@dailephd/my-dev-kit-lab 0.2.2 → 0.3.1

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

@@ -0,0 +1,339 @@
+import fs from "node:fs";
+import path from "node:path";
+import { splitLines } from "./textLines.js";
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 2 — source-of-truth collector.
+//
+// Reads package.json/package-lock.json/docs/CI-workflow/config *facts* only.
+// Never executes a command, never calls security:validate or an experiment
+// command, and never produces an AuditIssue -- this is data collection for
+// later detector batches to consume, same spirit as projectInventory.ts.
+// Reuses the already-computed ProjectInventorySnapshot for file discovery
+// (docs/ci/test file lists) rather than re-walking the filesystem.
+// ---------------------------------------------------------------------------
+export const SCRIPT_GROUPS = ["build", "test", "security", "experiment", "audit", "docs", "release", "other"];
+const MAX_DOCS_READ_BYTES = 200_000;
+const MAX_CI_READ_BYTES = 100_000;
+export function collectSourceOfTruth(targetRoot, inventory) {
+    const resolvedRoot = path.resolve(targetRoot);
+    const warnings = [];
+    const pkg = readPackageTruth(resolvedRoot, warnings);
+    const lockfile = readLockfileTruth(resolvedRoot, pkg, warnings);
+    const commands = classifyCommands(pkg);
+    const docs = readDocsTruth(resolvedRoot, inventory, warnings);
+    const ci = readCiTruth(resolvedRoot, inventory, warnings);
+    const buildTooling = readBuildToolingTruth(inventory, pkg);
+    const tests = readTestTruth(inventory);
+    const security = readSecurityTruth(resolvedRoot, pkg);
+    const experiment = readExperimentTruth(resolvedRoot, pkg);
+    return {
+        targetRoot: resolvedRoot,
+        package: pkg,
+        lockfile,
+        commands,
+        docs,
+        ci,
+        buildTooling,
+        tests,
+        security,
+        experiment,
+        warnings,
+    };
+}
+function readPackageTruth(targetRoot, warnings) {
+    const pkgPath = path.join(targetRoot, "package.json");
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    try {
+        return {
+            name: typeof raw.name === "string" ? raw.name : null,
+            version: typeof raw.version === "string" ? raw.version : null,
+            description: typeof raw.description === "string" ? raw.description : null,
+            bin: isRecordOfStrings(raw.bin) || typeof raw.bin === "string" ? raw.bin : null,
+            main: typeof raw.main === "string" ? raw.main : null,
+            module: typeof raw.module === "string" ? raw.module : null,
+            types: typeof raw.types === "string" ? raw.types : typeof raw.typings === "string" ? raw.typings : null,
+            scripts: isRecordOfStrings(raw.scripts) ? raw.scripts : {},
+            dependencies: isRecordOfStrings(raw.dependencies) ? raw.dependencies : {},
+            devDependencies: isRecordOfStrings(raw.devDependencies) ? raw.devDependencies : {},
+            peerDependencies: isRecordOfStrings(raw.peerDependencies) ? raw.peerDependencies : null,
+            engines: isRecordOfStrings(raw.engines) ? raw.engines : null,
+            files: Array.isArray(raw.files) ? raw.files.filter((f) => typeof f === "string") : null,
+            packageManagerHint: typeof raw.packageManager === "string" ? raw.packageManager : null,
+        };
+    }
+    catch (err) {
+        warnings.push(`Could not fully parse package.json fields: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+function isRecordOfStrings(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    return Object.values(value).every((v) => typeof v === "string");
+}
+function readLockfileTruth(targetRoot, pkg, warnings) {
+    const lockPath = path.join(targetRoot, "package-lock.json");
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+    }
+    catch {
+        return { present: false, rootName: null, rootVersion: null, lockfileVersion: null, packageManagerConsistent: null };
+    }
+    try {
+        const rootPackageEntry = raw.packages?.[""];
+        const rootName = typeof raw.name === "string" ? raw.name : typeof rootPackageEntry?.name === "string" ? rootPackageEntry.name : null;
+        const rootVersion = typeof raw.version === "string" ? raw.version : typeof rootPackageEntry?.version === "string" ? rootPackageEntry.version : null;
+        const lockfileVersion = typeof raw.lockfileVersion === "number" ? raw.lockfileVersion : null;
+        const packageManagerConsistent = pkg?.name != null && rootName != null ? pkg.name === rootName && pkg.version === rootVersion : null;
+        return { present: true, rootName, rootVersion, lockfileVersion, packageManagerConsistent };
+    }
+    catch (err) {
+        warnings.push(`Could not fully parse package-lock.json fields: ${err instanceof Error ? err.message : String(err)}`);
+        return { present: true, rootName: null, rootVersion: null, lockfileVersion: null, packageManagerConsistent: null };
+    }
+}
+// ---------------------------------------------------------------------------
+// Command/script truth
+// ---------------------------------------------------------------------------
+function classifyScriptGroup(scriptName) {
+    const name = scriptName.toLowerCase();
+    if (name.startsWith("security") || name === "test:security" || name.startsWith("test:fuzz"))
+        return "security";
+    if (name.startsWith("experiment"))
+        return "experiment";
+    if (name === "audit" || name.startsWith("audit:"))
+        return "audit";
+    if (name === "test" || name.startsWith("test:"))
+        return "test";
+    if (name === "build" || name === "typecheck" || name === "clean" || name.includes("build"))
+        return "build";
+    if (name.includes("doc"))
+        return "docs";
+    if (name.includes("release") || name.includes("publish") || name.includes("pack") || name.includes("version")) {
+        return "release";
+    }
+    return "other";
+}
+function classifyCommands(pkg) {
+    const scriptsByGroup = Object.fromEntries(SCRIPT_GROUPS.map((g) => [g, []]));
+    if (!pkg) {
+        return { scriptsByGroup, allScriptNames: [] };
+    }
+    const allScriptNames = Object.keys(pkg.scripts).sort((a, b) => a.localeCompare(b));
+    for (const name of allScriptNames) {
+        scriptsByGroup[classifyScriptGroup(name)].push(name);
+    }
+    return { scriptsByGroup, allScriptNames };
+}
+// ---------------------------------------------------------------------------
+// Docs truth
+// ---------------------------------------------------------------------------
+function readDocsTruth(targetRoot, inventory, warnings) {
+    const files = [];
+    let hasReadme = false;
+    let hasChangelog = false;
+    for (const entry of inventory.docsFiles) {
+        const basename = path.basename(entry.relativePath).toLowerCase();
+        if (basename === "readme.md")
+            hasReadme = true;
+        if (basename === "changelog.md")
+            hasChangelog = true;
+        const fullPath = path.join(targetRoot, entry.relativePath);
+        let content = "";
+        try {
+            if (entry.sizeBytes <= MAX_DOCS_READ_BYTES) {
+                content = fs.readFileSync(fullPath, "utf8");
+            }
+        }
+        catch (err) {
+            warnings.push(`Could not read docs file: ${entry.relativePath} (${err instanceof Error ? err.message : String(err)})`);
+        }
+        const titleMatch = content.match(/^#\s+(.+)$/m);
+        files.push({
+            relativePath: entry.relativePath,
+            title: titleMatch ? titleMatch[1].trim() : null,
+            mentionsAudit: /\baudit\b/i.test(content),
+            mentionsSecurityValidation: /security[- ]?valid|security:validate/i.test(content),
+            mentionsExperiments: /\bexperiment/i.test(content),
+            mentionsReleasePublish: /\b(release|publish|npm publish)\b/i.test(content),
+            mentionsPlannedCommands: /\bplanned\b/i.test(content),
+            mentionsCurrentCommands: /\bcurrent\b/i.test(content),
+        });
+    }
+    files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+    return { files, hasReadme, hasChangelog };
+}
+// ---------------------------------------------------------------------------
+// CI/workflow truth
+// ---------------------------------------------------------------------------
+function readCiTruth(targetRoot, inventory, warnings) {
+    const workflows = [];
+    for (const entry of inventory.ciFiles) {
+        const fullPath = path.join(targetRoot, entry.relativePath);
+        let content = "";
+        try {
+            if (entry.sizeBytes <= MAX_CI_READ_BYTES) {
+                content = fs.readFileSync(fullPath, "utf8");
+            }
+        }
+        catch (err) {
+            warnings.push(`Could not read workflow file: ${entry.relativePath} (${err instanceof Error ? err.message : String(err)})`);
+        }
+        workflows.push({
+            relativePath: entry.relativePath,
+            name: parseWorkflowName(content),
+            nodeVersionsReferenced: parseNodeVersions(content),
+            packageManagerCommandsReferenced: parsePackageManagerCommands(content),
+            npmScriptsReferenced: parseNpmScriptsReferenced(content),
+        });
+    }
+    workflows.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+    return { workflows };
+}
+function parseWorkflowName(content) {
+    const match = content.match(/^name:\s*(.+)$/m);
+    return match ? match[1].trim() : null;
+}
+function parseNodeVersions(content) {
+    const versions = new Set();
+    // Inline form: node-version: 20
+    for (const match of content.matchAll(/node-version:\s*["']?([\w.]+)["']?\s*$/gm)) {
+        versions.add(match[1]);
+    }
+    // List form:
+    //   node-version:
+    //     - 20
+    //     - 22
+    // v0.3.0 Batch 6 — use the canonical splitLines() helper instead of a raw
+    // string split on a newline character, so CRLF-authored workflow files
+    // (trailing carriage-return on every line) don't silently break the
+    // list-item regex below (see src/audits/core/textLines.ts's header
+    // comment). A bare split here is also exactly what
+    // crossPlatformRotDetector.ts's raw-split-detection check flags in any
+    // other src/audits/ file.
+    const lines = splitLines(content);
+    for (let i = 0; i < lines.length; i++) {
+        if (/node-version:\s*$/.test(lines[i])) {
+            for (let j = i + 1; j < lines.length; j++) {
+                const listItem = lines[j].match(/^\s*-\s*["']?([\w.]+)["']?\s*$/);
+                if (!listItem)
+                    break;
+                versions.add(listItem[1]);
+            }
+        }
+    }
+    return [...versions].sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+}
+function parsePackageManagerCommands(content) {
+    const commands = new Set();
+    for (const match of content.matchAll(/\bnpm (ci|install|publish|pack|audit|outdated)\b/g)) {
+        commands.add(`npm ${match[1]}`);
+    }
+    for (const match of content.matchAll(/\bnpx [\w.:-]+/g)) {
+        commands.add(match[0].trim());
+    }
+    return [...commands].sort((a, b) => a.localeCompare(b));
+}
+function parseNpmScriptsReferenced(content) {
+    const scripts = new Set();
+    for (const match of content.matchAll(/\bnpm run ([\w:.-]+)/g)) {
+        scripts.add(match[1]);
+    }
+    return [...scripts].sort((a, b) => a.localeCompare(b));
+}
+// ---------------------------------------------------------------------------
+// Build tooling truth
+// ---------------------------------------------------------------------------
+function readBuildToolingTruth(inventory, pkg) {
+    const tsconfigPaths = inventory.files
+        .filter((f) => /^tsconfig(\..+)?\.json$/.test(path.basename(f.relativePath)))
+        .map((f) => f.relativePath)
+        .sort((a, b) => a.localeCompare(b));
+    const vitestConfigPaths = inventory.files
+        .filter((f) => /^vitest\.config\.[jt]s$/.test(path.basename(f.relativePath)) || path.basename(f.relativePath) === "vitest.workspace.ts")
+        .map((f) => f.relativePath)
+        .sort((a, b) => a.localeCompare(b));
+    const eslintConfigPaths = inventory.files
+        .filter((f) => /^\.eslintrc(\..+)?$/.test(path.basename(f.relativePath)) || /^eslint\.config\.[jt]s$/.test(path.basename(f.relativePath)))
+        .map((f) => f.relativePath)
+        .sort((a, b) => a.localeCompare(b));
+    const scripts = pkg?.scripts ?? {};
+    return {
+        hasTsconfig: tsconfigPaths.length > 0,
+        tsconfigPaths,
+        hasVitestConfig: vitestConfigPaths.length > 0,
+        vitestConfigPaths,
+        hasEslintConfig: eslintConfigPaths.length > 0,
+        eslintConfigPaths,
+        hasBuildScript: "build" in scripts,
+        hasTypecheckScript: "typecheck" in scripts,
+        hasTestScript: "test" in scripts,
+    };
+}
+// ---------------------------------------------------------------------------
+// Test truth
+// ---------------------------------------------------------------------------
+function readTestTruth(inventory) {
+    const testFilesByTopLevelArea = {};
+    let auditTestFileCount = 0;
+    let securityTestFileCount = 0;
+    let experimentTestFileCount = 0;
+    for (const file of inventory.testFiles) {
+        const match = file.relativePath.match(/^tests\/([^/]+)\//);
+        const area = match ? match[1] : "other";
+        testFilesByTopLevelArea[area] = (testFilesByTopLevelArea[area] ?? 0) + 1;
+        if (area === "audits")
+            auditTestFileCount += 1;
+        if (area === "security")
+            securityTestFileCount += 1;
+        if (area === "experiments")
+            experimentTestFileCount += 1;
+    }
+    const orderedAreas = Object.fromEntries(Object.entries(testFilesByTopLevelArea).sort(([a], [b]) => a.localeCompare(b)));
+    return {
+        totalTestFileCount: inventory.testFiles.length,
+        auditTestFileCount,
+        securityTestFileCount,
+        experimentTestFileCount,
+        testFilesByTopLevelArea: orderedAreas,
+    };
+}
+// ---------------------------------------------------------------------------
+// Security / experiment truth (script + directory presence only)
+// ---------------------------------------------------------------------------
+function readSecurityTruth(targetRoot, pkg) {
+    const scripts = pkg?.scripts ?? {};
+    return {
+        hasSecurityValidateScript: "security:validate" in scripts,
+        hasSecurityDepsScript: "security:deps" in scripts,
+        hasSecurityPackageScript: "security:package" in scripts,
+        hasSecurityCodeqlScript: "security:codeql" in scripts,
+        hasSecuritySemgrepScript: "security:semgrep" in scripts,
+        hasTestSecurityScript: "test:security" in scripts,
+        hasSecurityValidationSourceDir: dirExists(path.join(targetRoot, "src", "securityValidation")),
+    };
+}
+function readExperimentTruth(targetRoot, pkg) {
+    const scripts = pkg?.scripts ?? {};
+    return {
+        hasExperimentListScript: "experiment:list" in scripts,
+        hasExperimentDescribeScript: "experiment:describe" in scripts,
+        hasExperimentRunScript: "experiment:run" in scripts,
+        hasExperimentsSourceDir: dirExists(path.join(targetRoot, "src", "experiments")),
+    };
+}
+function dirExists(dirPath) {
+    try {
+        return fs.statSync(dirPath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,24 @@
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 6 — canonical, core-level line-splitting helper.
+//
+// Moved here from src/audits/codeRot/utils/textLines.ts (Batch 3), because
+// src/audits/core/sourceOfTruth.ts (a core-level module) needed the same
+// CRLF-safe splitting behavior for parseNodeVersions()'s list-form
+// "node-version:\n  - 20\n  - 22" parsing, and core/ depending on
+// codeRot/utils/ would be architecturally backwards (core is lower-level
+// than codeRot). This is now the single canonical implementation; the
+// codeRot-side module re-exports it so no existing detector import path
+// changes (see src/audits/codeRot/utils/textLines.ts).
+//
+// Windows-authored files in this repo (e.g. docs/ROADMAP.md) commonly have
+// CRLF line endings. A plain content.split("\n") leaves a trailing "\r" on
+// every line, which silently breaks any "$"-anchored regex against that
+// line (JS regex "." does not match "\r", a line terminator character) --
+// discovered via a real false negative where a heading-tracking regex
+// matched zero headings in a CRLF file. Every module that splits doc/text
+// content into lines must go through this helper instead of a bare
+// .split("\n").
+// ---------------------------------------------------------------------------
+export function splitLines(content) {
+    return content.replace(/\r\n/g, "\n").split("\n");
+}

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

@@ -0,0 +1,299 @@
+import ts from "typescript";
+// ---------------------------------------------------------------------------
+// v0.3.1 Batch 3 -- TypeScript/JavaScript source analyzer.
+//
+// Single-file, syntax-only analysis via the TypeScript compiler API:
+//   - ts.createSourceFile() builds a per-file AST (no Program, no project
+//     resolution, no type checking) that is walked once to extract facts.
+//   - ts.transpileModule({ reportDiagnostics: true }) is used purely to
+//     obtain syntactic diagnostics -- it is itself a single-file operation
+//     (no cross-file resolution), matching the "single-file parsing only"
+//     requirement for this batch.
+//
+// Parse-status policy (deliberately conservative, see docs on
+// SourceFactParseStatus): zero syntax diagnostics -> "parsed". Any syntax
+// diagnostic -> "parse-error", even though the AST walk below still runs
+// against TypeScript's best-effort (error-tolerant) parse and whatever facts
+// it manages to extract are still attached -- the parseStatus signals
+// "don't treat these facts as fully reliable", not "no facts exist". This
+// mirrors how collectSourceFacts.ts already reports a caught analyzer
+// exception as parse-error with an empty-fact fallback -- this analyzer just
+// reaches parse-error through diagnostics instead of a thrown exception, and
+// still gets to keep best-effort facts (which a thrown-exception parse-error
+// never has, since collectSourceFacts.ts only has the exception itself).
+// ---------------------------------------------------------------------------
+export const TYPESCRIPT_JAVASCRIPT_ANALYZER_ID = "typescript-javascript-analyzer";
+const SUPPORTED_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
+// AST construction is meaningfully more expensive than a line count -- large
+// files (generated bundles, vendored single-file libraries that slipped past
+// role/path exclusions, etc.) are not parsed. Mirrors the size-bounding
+// philosophy of projectInventory.ts's own read limits, just at a tighter
+// threshold appropriate for actually building an AST.
+const MAX_ANALYZABLE_BYTES = 1_000_000;
+export const TYPESCRIPT_JAVASCRIPT_ANALYZER = {
+    id: TYPESCRIPT_JAVASCRIPT_ANALYZER_ID,
+    supportedLanguages: ["typescript", "javascript"],
+    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: TYPESCRIPT_JAVASCRIPT_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: TYPESCRIPT_JAVASCRIPT_ANALYZER_ID,
+                },
+            ],
+        };
+    }
+    const scriptKind = resolveScriptKind(inventoryEntry.extension);
+    const sourceFile = ts.createSourceFile(relativePath, content, ts.ScriptTarget.Latest, true, scriptKind);
+    const diagnostics = getSyntaxDiagnostics(relativePath, sourceFile);
+    const imports = [];
+    const exports = [];
+    const declarations = [];
+    const references = [];
+    const lineOf = (node) => sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+    function pushDeclaration(node, name, kind) {
+        const isExported = hasModifier(node, ts.SyntaxKind.ExportKeyword);
+        const isDefault = hasModifier(node, ts.SyntaxKind.DefaultKeyword);
+        if (name) {
+            declarations.push({ name, kind, exported: isExported, line: lineOf(node) });
+        }
+        if (isDefault) {
+            exports.push({ name: name ?? "default", kind: "default", line: lineOf(node) });
+        }
+        else if (isExported && name) {
+            exports.push({ name, kind: "named", line: lineOf(node) });
+        }
+    }
+    function handleImportDeclaration(node) {
+        if (!ts.isStringLiteralLike(node.moduleSpecifier))
+            return;
+        const source = node.moduleSpecifier.text;
+        const importedNames = [];
+        const clause = node.importClause;
+        if (clause) {
+            if (clause.name)
+                importedNames.push(clause.name.text);
+            const bindings = clause.namedBindings;
+            if (bindings && ts.isNamespaceImport(bindings)) {
+                importedNames.push(bindings.name.text);
+            }
+            else if (bindings && ts.isNamedImports(bindings)) {
+                for (const element of bindings.elements)
+                    importedNames.push(element.name.text);
+            }
+        }
+        imports.push({
+            source,
+            kind: "static",
+            line: lineOf(node),
+            ...(importedNames.length > 0 ? { importedNames } : {}),
+        });
+    }
+    function handleExportDeclaration(node) {
+        const source = node.moduleSpecifier && ts.isStringLiteralLike(node.moduleSpecifier) ? node.moduleSpecifier.text : undefined;
+        if (source) {
+            imports.push({ source, kind: "re-export", line: lineOf(node) });
+        }
+        if (!node.exportClause) {
+            if (source)
+                exports.push({ name: "*", kind: "namespace", line: lineOf(node) });
+            return;
+        }
+        if (ts.isNamespaceExport(node.exportClause)) {
+            exports.push({ name: node.exportClause.name.text, kind: "namespace", line: lineOf(node) });
+            return;
+        }
+        for (const element of node.exportClause.elements) {
+            exports.push({ name: element.name.text, kind: "named", line: lineOf(node) });
+        }
+    }
+    function handleExportAssignment(node) {
+        if (node.isExportEquals) {
+            exports.push({ name: "module.exports", kind: "commonjs", line: lineOf(node) });
+            return;
+        }
+        const expr = node.expression;
+        let name = "default";
+        if (ts.isIdentifier(expr)) {
+            name = expr.text;
+        }
+        else if ((ts.isFunctionExpression(expr) || ts.isClassExpression(expr)) && expr.name) {
+            name = expr.name.text;
+        }
+        exports.push({ name, kind: "default", line: lineOf(node) });
+    }
+    function handleVariableStatement(node) {
+        const isExported = hasModifier(node, ts.SyntaxKind.ExportKeyword);
+        const isConst = (node.declarationList.flags & ts.NodeFlags.Const) !== 0;
+        for (const decl of node.declarationList.declarations) {
+            // Destructuring patterns (`const { a, b } = x`) are conservatively
+            // skipped -- only simple identifier bindings are recorded.
+            if (!ts.isIdentifier(decl.name))
+                continue;
+            declarations.push({
+                name: decl.name.text,
+                kind: isConst ? "constant" : "variable",
+                exported: isExported,
+                line: lineOf(decl),
+            });
+            if (isExported) {
+                exports.push({ name: decl.name.text, kind: "named", line: lineOf(decl) });
+            }
+        }
+    }
+    function handleCommonJsAssignment(node) {
+        const left = node.left;
+        if (!ts.isPropertyAccessExpression(left) || !ts.isIdentifier(left.expression))
+            return;
+        if (left.expression.text === "module" && left.name.text === "exports") {
+            exports.push({ name: "module.exports", kind: "commonjs", line: lineOf(node) });
+        }
+        else if (left.expression.text === "exports") {
+            exports.push({ name: left.name.text, kind: "commonjs", line: lineOf(node) });
+        }
+    }
+    function handleCallExpression(node) {
+        if (ts.isIdentifier(node.expression) && node.expression.text === "require") {
+            const arg = node.arguments[0];
+            if (arg && ts.isStringLiteralLike(arg)) {
+                imports.push({ source: arg.text, kind: "commonjs", line: lineOf(node) });
+            }
+            return; // already represented as an import fact -- do not also reference "require".
+        }
+        if (node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+            const arg = node.arguments[0];
+            if (arg && ts.isStringLiteralLike(arg)) {
+                imports.push({ source: arg.text, kind: "dynamic", line: lineOf(node) });
+            }
+            return;
+        }
+        if (ts.isIdentifier(node.expression)) {
+            // Conservative reference extraction: only bare-identifier call
+            // expressions (`foo()`), not property-access calls (`a.b()`) or any
+            // other identifier usage -- no scope analysis, no unused-detection.
+            references.push({ name: node.expression.text, kind: "call", line: lineOf(node) });
+        }
+    }
+    function visit(node) {
+        if (ts.isImportDeclaration(node)) {
+            handleImportDeclaration(node);
+        }
+        else if (ts.isExportDeclaration(node)) {
+            handleExportDeclaration(node);
+        }
+        else if (ts.isExportAssignment(node)) {
+            handleExportAssignment(node);
+        }
+        else if (ts.isFunctionDeclaration(node)) {
+            pushDeclaration(node, node.name?.text, "function");
+        }
+        else if (ts.isClassDeclaration(node)) {
+            pushDeclaration(node, node.name?.text, "class");
+        }
+        else if (ts.isInterfaceDeclaration(node)) {
+            pushDeclaration(node, node.name.text, "interface");
+        }
+        else if (ts.isTypeAliasDeclaration(node)) {
+            pushDeclaration(node, node.name.text, "type");
+        }
+        else if (ts.isEnumDeclaration(node)) {
+            pushDeclaration(node, node.name.text, "enum");
+        }
+        else if (ts.isVariableStatement(node)) {
+            handleVariableStatement(node);
+        }
+        else if (ts.isMethodDeclaration(node) && ts.isIdentifier(node.name)) {
+            declarations.push({ name: node.name.text, kind: "method", exported: false, line: lineOf(node) });
+        }
+        else if (ts.isCallExpression(node)) {
+            handleCallExpression(node);
+        }
+        else if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
+            handleCommonJsAssignment(node);
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    const parseStatus = diagnostics.length > 0 ? "parse-error" : "parsed";
+    return {
+        relativePath,
+        language,
+        role,
+        parseStatus,
+        analyzerId: TYPESCRIPT_JAVASCRIPT_ANALYZER_ID,
+        lineCount: inventoryEntry.lineCount,
+        imports,
+        exports,
+        declarations,
+        references,
+        diagnostics,
+    };
+}
+function resolveScriptKind(extension) {
+    switch (extension) {
+        case ".tsx":
+            return ts.ScriptKind.TSX;
+        case ".jsx":
+            return ts.ScriptKind.JSX;
+        case ".js":
+        case ".mjs":
+        case ".cjs":
+            return ts.ScriptKind.JS;
+        case ".ts":
+        case ".mts":
+        case ".cts":
+        default:
+            return ts.ScriptKind.TS;
+    }
+}
+function hasModifier(node, kind) {
+    if (!ts.canHaveModifiers(node))
+        return false;
+    const modifiers = ts.getModifiers(node);
+    return modifiers?.some((m) => m.kind === kind) ?? false;
+}
+// Reads syntax diagnostics directly off the already-built SourceFile rather
+// than running a second full parse via ts.transpileModule(). `parseDiagnostics`
+// is not part of the public TypeScript.d.ts surface, but it is populated by
+// createSourceFile() itself (every syntax error the parser recovers from is
+// recorded there) and has been stable across TypeScript versions for years --
+// this is a widely-used pattern for exactly this "syntax diagnostics without
+// a second parse/transpile pass" use case. Benchmarked at ~5x faster than
+// transpileModule() over this repo's own ~375 TS/JS files, which matters
+// because collectSourceFacts.ts calls this analyzer once per eligible file
+// on every audit run (including this repo's own self-audit).
+function getSyntaxDiagnostics(relativePath, sourceFile) {
+    const parseDiagnostics = sourceFile.parseDiagnostics ?? [];
+    return parseDiagnostics.map((diagnostic) => toSourceFactDiagnostic(relativePath, diagnostic));
+}
+function toSourceFactDiagnostic(relativePath, diagnostic) {
+    const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n");
+    const line = diagnostic.file && diagnostic.start !== undefined
+        ? diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start).line + 1
+        : undefined;
+    return {
+        severity: diagnostic.category === ts.DiagnosticCategory.Warning ? "warning" : "error",
+        code: `TS${diagnostic.code}`,
+        message: line !== undefined ? `Line ${line}: ${message}` : message,
+        path: relativePath,
+        analyzerId: TYPESCRIPT_JAVASCRIPT_ANALYZER_ID,
+    };
+}