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

package/dist/src/audits/codeRot/detectors/testRotDetector.js

@@ -1,7 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
+import { collectPythonProjectMetadata } from "../../core/pythonProjectMetadata.js";
 import { readBoundedFileText } from "../utils/boundedRead.js";
 import { deduplicateIssuesById, makeCodeRotIssue } from "../utils/issueFactories.js";
+import { getParsedSourceFacts, indexSourceFactsByPath } from "../utils/sourceFactsLookup.js";
 import { splitLines } from "../utils/textLines.js";
 // ---------------------------------------------------------------------------
 // v0.3.0 Batch 4 — test-rot detector.
@@ -42,6 +44,13 @@ export const TEST_ROT_DETECTOR = {
         const issues = [];
         const scriptNames = new Set(ctx.sourceOfTruth.commands.allScriptNames);
         const currentVersion = ctx.sourceOfTruth.package?.version ?? null;
+        const sourceFactsIndex = indexSourceFactsByPath(ctx.sourceFacts);
+        // v0.3.2 Batch 2 -- computed once per run, not per test file. Presence-
+        // only/simple-text-extraction (see pythonProjectMetadata.ts); used below
+        // purely as weak supporting context on Python findings, never as a
+        // required condition -- its absence must not change whether a finding
+        // is emitted, only add or omit one extra evidence line.
+        const pythonMetadata = collectPythonProjectMetadata(ctx.target.rootPath, ctx.inventory);
         for (const testFile of ctx.inventory.testFiles) {
             const content = readBoundedFileText(ctx.target.rootPath, testFile.relativePath, testFile.sizeBytes, MAX_READ_BYTES);
             if (content === null)
@@ -61,6 +70,26 @@ export const TEST_ROT_DETECTOR = {
             if (testFile.relativePath.startsWith("tests/audits/codeRot/"))
                 continue;
             issues.push(...findMissingSourceImports(ctx, testFile.relativePath, content));
+            // v0.3.1 Batch 4 -- when the TypeScript/JavaScript analyzer actually
+            // parsed this test file, also check its structured import facts.
+            // This catches import forms the regex above misses (e.g. multi-line
+            // import statements) without duplicate-reporting a specifier both
+            // checks already found: idCues use the same shape
+            // (testRelativePath, "missing-source-import", specifier), so an
+            // identical id is deduplicated by deduplicateIssuesById() below.
+            const parsedFacts = getParsedSourceFacts(sourceFactsIndex, testFile.relativePath);
+            if (parsedFacts?.language === "python") {
+                // v0.3.2 Batch 2 -- Python relative imports use dotted-module
+                // notation (".module", "..pkg.module"), not TS/JS's path-like
+                // "./module" syntax. Routing Python facts through the TS/JS
+                // resolver below would misresolve every relative Python import and
+                // flag it as missing regardless of whether it actually exists --
+                // this guard is the fix for that latent cross-language bug.
+                issues.push(...findMissingPythonSourceImports(ctx, testFile.relativePath, parsedFacts, pythonMetadata));
+            }
+            else if (parsedFacts) {
+                issues.push(...findMissingSourceImportsFromSourceFacts(ctx, testFile.relativePath, parsedFacts));
+            }
             issues.push(...findStaleNpmRunReferences(testFile.relativePath, content, scriptNames));
             issues.push(...findSkipUsage(testFile.relativePath, content));
             issues.push(...findOnlyUsage(testFile.relativePath, content));
@@ -115,6 +144,153 @@ function findMissingSourceImports(ctx, testRelativePath, content) {
     }
     return issues;
 }
+// v0.3.1 Batch 4 -- source-facts-derived counterpart to
+// findMissingSourceImports() above. Uses the TypeScript/JavaScript
+// analyzer's already-parsed ImportFact list instead of a regex scan of raw
+// content, so it also catches relative import specifiers the regex above
+// misses. Only called for facts with parseStatus "parsed" (see caller) --
+// file-level-only/parse-error facts carry an empty imports array that
+// would otherwise silently look like "no imports" rather than "unknown".
+function findMissingSourceImportsFromSourceFacts(ctx, testRelativePath, facts) {
+    const issues = [];
+    const testDir = path.dirname(testRelativePath);
+    for (const imp of facts.imports) {
+        if (!imp.source.startsWith("."))
+            continue;
+        const resolvedBase = path.join(testDir, imp.source).replace(/\\/g, "/");
+        const strippedBase = resolvedBase.replace(/\.[cm]?[jt]sx?$/, "");
+        const resolved = RESOLVE_EXTENSIONS.some((ext) => fs.existsSync(path.join(ctx.target.rootPath, `${strippedBase}${ext}`)));
+        if (resolved)
+            continue;
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: [testRelativePath, "missing-source-import", imp.source],
+            title: `Test "${testRelativePath}" imports a missing source file: "${imp.source}"`,
+            description: `${testRelativePath} imports "${imp.source}" (source-facts-derived via the TypeScript/JavaScript analyzer), which does not resolve to an existing file on disk (checked common TS/JS extensions relative to the test file).`,
+            severity: "medium",
+            confidence: "high",
+            falsePositiveRisk: "low",
+            category: "test-rot",
+            recommendedAction: "Fix or remove the stale import.",
+            suggestedFixStrategy: `Update the import specifier "${imp.source}" in ${testRelativePath} to point to an existing file.`,
+            validationCommands: [`npx vitest run ${testRelativePath}`],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence: [
+                {
+                    kind: "file",
+                    message: "Analyzer-recorded relative import specifier does not resolve to an existing file.",
+                    filePath: testRelativePath,
+                    excerpt: imp.source,
+                    source: DETECTOR_ID,
+                    confidence: "high",
+                },
+            ],
+            affectedFiles: [testRelativePath],
+        }));
+    }
+    return issues;
+}
+// v0.3.2 Batch 2 -- resolves a Python relative-import source (".module",
+// "..pkg.sub", or bare "."/".." paired with `from . import name`-style
+// imported names) to candidate local file paths, using Python's own
+// relative-import level semantics (one leading dot = the importing file's
+// own directory, each additional dot = one directory further up). This is a
+// conservative, path-based approximation -- it does not resolve namespace
+// packages, `sys.path` manipulation, editable installs, or anything beyond
+// simple on-disk file/package presence, so returning zero matches is a
+// candidate "may indicate a missing module" signal, not proof.
+function resolvePythonRelativeImportCandidatePaths(testDir, importSource, importedNames) {
+    if (!importSource.startsWith("."))
+        return [];
+    let dotCount = 0;
+    while (dotCount < importSource.length && importSource[dotCount] === ".")
+        dotCount += 1;
+    const remainder = importSource.slice(dotCount);
+    const upLevels = dotCount - 1;
+    let baseDir = testDir;
+    for (let i = 0; i < upLevels; i++)
+        baseDir = path.dirname(baseDir);
+    const candidates = [];
+    const pushCandidatesFor = (moduleSegment) => {
+        candidates.push(path.join(baseDir, `${moduleSegment}.py`).replace(/\\/g, "/"));
+        candidates.push(path.join(baseDir, moduleSegment, "__init__.py").replace(/\\/g, "/"));
+    };
+    if (remainder) {
+        pushCandidatesFor(remainder.split(".").join("/"));
+    }
+    else {
+        // Bare "." / ".." (e.g. `from . import sibling`) -- the module lives
+        // in `importedNames`, not in `importSource` itself.
+        for (const name of importedNames ?? [])
+            pushCandidatesFor(name);
+    }
+    return candidates;
+}
+// v0.3.2 Batch 2 -- Python-specific counterpart to
+// findMissingSourceImportsFromSourceFacts() above. Only ever called for
+// facts with `language === "python"` (see caller) -- the two functions are
+// kept fully separate rather than parameterized by language, because their
+// resolution algorithms are genuinely different (dotted-module relative-
+// import-level semantics vs. path-like specifier semantics), and conflating
+// them risked silently misresolving one language or the other. Deliberately
+// lower severity/confidence than the TS/JS counterpart: this scan has no
+// real package/sys.path awareness, so it is weaker evidence than the
+// TS/JS analyzer's near-exact relative-path resolution.
+function findMissingPythonSourceImports(ctx, testRelativePath, facts, pythonMetadata) {
+    const issues = [];
+    const testDir = path.dirname(testRelativePath);
+    for (const imp of facts.imports) {
+        if (!imp.source.startsWith("."))
+            continue; // conservative: only relative Python imports are checked
+        const candidates = resolvePythonRelativeImportCandidatePaths(testDir, imp.source, imp.importedNames);
+        if (candidates.length === 0)
+            continue; // nothing checkable (e.g. bare "." with no imported names)
+        const resolved = candidates.some((candidate) => fs.existsSync(path.join(ctx.target.rootPath, candidate)));
+        if (resolved)
+            continue;
+        const evidence = [
+            {
+                kind: "file",
+                message: "Analyzer-recorded relative Python import does not resolve to a candidate local module/package file. This is a best-effort, path-based check -- it does not resolve Python's real package/sys.path rules, so confirm manually before treating it as stale.",
+                filePath: testRelativePath,
+                excerpt: imp.source,
+                source: DETECTOR_ID,
+                confidence: "low",
+            },
+        ];
+        if (pythonMetadata.hasPytestConfiguration) {
+            evidence.push({
+                kind: "observation",
+                message: "Weak supporting context: this project has a detected pytest configuration (pytest.ini, or a pyproject.toml/setup.cfg pytest section), consistent with pytest-style test conventions -- not a requirement for this finding.",
+                source: DETECTOR_ID,
+                confidence: "low",
+            });
+        }
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: [testRelativePath, "missing-python-source-import", imp.source],
+            title: `Test "${testRelativePath}" imports a Python module that may not exist: "${imp.source}"`,
+            description: `${testRelativePath} imports "${imp.source}" (source-facts-derived via the Python analyzer). No candidate local module or package file was found relative to the test file. This is a deterministic source-facts signal from a conservative, non-semantic scan -- it does not resolve Python's real package/sys.path rules, namespace packages, or editable installs, so this may indicate a stale import but is not proof.`,
+            severity: "low",
+            confidence: "low",
+            falsePositiveRisk: "medium",
+            category: "test-rot",
+            recommendedAction: "Confirm the imported Python module exists (it may resolve via a path this scan cannot see) before treating this as stale.",
+            suggestedFixStrategy: `Update or remove the import "${imp.source}" in ${testRelativePath} if confirmed stale.`,
+            validationCommands: [`npx vitest run ${testRelativePath}`],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence,
+            affectedFiles: [testRelativePath],
+        }));
+    }
+    return issues;
+}
 function findStaleNpmRunReferences(testRelativePath, content, scriptNames) {
     const issues = [];
     const seen = new Set();

package/dist/src/audits/codeRot/utils/filePatternUtils.js

@@ -45,3 +45,53 @@ export const GENERIC_INFRA_BASENAMES = new Set([
     "errors",
     "error",
 ]);
+// v0.3.1 Batch 4 -- common, generic exported-declaration names that are
+// expected to repeat across unrelated files legitimately (CLI entrypoints,
+// handler/lifecycle conventions, etc.) -- excluded from the source-facts
+// duplicate-declaration-candidate heuristic in duplicateImplementationDetector.ts
+// to keep false positives near zero. v0.3.2 Batch 2 adds Python lifecycle/
+// dunder names ("teardown", "__init__", "__call__") for the same reason,
+// reused by both duplicateImplementationDetector.ts and
+// deadCodeCandidateDetector.ts's new Python-aware checks.
+export const GENERIC_DECLARATION_NAMES = new Set([
+    "run",
+    "main",
+    "init",
+    "initialize",
+    "setup",
+    "teardown",
+    "handler",
+    "handle",
+    "execute",
+    "process",
+    "validate",
+    "parse",
+    "format",
+    "render",
+    "build",
+    "create",
+    "start",
+    "stop",
+    "load",
+    "save",
+    "update",
+    "remove",
+    "apply",
+    "get",
+    "set",
+    "default",
+    "__init__",
+    "__call__",
+]);
+// v0.3.2 Batch 2 -- true for a generic/lifecycle declaration name (see
+// GENERIC_DECLARATION_NAMES above) or a pytest-style `test_*` name. Shared by
+// the Python-aware dead-code and duplicate-implementation checks so a
+// `test_*` helper/fixture function is never flagged as a candidate dead-code
+// symbol or a duplicate-implementation candidate merely for repeating across
+// unrelated test modules, a legitimate and extremely common pytest
+// convention. Comparison is case-insensitive; callers pass the already-
+// lowercased name where convenient.
+export function isGenericOrTestPrefixedDeclarationName(name) {
+    const lower = name.toLowerCase();
+    return GENERIC_DECLARATION_NAMES.has(lower) || lower.startsWith("test_");
+}

package/dist/src/audits/codeRot/utils/sourceFactsLookup.js

@@ -0,0 +1,53 @@
+import { baseNameNoExt } from "./filePatternUtils.js";
+// ---------------------------------------------------------------------------
+// v0.3.1 Batch 4 -- shared source-facts lookup helpers for code-rot
+// detectors.
+//
+// ctx.sourceFacts is optional (see auditRegistry.ts) precisely so existing
+// detector tests that build a literal AuditDetectorContext without it keep
+// working unchanged -- every helper here accepts `undefined` and degrades to
+// an empty result rather than throwing, so a caller never needs its own
+// null-check before using them.
+// ---------------------------------------------------------------------------
+// Indexes a SourceFactsSnapshot's files by relativePath for O(1) per-file
+// lookups. Returns an empty map when sourceFacts is undefined.
+export function indexSourceFactsByPath(sourceFacts) {
+    const index = new Map();
+    if (!sourceFacts)
+        return index;
+    for (const file of sourceFacts.files)
+        index.set(file.relativePath, file);
+    return index;
+}
+// Returns the facts for relativePath only when parseStatus is "parsed" --
+// callers that want analyzer-derived evidence (imports/exports/declarations)
+// should use this rather than reading the index directly, since
+// file-level-only/parse-error/skipped/unsupported entries carry empty fact
+// arrays that would silently look like "no imports" rather than "unknown".
+export function getParsedSourceFacts(index, relativePath) {
+    const facts = index.get(relativePath);
+    return facts && facts.parseStatus === "parsed" ? facts : null;
+}
+// Basenames referenced by any parsed file's relative import/re-export
+// specifier, lowercased. Mirrors deadCodeCandidateDetector.ts's regex-based
+// buildReverseReferenceIndex() basename matching, but sourced from
+// structured analyzer facts -- so it also catches import forms the regex
+// misses (e.g. multi-line import statements) for files a registered
+// analyzer actually parsed. Returns an empty set when sourceFacts is
+// undefined, so merging it into an existing Set is always safe.
+export function collectRelativeImportBasenames(sourceFacts) {
+    const basenames = new Set();
+    if (!sourceFacts)
+        return basenames;
+    for (const file of sourceFacts.files) {
+        if (file.parseStatus !== "parsed")
+            continue;
+        for (const imp of file.imports) {
+            if (!imp.source.startsWith("."))
+                continue;
+            const base = baseNameNoExt(imp.source.split("?")[0]);
+            basenames.add(base.toLowerCase());
+        }
+    }
+    return basenames;
+}

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

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { AUDIT_FAIL_ON_THRESHOLDS, AUDIT_INCLUDE_AREAS, AUDIT_OUTPUT_FORMATS, AUDIT_TYPES, DEFAULT_AUDIT_FAIL_ON_THRESHOLD, DEFAULT_AUDIT_INCLUDE_AREAS, DEFAULT_AUDIT_OUTPUT_FORMATS, DEFAULT_AUDIT_TYPES, PLANNED_AUDIT_TYPES, } from "./auditTypes.js";
+import { AUDIT_FAIL_ON_THRESHOLDS, AUDIT_INCLUDE_AREAS, AUDIT_OUTPUT_FORMATS, AUDIT_TYPES, DEFAULT_AUDIT_FAIL_ON_THRESHOLD, DEFAULT_AUDIT_INCLUDE_AREAS, DEFAULT_AUDIT_OUTPUT_FORMATS, DEFAULT_AUDIT_TYPES, IMPLEMENTED_AUDIT_TYPES, PLANNED_AUDIT_TYPES, } from "./auditTypes.js";
 const FLAGS_WITH_VALUE = {
     "--target": "target",
     "--types": "types",
@@ -67,7 +67,7 @@ function parseTypesOption(raw) {
     }
     const planned = parts.filter((p) => PLANNED_AUDIT_TYPES.includes(p));
     if (planned.length > 0) {
-        throw new Error(`--types value(s) planned but not implemented: ${planned.join(", ")}. Only "code-rot" is implemented in this version.`);
+        throw new Error(`--types value(s) planned but not implemented: ${planned.join(", ")}. Implemented audit types: ${IMPLEMENTED_AUDIT_TYPES.join(", ")}.`);
     }
     const unique = new Set(parts);
     const ordered = AUDIT_TYPES.filter((id) => unique.has(id));

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

@@ -3,14 +3,20 @@ import { DEFAULT_AUDIT_REGISTRY, selectDetectors } from "./auditRegistry.js";
 import { resolveAuditTarget } from "./auditTarget.js";
 import { scanProjectInventory } from "./projectInventory.js";
 import { collectSourceOfTruth } from "./sourceOfTruth.js";
+import { collectSourceFacts } from "./collectSourceFacts.js";
+import { collectPythonProjectMetadata } from "./pythonProjectMetadata.js";
+import { runSecurityAuditAdapter } from "../security/securityAuditAdapter.js";
+import { SECURITY_AUDIT_NOT_RUN_SUMMARY } from "../security/securityAuditTypes.js";
 export async function runAudit(options) {
     const { config, toolRoot } = options;
     const registry = options.registry ?? DEFAULT_AUDIT_REGISTRY;
     const target = options.target ?? resolveAuditTarget(config.targetPathArg, toolRoot);
     const inventory = scanProjectInventory(target.rootPath);
     const sourceOfTruth = collectSourceOfTruth(target.rootPath, inventory);
+    const sourceFacts = await collectSourceFacts(target.rootPath, inventory);
+    const pythonProjectMetadata = collectPythonProjectMetadata(target.rootPath, inventory);
     const selected = selectDetectors(registry, config.types, config.include);
-    const ctx = { target, config, inventory, sourceOfTruth };
+    const ctx = { target, config, inventory, sourceOfTruth, sourceFacts };
     const issues = [];
     const skippedDetectors = [];
     const detectorErrors = [];
@@ -35,6 +41,19 @@ export async function runAudit(options) {
             });
         }
     }
+    // v0.3.2 Batch 4 -- security audit adapter. Conditional (see the
+    // AuditResult.securitySummary field comment above): only runs when --types
+    // explicitly includes "security", never as part of a default/code-rot-only
+    // run. Appended after the code-rot detector loop above, so combined
+    // `--types code-rot,security` runs keep a deterministic issue order:
+    // code-rot detector issues (registry order) first, then security findings
+    // (security-validation check-execution order).
+    let securitySummary = SECURITY_AUDIT_NOT_RUN_SUMMARY;
+    if (config.types.includes("security")) {
+        const securityAudit = await runSecurityAuditAdapter({ toolRoot, config });
+        issues.push(...securityAudit.issues);
+        securitySummary = securityAudit.summary;
+    }
     const issueCounts = countIssuesBySeverity(issues);
     const { exitCode, reason } = calculateAuditExitCode(issues, config.failOn);
     return {
@@ -59,6 +78,9 @@ export async function runAudit(options) {
         exitReason: reason,
         inventory,
         sourceOfTruth,
+        sourceFacts,
+        pythonProjectMetadata,
+        securitySummary,
         noDetectorsRegistered: selected.length === 0,
     };
 }

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

@@ -7,14 +7,21 @@
 // this batch keeps the audit issue schema independent even where a
 // vocabulary word (e.g. "blocker") happens to be shared.
 // ---------------------------------------------------------------------------
-// Recognized --types values. Only "code-rot" has real detector coverage in
-// Batch 1 — the rest are known, named future audit types that must fail
-// cleanly with a "planned but not implemented" message rather than being
-// silently accepted or treated as an unknown/garbage value.
+// Recognized --types values. "code-rot" (Batch 1) and "security" (v0.3.2
+// Batch 4, via the security-validation audit adapter) have real coverage —
+// the rest are known, named future audit types that must fail cleanly with a
+// "planned but not implemented" message rather than being silently accepted
+// or treated as an unknown/garbage value.
 export const AUDIT_TYPES = ["code-rot", "quality", "security", "project", "all"];
-export const IMPLEMENTED_AUDIT_TYPES = ["code-rot"];
-export const PLANNED_AUDIT_TYPES = ["quality", "security", "project", "all"];
-export const DEFAULT_AUDIT_TYPES = IMPLEMENTED_AUDIT_TYPES;
+export const IMPLEMENTED_AUDIT_TYPES = ["code-rot", "security"];
+export const PLANNED_AUDIT_TYPES = ["quality", "project", "all"];
+// v0.3.2 Batch 4 — deliberately NOT derived from IMPLEMENTED_AUDIT_TYPES.
+// "security" becomes selectable via --types security (and --types
+// code-rot,security) but must never join the *default* (no --types flag)
+// audit run, since it shells out to npm audit/CodeQL/Semgrep/fuzz and is far
+// more expensive than the always-on code-rot detectors — a default,
+// unqualified `npm run audit` must keep its existing code-rot-only behavior.
+export const DEFAULT_AUDIT_TYPES = ["code-rot"];
 export const AUDIT_INCLUDE_AREAS = ["docs", "tests", "package", "architecture", "cli"];
 export const DEFAULT_AUDIT_INCLUDE_AREAS = AUDIT_INCLUDE_AREAS;
 export const AUDIT_OUTPUT_FORMATS = ["text", "json"];

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

@@ -0,0 +1,142 @@
+import fs from "node:fs";
+import path from "node:path";
+import { NORMALIZED_LANGUAGES } from "./projectInventory.js";
+import { DEFAULT_LANGUAGE_ANALYZER_REGISTRY, selectLanguageAnalyzer, } from "./languageAnalyzerRegistry.js";
+import { SOURCE_FACT_PARSE_STATUSES, } from "./sourceFacts.js";
+// ---------------------------------------------------------------------------
+// v0.3.1 Batch 2 -- source facts collector.
+//
+// Consumes the Batch 1 ProjectInventorySnapshot (never re-walks the
+// filesystem) and produces a SourceFactsSnapshot: analyzer facts where a
+// registered analyzer exists, deterministic fallback facts otherwise. Same
+// spirit as sourceOfTruth.ts -- pure data collection, never an AuditIssue,
+// never a write to a target file.
+//
+// Eligibility / omission policy (documented here since it's the single
+// source of truth for the decision):
+//   - Only inventory entries with role "source" or "test" are considered.
+//     docs/config/package/generated/vendor/build-output/report-output/
+//     unknown-role files are omitted entirely from `files` -- source facts
+//     are meaningless for them, and omitting (rather than emitting a
+//     "skipped" placeholder for every doc/config file in the repo) keeps
+//     the snapshot proportional to actual candidate source files.
+//   - For an eligible file in a *known* language (typescript, javascript,
+//     python, java, kotlin) with no registered analyzer: parseStatus
+//     "file-level-only" -- we know the language and already have
+//     inventory-level evidence (lineCount), just no analyzer parsed it yet.
+//   - For an eligible file in an *unknown* language: parseStatus
+//     "unsupported" -- no file-level evidence attempted either.
+//   - File content is only read when a registered analyzer actually claims
+//     the file -- with an empty default registry (Batch 2), no file is ever
+//     read by this collector.
+// ---------------------------------------------------------------------------
+const ANALYZABLE_ROLES = new Set(["source", "test"]);
+const KNOWN_LANGUAGES = new Set(["typescript", "javascript", "python", "java", "kotlin"]);
+export async function collectSourceFacts(targetRoot, inventory, registry = DEFAULT_LANGUAGE_ANALYZER_REGISTRY) {
+    const resolvedRoot = path.resolve(targetRoot);
+    const files = [];
+    const analyzerDiagnostics = [];
+    const warnings = [];
+    // inventory.files is already sorted by relativePath (Batch 1 guarantee) --
+    // filtering preserves that order, so no re-sort is needed here.
+    const eligible = inventory.files.filter((entry) => ANALYZABLE_ROLES.has(entry.role));
+    for (const entry of eligible) {
+        const analyzer = selectLanguageAnalyzer(registry, entry.language, entry.extension);
+        if (!analyzer) {
+            files.push(buildFallbackFacts(entry));
+            continue;
+        }
+        const absolutePath = path.join(resolvedRoot, entry.relativePath);
+        try {
+            const content = fs.readFileSync(absolutePath, "utf8");
+            const facts = await analyzer.analyzeFile({
+                targetRoot: resolvedRoot,
+                relativePath: entry.relativePath,
+                absolutePath,
+                content,
+                inventoryEntry: entry,
+                language: entry.language,
+                role: entry.role,
+            });
+            files.push(facts);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const diagnostic = {
+                severity: "error",
+                code: "analyzer-error",
+                message: `Analyzer "${analyzer.id}" failed on "${entry.relativePath}": ${message}`,
+                path: entry.relativePath,
+                analyzerId: analyzer.id,
+            };
+            analyzerDiagnostics.push(diagnostic);
+            files.push({
+                relativePath: entry.relativePath,
+                language: entry.language,
+                role: entry.role,
+                parseStatus: "parse-error",
+                analyzerId: analyzer.id,
+                lineCount: entry.lineCount,
+                imports: [],
+                exports: [],
+                declarations: [],
+                references: [],
+                diagnostics: [diagnostic],
+            });
+        }
+    }
+    return {
+        targetRoot: resolvedRoot,
+        files,
+        filesByLanguage: countByLanguage(files),
+        filesByParseStatus: countByParseStatus(files),
+        analyzerDiagnostics,
+        warnings,
+    };
+}
+function buildFallbackFacts(entry) {
+    const known = KNOWN_LANGUAGES.has(entry.language);
+    const parseStatus = known ? "file-level-only" : "unsupported";
+    const diagnostic = known
+        ? {
+            severity: "info",
+            code: "no-analyzer-registered",
+            message: `No language analyzer is registered for "${entry.language}" yet; only inventory-level facts are available.`,
+            path: entry.relativePath,
+            analyzerId: null,
+        }
+        : {
+            severity: "info",
+            code: "unsupported-language",
+            message: `Language "${entry.language}" is not supported for source-fact extraction.`,
+            path: entry.relativePath,
+            analyzerId: null,
+        };
+    return {
+        relativePath: entry.relativePath,
+        language: entry.language,
+        role: entry.role,
+        parseStatus,
+        analyzerId: null,
+        lineCount: entry.lineCount,
+        imports: [],
+        exports: [],
+        declarations: [],
+        references: [],
+        diagnostics: [diagnostic],
+    };
+}
+function countByLanguage(files) {
+    const counts = Object.fromEntries(NORMALIZED_LANGUAGES.map((l) => [l, 0]));
+    for (const file of files) {
+        counts[file.language] += 1;
+    }
+    return counts;
+}
+function countByParseStatus(files) {
+    const counts = Object.fromEntries(SOURCE_FACT_PARSE_STATUSES.map((s) => [s, 0]));
+    for (const file of files) {
+        counts[file.parseStatus] += 1;
+    }
+    return counts;
+}

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

@@ -0,0 +1,36 @@
+import { TYPESCRIPT_JAVASCRIPT_ANALYZER } from "./typescriptJavaScriptAnalyzer.js";
+import { PYTHON_ANALYZER } from "./pythonAnalyzer.js";
+// Validates a list has no duplicate analyzer ids. Later batches call this
+// when assembling their own registries; Batch 2's empty default trivially
+// passes.
+export function createLanguageAnalyzerRegistry(analyzers) {
+    const seen = new Set();
+    for (const analyzer of analyzers) {
+        if (seen.has(analyzer.id)) {
+            throw new Error(`Duplicate language analyzer id: "${analyzer.id}".`);
+        }
+        seen.add(analyzer.id);
+    }
+    return analyzers;
+}
+// First matching analyzer in registry order (deterministic), or null when
+// none supports the given language/extension. Order is preserved from the
+// input registry -- not re-sorted.
+export function selectLanguageAnalyzer(registry, language, extension) {
+    for (const analyzer of registry) {
+        if (!analyzer.supportedLanguages.includes(language))
+            continue;
+        if (analyzer.supportedExtensions && !analyzer.supportedExtensions.includes(extension))
+            continue;
+        return analyzer;
+    }
+    return null;
+}
+// v0.3.1 Batch 3 -- registers the TypeScript/JavaScript analyzer. v0.3.2
+// Batch 1 adds the Python analyzer alongside it. Java and Kotlin remain
+// fallback-only (no analyzer registered for them) -- see
+// collectSourceFacts.ts's fallback policy.
+export const DEFAULT_LANGUAGE_ANALYZER_REGISTRY = createLanguageAnalyzerRegistry([
+    TYPESCRIPT_JAVASCRIPT_ANALYZER,
+    PYTHON_ANALYZER,
+]);