@dailephd/my-dev-kit-lab 0.3.2 → 0.3.4

package/dist/src/audits/core/javaAnalyzer.js

@@ -0,0 +1,282 @@
+// ---------------------------------------------------------------------------
+// v0.3.3 Batch 1 -- conservative, dependency-free Java source analyzer.
+//
+// There is no Java compiler/parser available in this Node/TypeScript
+// project, and per this batch's scope this analyzer must not add a new
+// parser dependency (no javac, no javaparser-style library). Facts are
+// extracted with a deliberately narrow, brace-depth-tracking line scan --
+// not a real tokenizer, not an AST, and not a syntax validator. Same
+// LanguageAnalyzer contract, same SourceFileFacts shape, and the same
+// size-bounding philosophy as typescriptJavaScriptAnalyzer.ts/
+// pythonAnalyzer.ts, but confidence is necessarily lower since nothing here
+// proves the file is syntactically valid Java.
+//
+// What this DOES extract:
+//   - a single `package foo.bar;` declaration
+//   - `import foo.bar.Baz;` and `import static foo.bar.Baz.member;` (both
+//     recorded via the existing generic ImportFactKind "static" -- the same
+//     "resolved through a static, syntactic import statement" meaning
+//     already used by every other analyzer in this project, not a claim
+//     about Java's specific "import static" keyword)
+//   - top-level and nested class/interface/enum declarations
+//   - method and constructor declarations directly inside a class/
+//     interface/enum body (both recorded as DeclarationFactKind "method" --
+//     there is no dedicated constructor kind in the shared model, and
+//     "method" is a safe, non-overclaiming fit)
+//   - visibility (public/protected/private/package-private), folded into
+//     the existing `exported` boolean: `exported: true` only for an
+//     explicit `public` modifier, `false` for protected/private/
+//     package-private -- see "Visibility mapping" below for why no new
+//     schema field was added
+//   - line counts, parse/analyze status, and diagnostics for degraded
+//     parsing
+//
+// What this explicitly does NOT do: real Java compilation, type resolution,
+// symbol/overload resolution, inheritance analysis, annotation/framework
+// lifecycle understanding, runtime behavior, Gradle/Maven source-set
+// validation, semantic duplicate-implementation proof, or dead-code proof.
+// Field/property declarations are not extracted (out of this batch's
+// required scope, and harder to distinguish conservatively from local
+// variable declarations via regex alone). Java text blocks (`"""..."""`,
+// Java 15+) are not given special multi-line handling the way Kotlin's raw
+// strings are in kotlinAnalyzer.ts -- if present, a `{`/`}`/quote character
+// inside one could be slightly miscounted, which is an accepted, narrow
+// limitation of a regex/brace-counting scanner rather than a crash risk.
+//
+// Visibility mapping (no SourceFacts schema change):
+//   DeclarationFact has no dedicated visibility field, and per this batch's
+//   "prefer no schema change" guidance, none is added here. Java's four
+//   visibility levels collapse onto the existing boolean `exported` the
+//   same way the Python analyzer already folds its own export heuristic
+//   into that field: `public` -> true, everything else (protected/private/
+//   package-private) -> false. This intentionally loses the
+//   protected-vs-private-vs-package-private distinction; callers that need
+//   finer detail must re-derive it from source, which this analyzer does
+//   not claim to make unnecessary.
+// ---------------------------------------------------------------------------
+export const JAVA_ANALYZER_ID = "java-analyzer";
+const SUPPORTED_EXTENSIONS = [".java"];
+// Mirrors typescriptJavaScriptAnalyzer.ts/pythonAnalyzer.ts's bound.
+const MAX_ANALYZABLE_BYTES = 1_000_000;
+const PACKAGE_LINE_PATTERN = /^\s*package\s+([\w.]+)\s*;/;
+const IMPORT_LINE_PATTERN = /^\s*import\s+(static\s+)?([\w.]+(?:\.\*)?)\s*;/;
+// Requires an explicit visibility modifier to be captured separately so
+// "no modifier present" (package-private) is distinguishable from an
+// explicit one -- see MODIFIER_PATTERN below.
+const MODIFIER_WORDS = "(?:public|protected|private|static|final|abstract|sealed|non-sealed|strictfp|synchronized|native|default)";
+const TYPE_DECL_PATTERN = new RegExp(`^\\s*(?:${MODIFIER_WORDS}\\s+)*(class|interface|enum|record)\\s+(\\w+)`);
+// Two separate word-tokens (a return-type-like token, then the method name)
+// before the parameter list -- this is what keeps `if (...)`, `for (...)`,
+// `while (...)`, `switch (...)`, and plain method-call statements
+// (`foo.bar(x);`, a single dotted token with no preceding space) from ever
+// matching: those all have only one space-separated token before `(`.
+// The trailing group accepts either just an opening brace (multi-line
+// body), a semicolon (abstract/interface method declaration), or a full
+// one-liner body with no nested braces (e.g. `{ return true; }`, `{}`) --
+// without the last alternative, a common one-liner accessor/getter would
+// never be recognized as a declaration at all.
+const METHOD_LINE_PATTERN = new RegExp(`^\\s*(?:${MODIFIER_WORDS}\\s+)*[\\w<>\\[\\],.?]+\\s+(\\w+)\\s*\\(([^()]*)\\)\\s*(?:throws\\s+[\\w.,\\s<>]+)?\\s*(?:\\{[^{}]*\\}|\\{|;)\\s*$`);
+// A constructor has no return-type token: just an optional visibility
+// modifier, the identifier, then the parameter list. The caller only
+// accepts a match here when the identifier equals the enclosing class/
+// enum/record name, which is what actually distinguishes a real
+// constructor from a stray call-like statement (see analyzeFile below).
+const CONSTRUCTOR_LINE_PATTERN = /^\s*(?:(?:public|protected|private)\s+)?(\w+)\s*\(([^()]*)\)\s*(?:throws\s+[\w.,\s<>]+)?\s*(?:\{[^{}]*\}|\{)\s*$/;
+const EXPLICIT_MODIFIER_PATTERN = /(?:^|\s)(public|protected|private)(?:\s|$)/;
+export const JAVA_ANALYZER = {
+    id: JAVA_ANALYZER_ID,
+    supportedLanguages: ["java"],
+    supportedExtensions: SUPPORTED_EXTENSIONS,
+    analyzeFile,
+};
+function analyzeFile(input) {
+    const { relativePath, language, role, content, inventoryEntry } = input;
+    if (Buffer.byteLength(content, "utf8") > MAX_ANALYZABLE_BYTES) {
+        return {
+            relativePath,
+            language,
+            role,
+            parseStatus: "file-level-only",
+            analyzerId: JAVA_ANALYZER_ID,
+            lineCount: inventoryEntry.lineCount,
+            imports: [],
+            exports: [],
+            declarations: [],
+            references: [],
+            diagnostics: [
+                {
+                    severity: "info",
+                    code: "file-too-large-for-analysis",
+                    message: `File exceeds the ${MAX_ANALYZABLE_BYTES}-byte analyzer bound; only inventory-level facts are available.`,
+                    path: relativePath,
+                    analyzerId: JAVA_ANALYZER_ID,
+                },
+            ],
+        };
+    }
+    const diagnostics = [];
+    const { logical, hadUnterminatedBlockComment } = buildLogicalLines(content);
+    const imports = [];
+    const declarations = [];
+    const scopeStack = [];
+    let depth = 0;
+    let packageSeen = false;
+    for (let i = 0; i < logical.length; i++) {
+        const line = logical[i];
+        const lineNumber = i + 1;
+        if (line.trim().length === 0) {
+            continue;
+        }
+        if (!packageSeen) {
+            const packageMatch = line.match(PACKAGE_LINE_PATTERN);
+            if (packageMatch)
+                packageSeen = true;
+        }
+        const importMatch = line.match(IMPORT_LINE_PATTERN);
+        if (importMatch) {
+            imports.push({ source: importMatch[2], kind: "static", line: lineNumber });
+        }
+        const typeMatch = line.match(TYPE_DECL_PATTERN);
+        // "record" (a restricted, implicitly-final class variant) is folded
+        // into the existing "class" DeclarationFactKind/ScopeKind -- there is
+        // no dedicated record kind in the shared model, and "class" is a safe,
+        // non-overclaiming fit (a record's synthesized accessor/constructor
+        // methods are not separately modeled).
+        const normalizedKind = typeMatch ? (typeMatch[1] === "record" ? "class" : typeMatch[1]) : null;
+        if (typeMatch && normalizedKind) {
+            const name = typeMatch[2];
+            declarations.push({
+                name,
+                kind: normalizedKind,
+                exported: EXPLICIT_MODIFIER_PATTERN.exec(line.slice(0, typeMatch.index + typeMatch[0].length))?.[1] === "public",
+                line: lineNumber,
+            });
+        }
+        else if (scopeStack.length > 0 && depth === scopeStack[scopeStack.length - 1].bodyDepth) {
+            const currentScope = scopeStack[scopeStack.length - 1];
+            const methodMatch = line.match(METHOD_LINE_PATTERN);
+            if (methodMatch) {
+                pushMethodDeclaration(declarations, methodMatch[1], line, lineNumber);
+            }
+            else {
+                const ctorMatch = line.match(CONSTRUCTOR_LINE_PATTERN);
+                if (ctorMatch && ctorMatch[1] === currentScope.name) {
+                    pushMethodDeclaration(declarations, ctorMatch[1], line, lineNumber);
+                }
+            }
+        }
+        const depthBefore = depth;
+        depth += countChar(line, "{") - countChar(line, "}");
+        if (typeMatch && normalizedKind) {
+            // Always push assuming depth+1 is the body -- whether the opening
+            // brace was on this same line (K&R style, the common case) or a
+            // subsequent line (Allman style), the actual `{` character
+            // eventually seen will bump `depth` to exactly `depthBefore + 1`,
+            // matching this assumption either way.
+            scopeStack.push({ kind: normalizedKind, name: typeMatch[2], bodyDepth: depthBefore + 1 });
+        }
+        while (scopeStack.length > 0 && depth < scopeStack[scopeStack.length - 1].bodyDepth) {
+            scopeStack.pop();
+        }
+    }
+    if (hadUnterminatedBlockComment) {
+        diagnostics.push({
+            severity: "error",
+            code: "unterminated-block-comment",
+            message: "File appears to contain an unterminated /* block comment; facts from this best-effort scan may be incomplete.",
+            path: relativePath,
+            analyzerId: JAVA_ANALYZER_ID,
+        });
+    }
+    const parseStatus = hadUnterminatedBlockComment ? "parse-error" : "parsed";
+    return {
+        relativePath,
+        language,
+        role,
+        parseStatus,
+        analyzerId: JAVA_ANALYZER_ID,
+        lineCount: inventoryEntry.lineCount,
+        imports,
+        exports: [],
+        declarations,
+        references: [],
+        diagnostics,
+    };
+}
+function pushMethodDeclaration(declarations, name, line, lineNumber) {
+    const kind = "method";
+    declarations.push({
+        name,
+        kind,
+        exported: EXPLICIT_MODIFIER_PATTERN.exec(line)?.[1] === "public",
+        line: lineNumber,
+    });
+}
+function countChar(line, ch) {
+    let count = 0;
+    for (let i = 0; i < line.length; i++) {
+        if (line[i] === ch)
+            count += 1;
+    }
+    return count;
+}
+// ---------------------------------------------------------------------------
+// Comment/string stripping (heuristic, not a tokenizer). Strips `//` line
+// comments and `/* ... */` block comments (which may span multiple
+// lines), and blanks out the contents of `"..."` and `'...'` literals
+// (escape-aware) so a brace/quote character inside a string or comment can
+// never be misread as real code structure. Does not give Java 15+ text
+// blocks (`"""..."""`) special multi-line handling -- see this file's
+// header comment.
+// ---------------------------------------------------------------------------
+function buildLogicalLines(content) {
+    const rawLines = content.split(/\r\n|\r|\n/);
+    const logical = [];
+    let inBlockComment = false;
+    for (const rawLine of rawLines) {
+        logical.push(stripLine(rawLine));
+    }
+    return { logical, hadUnterminatedBlockComment: inBlockComment };
+    function stripLine(line) {
+        let result = "";
+        let i = 0;
+        while (i < line.length) {
+            if (inBlockComment) {
+                const closeIdx = line.indexOf("*/", i);
+                if (closeIdx === -1)
+                    return result;
+                inBlockComment = false;
+                i = closeIdx + 2;
+                continue;
+            }
+            const ch = line[i];
+            if (ch === "/" && line[i + 1] === "/")
+                return result;
+            if (ch === "/" && line[i + 1] === "*") {
+                inBlockComment = true;
+                i += 2;
+                continue;
+            }
+            if (ch === '"' || ch === "'") {
+                const quote = ch;
+                let j = i + 1;
+                while (j < line.length) {
+                    if (line[j] === "\\") {
+                        j += 2;
+                        continue;
+                    }
+                    if (line[j] === quote) {
+                        j += 1;
+                        break;
+                    }
+                    j += 1;
+                }
+                i = j;
+                continue;
+            }
+            result += ch;
+            i += 1;
+        }
+        return result;
+    }
+}

package/dist/src/audits/core/jvmProjectMetadata.js

@@ -0,0 +1,106 @@
+import fs from "node:fs";
+import path from "node:path";
+const GRADLE_BUILD_FILE_NAMES = new Set(["build.gradle", "build.gradle.kts"]);
+const GRADLE_SETTINGS_FILE_NAMES = new Set(["settings.gradle", "settings.gradle.kts"]);
+const GRADLE_WRAPPER_FILE_NAMES = new Set(["gradlew", "gradlew.bat"]);
+// Conservative, single-line extraction: `rootProject.name = "foo"` (Groovy
+// or Kotlin DSL both use this exact call-and-assign shape). Does not handle
+// multi-line expressions, string concatenation, or computed values.
+const GRADLE_SETTINGS_PROJECT_NAME_PATTERN = /rootProject\.name\s*=\s*["']([^"']+)["']/;
+// Conservative, single-line/non-nested extraction: the first top-level
+// `<artifactId>...</artifactId>` in the file. Real pom.xml can nest an
+// `<artifactId>` inside `<parent>` or `<dependencies>`, which this naive
+// first-match scan cannot distinguish -- so this is intentionally treated as
+// best-effort only, matching this module's "leave null rather than guess"
+// policy for anything structurally ambiguous. A `<parent>` block, if present
+// before the project's own `<artifactId>`, is skipped over so the far more
+// common case (parent declared first, then the project's own coordinates)
+// resolves to the right value instead of the parent's.
+const POM_ARTIFACT_ID_PATTERN = /<artifactId>\s*([^<\s][^<]*?)\s*<\/artifactId>/;
+function findSourceSetDirectories(inventory, segment, language) {
+    const dirName = `src/${segment}/${language}`;
+    const prefix = `${dirName}/`;
+    const found = inventory.files.some((f) => f.relativePath === dirName || f.relativePath.startsWith(prefix));
+    return found ? [dirName] : [];
+}
+export function collectJvmProjectMetadata(targetRoot, inventory) {
+    const warnings = [];
+    const knownPaths = new Set(inventory.files.map((f) => f.relativePath));
+    const recognizedBuildFiles = inventory.files
+        .map((f) => f.relativePath)
+        .filter((relativePath) => {
+        const basename = path.posix.basename(relativePath);
+        return (GRADLE_BUILD_FILE_NAMES.has(basename) ||
+            GRADLE_SETTINGS_FILE_NAMES.has(basename) ||
+            GRADLE_WRAPPER_FILE_NAMES.has(basename) ||
+            basename === "pom.xml" ||
+            basename === "gradle.properties");
+    })
+        .sort((a, b) => a.localeCompare(b));
+    const hasGradleBuild = recognizedBuildFiles.some((p) => GRADLE_BUILD_FILE_NAMES.has(path.posix.basename(p)));
+    const hasGradleSettings = recognizedBuildFiles.some((p) => GRADLE_SETTINGS_FILE_NAMES.has(path.posix.basename(p)));
+    const hasMavenPom = knownPaths.has("pom.xml");
+    const hasGradleWrapper = recognizedBuildFiles.some((p) => GRADLE_WRAPPER_FILE_NAMES.has(path.posix.basename(p)));
+    const javaSourceDirs = findSourceSetDirectories(inventory, "main", "java");
+    const kotlinSourceDirs = findSourceSetDirectories(inventory, "main", "kotlin");
+    const javaTestDirs = findSourceSetDirectories(inventory, "test", "java");
+    const kotlinTestDirs = findSourceSetDirectories(inventory, "test", "kotlin");
+    // Source-set directory presence is a conservative signal only -- a
+    // project can validly keep Java/Kotlin files outside the conventional
+    // src/main|test/{java,kotlin} layout, so this does not attempt to prove
+    // "has no Java/Kotlin source"; it only reports the conventional-layout
+    // signal explicitly. hasJavaSource/hasKotlinSource below fall back to any
+    // scanned file of that language so they stay meaningful even for
+    // non-conventional layouts.
+    const hasJavaSource = javaSourceDirs.length > 0 || inventory.filesByLanguage.java > 0;
+    const hasKotlinSource = kotlinSourceDirs.length > 0 || inventory.filesByLanguage.kotlin > 0;
+    const hasJavaTests = javaTestDirs.length > 0;
+    const hasKotlinTests = kotlinTestDirs.length > 0;
+    const recognizedSourceDirectories = [...new Set([...javaSourceDirs, ...kotlinSourceDirs])].sort((a, b) => a.localeCompare(b));
+    const recognizedTestDirectories = [...new Set([...javaTestDirs, ...kotlinTestDirs])].sort((a, b) => a.localeCompare(b));
+    let projectName = null;
+    if (hasGradleSettings) {
+        const settingsPath = recognizedBuildFiles.find((p) => GRADLE_SETTINGS_FILE_NAMES.has(path.posix.basename(p)));
+        if (settingsPath) {
+            const content = readSafely(targetRoot, settingsPath, warnings);
+            if (content !== null) {
+                const match = content.match(GRADLE_SETTINGS_PROJECT_NAME_PATTERN);
+                if (match)
+                    projectName = match[1];
+            }
+        }
+    }
+    if (projectName === null && hasMavenPom) {
+        const content = readSafely(targetRoot, "pom.xml", warnings);
+        if (content !== null) {
+            const withoutParentBlock = content.replace(/<parent>[\s\S]*?<\/parent>/, "");
+            const match = withoutParentBlock.match(POM_ARTIFACT_ID_PATTERN);
+            if (match)
+                projectName = match[1];
+        }
+    }
+    return {
+        hasGradleBuild,
+        hasGradleSettings,
+        hasMavenPom,
+        hasGradleWrapper,
+        hasJavaSource,
+        hasKotlinSource,
+        hasJavaTests,
+        hasKotlinTests,
+        recognizedBuildFiles,
+        recognizedSourceDirectories,
+        recognizedTestDirectories,
+        projectName,
+        warnings,
+    };
+}
+function readSafely(targetRoot, relativePath, warnings) {
+    try {
+        return fs.readFileSync(path.join(targetRoot, relativePath), "utf8");
+    }
+    catch (err) {
+        warnings.push(`Could not read ${relativePath}: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}

package/dist/src/audits/core/kotlinAnalyzer.js

@@ -0,0 +1,280 @@
+// ---------------------------------------------------------------------------
+// v0.3.3 Batch 1 -- conservative, dependency-free Kotlin source analyzer.
+//
+// There is no Kotlin compiler/parser available in this Node/TypeScript
+// project, and per this batch's scope this analyzer must not add a new
+// parser dependency. Facts are extracted with the same style of
+// brace-depth-tracking line scan as javaAnalyzer.ts -- not a real
+// tokenizer, not an AST, and not a syntax validator.
+//
+// What this DOES extract:
+//   - a single `package foo.bar` declaration (no trailing `;` required)
+//   - `import foo.bar.Baz` and `import foo.bar.Baz as Alias` (recorded via
+//     the existing generic ImportFactKind "static" -- "resolved through a
+//     static, syntactic import statement", the same meaning already used
+//     by every other analyzer in this project)
+//   - class, data class, interface, and object declarations (data class ->
+//     DeclarationFactKind "class"; object -> "class", the closest safe
+//     existing kind for a singleton declaration -- there is no dedicated
+//     object kind in the shared model)
+//   - `enum class Foo` -> DeclarationFactKind "enum"
+//   - top-level function declarations (`fun foo(...)`) -> kind "function"
+//   - member function declarations directly inside a class/interface/
+//     object body -> kind "method"
+//   - visibility (public/internal/protected/private), folded into the
+//     existing `exported` boolean -- see "Visibility mapping" below
+//   - line counts, parse/analyze status, and diagnostics for degraded
+//     parsing
+//
+// What this explicitly does NOT do: real Kotlin compilation, type
+// inference, extension-function semantic resolution (an extension
+// function's receiver type is not modeled -- only the function's own
+// identifier is recorded as its name), coroutine behavior, multiplatform
+// source-set semantics, Android/Compose lifecycle behavior, runtime
+// behavior, semantic duplicate-implementation proof, or dead-code proof.
+// Property (`val`/`var`) declarations are not extracted (out of this
+// batch's required scope, and harder to distinguish conservatively from
+// local variable declarations via regex alone).
+//
+// Visibility mapping (no SourceFacts schema change):
+//   Same reasoning as javaAnalyzer.ts. Kotlin's default (no modifier) is
+//   `public`, unlike Java's package-private default -- so `exported` is
+//   true unless an explicit `internal`, `protected`, or `private` modifier
+//   is present. This intentionally collapses internal/protected/private
+//   into a single "not exported" bucket; callers needing that distinction
+//   must re-derive it from source.
+// ---------------------------------------------------------------------------
+export const KOTLIN_ANALYZER_ID = "kotlin-analyzer";
+const SUPPORTED_EXTENSIONS = [".kt", ".kts"];
+// Mirrors typescriptJavaScriptAnalyzer.ts/pythonAnalyzer.ts/javaAnalyzer.ts's
+// bound.
+const MAX_ANALYZABLE_BYTES = 1_000_000;
+const PACKAGE_LINE_PATTERN = /^\s*package\s+([\w.]+)\s*;?\s*$/;
+const IMPORT_LINE_PATTERN = /^\s*import\s+([\w.]+(?:\.\*)?)(?:\s+as\s+(\w+))?\s*;?\s*$/;
+const VISIBILITY_WORDS = "(?:public|internal|protected|private)";
+const OTHER_TYPE_MODIFIER_WORDS = "(?:open|final|abstract|sealed|inner|data|annotation|enum|companion|value|actual|expect)";
+const TYPE_DECL_PATTERN = new RegExp(`^\\s*(${VISIBILITY_WORDS}\\s+)?((?:${OTHER_TYPE_MODIFIER_WORDS}\\s+)*)(class|interface|object)\\s+(\\w+)`);
+// Optional generic receiver/type parameters and an optional extension-
+// function receiver (`ReceiverType.`) before the function name -- the
+// receiver itself is discarded, only the final identifier is kept as the
+// function's name (see header comment).
+const FUN_LINE_PATTERN = new RegExp(`^\\s*(${VISIBILITY_WORDS}\\s+)?(?:(?:override|open|final|abstract|inline|suspend|operator|infix|tailrec|external)\\s+)*fun(?:\\s*<[^>]*>)?\\s+(?:[\\w<>?.]+\\.)?(\\w+)\\s*\\(`);
+export const KOTLIN_ANALYZER = {
+    id: KOTLIN_ANALYZER_ID,
+    supportedLanguages: ["kotlin"],
+    supportedExtensions: SUPPORTED_EXTENSIONS,
+    analyzeFile,
+};
+function analyzeFile(input) {
+    const { relativePath, language, role, content, inventoryEntry } = input;
+    if (Buffer.byteLength(content, "utf8") > MAX_ANALYZABLE_BYTES) {
+        return {
+            relativePath,
+            language,
+            role,
+            parseStatus: "file-level-only",
+            analyzerId: KOTLIN_ANALYZER_ID,
+            lineCount: inventoryEntry.lineCount,
+            imports: [],
+            exports: [],
+            declarations: [],
+            references: [],
+            diagnostics: [
+                {
+                    severity: "info",
+                    code: "file-too-large-for-analysis",
+                    message: `File exceeds the ${MAX_ANALYZABLE_BYTES}-byte analyzer bound; only inventory-level facts are available.`,
+                    path: relativePath,
+                    analyzerId: KOTLIN_ANALYZER_ID,
+                },
+            ],
+        };
+    }
+    const diagnostics = [];
+    const { logical, hadUnterminatedBlockComment, hadUnterminatedRawString } = buildLogicalLines(content);
+    const imports = [];
+    const declarations = [];
+    const scopeStack = [];
+    let depth = 0;
+    for (let i = 0; i < logical.length; i++) {
+        const line = logical[i];
+        const lineNumber = i + 1;
+        if (line.trim().length === 0) {
+            continue;
+        }
+        const importMatch = line.match(IMPORT_LINE_PATTERN);
+        if (importMatch) {
+            imports.push({
+                source: importMatch[1],
+                kind: "static",
+                line: lineNumber,
+                ...(importMatch[2] ? { importedNames: [importMatch[2]] } : {}),
+            });
+        }
+        const typeMatch = line.match(TYPE_DECL_PATTERN);
+        let isEnumClass = false;
+        if (typeMatch) {
+            isEnumClass = /(?:^|\s)enum(?:\s|$)/.test(typeMatch[2]);
+        }
+        if (typeMatch) {
+            const rawKeyword = typeMatch[3]; // "class" | "interface" | "object"
+            const name = typeMatch[4];
+            const exported = typeMatch[1] === undefined || typeMatch[1].trim() === "public";
+            declarations.push({
+                name,
+                kind: isEnumClass ? "enum" : rawKeyword === "interface" ? "interface" : "class",
+                exported,
+                line: lineNumber,
+            });
+        }
+        else if (scopeStack.length > 0 && depth === scopeStack[scopeStack.length - 1].bodyDepth) {
+            const funMatch = line.match(FUN_LINE_PATTERN);
+            if (funMatch) {
+                const exported = funMatch[1] === undefined || funMatch[1].trim() === "public";
+                declarations.push({ name: funMatch[2], kind: "method", exported, line: lineNumber });
+            }
+        }
+        else if (scopeStack.length === 0) {
+            const funMatch = line.match(FUN_LINE_PATTERN);
+            if (funMatch) {
+                const exported = funMatch[1] === undefined || funMatch[1].trim() === "public";
+                declarations.push({ name: funMatch[2], kind: "function", exported, line: lineNumber });
+            }
+        }
+        const depthBefore = depth;
+        depth += countChar(line, "{") - countChar(line, "}");
+        if (typeMatch) {
+            const rawKeyword = typeMatch[3];
+            // class/object and interface both get a scope frame ("object" is
+            // tracked as a "class"-kind scope for member-function purposes);
+            // whether the opening `{` lands on this line or a later one, the
+            // eventual `{` bumps depth to exactly depthBefore + 1 either way --
+            // same reasoning as javaAnalyzer.ts's scope push.
+            const scopeKind = rawKeyword === "interface" ? "interface" : "class";
+            scopeStack.push({ kind: scopeKind, bodyDepth: depthBefore + 1 });
+        }
+        while (scopeStack.length > 0 && depth < scopeStack[scopeStack.length - 1].bodyDepth) {
+            scopeStack.pop();
+        }
+    }
+    if (hadUnterminatedRawString) {
+        diagnostics.push({
+            severity: "error",
+            code: "unterminated-raw-string",
+            message: 'File appears to contain an unterminated """ raw string; facts from this best-effort scan may be incomplete.',
+            path: relativePath,
+            analyzerId: KOTLIN_ANALYZER_ID,
+        });
+    }
+    if (hadUnterminatedBlockComment) {
+        diagnostics.push({
+            severity: "error",
+            code: "unterminated-block-comment",
+            message: "File appears to contain an unterminated /* block comment; facts from this best-effort scan may be incomplete.",
+            path: relativePath,
+            analyzerId: KOTLIN_ANALYZER_ID,
+        });
+    }
+    const parseStatus = hadUnterminatedRawString || hadUnterminatedBlockComment ? "parse-error" : "parsed";
+    return {
+        relativePath,
+        language,
+        role,
+        parseStatus,
+        analyzerId: KOTLIN_ANALYZER_ID,
+        lineCount: inventoryEntry.lineCount,
+        imports,
+        exports: [],
+        declarations,
+        references: [],
+        diagnostics,
+    };
+}
+function countChar(line, ch) {
+    let count = 0;
+    for (let i = 0; i < line.length; i++) {
+        if (line[i] === ch)
+            count += 1;
+    }
+    return count;
+}
+// ---------------------------------------------------------------------------
+// Comment/string stripping (heuristic, not a tokenizer). Strips `//` line
+// comments and `/* ... */` block comments (which may span multiple lines),
+// blanks out `"..."`/`'...'` single-line literal contents (escape-aware),
+// and blanks out `"""..."""` raw strings (which may span multiple lines,
+// no escape processing inside -- mirrors pythonAnalyzer.ts's triple-quote
+// handling, since Kotlin raw strings share the same "arbitrary content
+// until the next matching triple-quote marker" shape).
+// ---------------------------------------------------------------------------
+function buildLogicalLines(content) {
+    const rawLines = content.split(/\r\n|\r|\n/);
+    const logical = [];
+    let inBlockComment = false;
+    let inRawString = false;
+    for (const rawLine of rawLines) {
+        if (inRawString) {
+            const closeIdx = rawLine.indexOf('"""');
+            if (closeIdx === -1) {
+                logical.push("");
+                continue;
+            }
+            inRawString = false;
+            logical.push(stripLine(rawLine.slice(closeIdx + 3)));
+            continue;
+        }
+        logical.push(stripLine(rawLine));
+    }
+    return { logical, hadUnterminatedBlockComment: inBlockComment, hadUnterminatedRawString: inRawString };
+    function stripLine(line) {
+        let result = "";
+        let i = 0;
+        while (i < line.length) {
+            if (inBlockComment) {
+                const closeIdx = line.indexOf("*/", i);
+                if (closeIdx === -1)
+                    return result;
+                inBlockComment = false;
+                i = closeIdx + 2;
+                continue;
+            }
+            const ch = line[i];
+            if (ch === "/" && line[i + 1] === "/")
+                return result;
+            if (ch === "/" && line[i + 1] === "*") {
+                inBlockComment = true;
+                i += 2;
+                continue;
+            }
+            if (line.slice(i, i + 3) === '"""') {
+                const closeIdx = line.indexOf('"""', i + 3);
+                if (closeIdx === -1) {
+                    inRawString = true;
+                    return result;
+                }
+                i = closeIdx + 3;
+                continue;
+            }
+            if (ch === '"' || ch === "'") {
+                const quote = ch;
+                let j = i + 1;
+                while (j < line.length) {
+                    if (line[j] === "\\") {
+                        j += 2;
+                        continue;
+                    }
+                    if (line[j] === quote) {
+                        j += 1;
+                        break;
+                    }
+                    j += 1;
+                }
+                i = j;
+                continue;
+            }
+            result += ch;
+            i += 1;
+        }
+        return result;
+    }
+}