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

package/README.md

@@ -1,8 +1,10 @@
 # my-dev-kit-lab
 
-my-dev-kit-lab is the experiment, evidence, reporting, security-validation, and future audit companion for my-dev-kit. It runs reproducible experiments that test whether my-dev-kit's graph-guided retrieval helps coding-agent workflows, collects metrics, renders reports, generates plots, captures screenshots, builds gallery outputs, and performs automated CLI/package security validation.
-
-The current package version is `v0.3.0` (release-prepared; not yet published to npm, tagged, or released on GitHub). The latest published npm baseline is `v0.2.2`. Its generic experiment-plugin framework was introduced in v0.2.0. The first plugin is `context-strategy-comparison`, which preserves the existing raw-full-file vs my-dev-kit-guided workflow through the plugin runner.
+my-dev-kit-lab is the experiment, evidence, reporting, security-validation, and audit companion for my-dev-kit. It runs reproducible experiments that test whether my-dev-kit's graph-guided retrieval helps coding-agent workflows, collects metrics, renders reports, generates plots, captures screenshots, builds gallery outputs, performs automated CLI/package security validation, and runs the generic audit framework.
+
+The current published baseline is `v0.3.0`. `v0.3.0` introduced the generic audit framework and the first implemented code-rot detector family. The generic experiment-plugin framework was introduced in `v0.2.0`. The first plugin is `context-strategy-comparison`, which preserves the existing raw-full-file vs my-dev-kit-guided workflow through the plugin runner.
+
+The checked-out package is release-prepared for `v0.3.1` on top of the published baseline: normalized language/file-role inventory, source-facts collection, a TypeScript/JavaScript analyzer, source-facts-aware code-rot signals, and source-facts summaries in text/JSON audit reports. `v0.3.1` is not published yet; Python, Java, Kotlin, Android validation, framework-aware profiles, and broader audit types remain future roadmap work.
 
 my-dev-kit is most useful when the repository is larger than the task. It helps coding agents work with large codebases through reusable structural indexing, graph-guided retrieval, targeted source slices, and auditable context selection. Results are scoped evidence; the project does not claim that my-dev-kit always saves tokens.
 
@@ -32,7 +34,7 @@ my-dev-kit is most useful when the repository is larger than the task. It helps
 - Target-aware experiment execution for local projects via `experiment:run -- --target <path>`
 - Plugin-aware JSON and HTML reports with plugin, target, variant, metric, artifact, warning, skip, and failure metadata
 - Security validation framework: dependency audit, package tarball inspection, CLI adversarial tests, static scans (CodeQL/Semgrep), bounded fuzz smoke, attack-scenario checks, and structured verdict/report output — runnable against any local project via `security:validate --target <path>`
-- Generic audit framework (package.json now specifies version `v0.3.0`; release-prepared but not yet published to npm, tagged, or released on GitHub): `npm run audit` runs heuristic, conservative code-rot detectors and writes text/JSON reports under `reports/audits/code-rot/` by default. Only the `code-rot` audit type is currently implemented; `quality`, `security`, `project`, and `all` audit types are planned and fail cleanly instead of running. `npm run audit` supports `--target`, `--types code-rot`, and other flags — see [docs/COMMANDS.md](docs/COMMANDS.md). Audit does not modify target files, does not auto-fix issues, does not run `security:validate`, and does not perform release-readiness determination.
+- Generic audit framework in the current published `v0.3.0` baseline: `npm run audit` runs heuristic, conservative code-rot detectors and writes text/JSON reports under `reports/audits/code-rot/` by default. Only the `code-rot` audit type is currently implemented; `quality`, `security`, `project`, and `all` audit types are planned and fail cleanly instead of running. `npm run audit` supports `--target`, `--types code-rot`, and other flags — see [docs/COMMANDS.md](docs/COMMANDS.md). Audit does not modify target files, does not auto-fix issues, does not run `security:validate`, and does not perform release-readiness determination.
 
 ---
 
@@ -201,9 +203,16 @@ See [docs/METRICS.md](docs/METRICS.md) for full metric definitions.
 
 ---
 
-## Current baseline release positioning
-
-my-dev-kit-lab is at a working baseline. The raw-vs-indexed experiment pipeline is fully implemented and produces reproducible artifacts. Real-agent campaign support exists for Codex and Claude. The latest published npm baseline is `v0.2.2`, which implements the automated security-validation fortification work described below and has passed pre-release readiness and cross-platform validation. package.json now specifies version `v0.3.0`, which adds the generic audit framework described below; `v0.3.0` is release-prepared but has not yet been published to npm, tagged, or released on GitHub.
+## Current baseline release positioning
+
+my-dev-kit-lab is at a working baseline. The raw-vs-indexed experiment pipeline is fully implemented and produces reproducible artifacts. Real-agent campaign support exists for Codex and Claude. The current published npm baseline is `v0.3.0`, which includes the generic audit framework and the first implemented code-rot detector family on top of the earlier experiment and automated security-validation work.
+
+Planned roadmap direction after the published baseline:
+
+- `v0.3.1`: language-aware code-rot substrate plus TypeScript/JavaScript support, release-prepared and not yet published
+- `v0.3.2` through `v0.3.4`: Python, Java/Kotlin, and cross-language stability for the language-aware code-rot track
+- `v0.4.0` through `v0.4.2`: Android automated security validation
+- manual pentest: post-v1 / version TBD
 
 ---
 
@@ -241,7 +250,7 @@ Each security command can validate my-dev-kit-lab itself or another local projec
 
 `security:validate` supports `--checks`, `--profile`, `--format`, `--fail-on`, `--out`, and `--report-prefix`. The no-flag path remains backward compatible and still runs the classic implemented check groups: `deps`, `package`, `static`, `cli-adversarial`, and `fuzz`. Supplying `--profile` without `--checks` swaps in that profile's default checks; supplying explicit `--checks` always wins over profile defaults.
 
-The current attack-scenario checks cover boundary, subprocess, secrets, and network assumptions. They are automated adversarial checks, not a manual pentest. `verdictImpact` metadata from each registered scenario drives blocker categorization in report reasoning, and narrowed `--checks` runs are labeled as scoped rather than described as a full release gate.
+The current attack-scenario checks cover boundary, subprocess, secrets, and network assumptions. They are automated adversarial checks, not a manual pentest. Manual pentest is deferred until after `v1.0.0`. `verdictImpact` metadata from each registered scenario drives blocker categorization in report reasoning, and narrowed `--checks` runs are labeled as scoped rather than described as a full release gate.
 
 JSON report poisoning/config-injection checks use a baseline-diff schema guard so legitimate additive JSON fields do not fail the guard while payload-created trusted top-level fields still do. Text reports are sanitized to strip ANSI/control-byte payloads before rendering.
 

package/dist/scripts/audits/runAudit.js

@@ -86,6 +86,7 @@ if (model.summary.noDetectorsRegistered) {
 console.log(`\nInventory: ${model.inventory.totalScannedFileCount} file(s) scanned, ${model.inventory.skippedFileCount} skipped`);
 console.log(`  source=${model.inventory.filesByCategory.source} tests=${model.inventory.filesByCategory.tests} docs=${model.inventory.filesByCategory.docs} package=${model.inventory.filesByCategory.package} config=${model.inventory.filesByCategory.config} scripts=${model.inventory.filesByCategory.scripts} ci=${model.inventory.filesByCategory.ci}`);
 console.log(`Source of truth: package=${model.sourceOfTruth.packageName ?? "(none)"}@${model.sourceOfTruth.packageVersion ?? "?"} readme=${model.sourceOfTruth.hasReadme} changelog=${model.sourceOfTruth.hasChangelog} ciWorkflows=${model.sourceOfTruth.ciWorkflowCount}`);
+console.log(`Source facts: ${model.sourceFacts.totalFilesAnalyzed} file(s) analyzed (parsed=${model.sourceFacts.filesByParseStatus.parsed} file-level-only=${model.sourceFacts.filesByParseStatus["file-level-only"]} unsupported=${model.sourceFacts.filesByParseStatus.unsupported})`);
 if (writtenPaths.length > 0) {
     console.log(`\nReports written:`);
     for (const p of writtenPaths) {

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

@@ -2,6 +2,7 @@ import path from "node:path";
 import { readBoundedFileText } from "../utils/boundedRead.js";
 import { baseNameNoExt } from "../utils/filePatternUtils.js";
 import { deduplicateIssuesById, makeCodeRotIssue } from "../utils/issueFactories.js";
+import { collectRelativeImportBasenames, getParsedSourceFacts, indexSourceFactsByPath } from "../utils/sourceFactsLookup.js";
 // ---------------------------------------------------------------------------
 // v0.3.0 Batch 4 — dead-code candidate detector.
 //
@@ -140,7 +141,13 @@ function findUnreferencedScriptFiles(ctx, pkg) {
     return issues;
 }
 function buildReverseReferenceIndex(ctx) {
-    const referencedBasenames = new Set();
+    // v0.3.1 Batch 4 -- seeded with basenames the TypeScript/JavaScript
+    // analyzer already resolved from real import declarations (parsed files
+    // only). This only ever adds references, never removes them, so it can
+    // only reduce false positives relative to the regex-only scan below --
+    // safe even though ctx.sourceFacts is optional (returns an empty set when
+    // absent, e.g. in existing detector-only unit tests).
+    const referencedBasenames = collectRelativeImportBasenames(ctx.sourceFacts);
     const allCandidateFiles = [
         ...ctx.inventory.sourceFiles,
         ...ctx.inventory.testFiles,
@@ -164,6 +171,7 @@ function buildReverseReferenceIndex(ctx) {
 function findUnreferencedSourceFiles(ctx, pkg, docsConcat) {
     const referencedBasenames = buildReverseReferenceIndex(ctx);
     const binCandidates = pkg ? binTargetsAsSourceCandidates(pkg) : new Set();
+    const sourceFactsIndex = indexSourceFactsByPath(ctx.sourceFacts);
     const issues = [];
     for (const file of ctx.inventory.sourceFiles) {
         if (file.sizeBytes > MAX_READ_BYTES)
@@ -187,6 +195,26 @@ function findUnreferencedSourceFiles(ctx, pkg, docsConcat) {
             continue;
         if (referencedBasenames.has(base.toLowerCase()))
             continue;
+        const evidence = [
+            {
+                kind: "observation",
+                message: "No relative import/require specifier in the scanned source/test/script set resolves to this file's basename.",
+                filePath: file.relativePath,
+                source: DETECTOR_ID,
+                confidence: "low",
+            },
+        ];
+        // v0.3.1 Batch 4 -- when the TypeScript/JavaScript analyzer actually
+        // parsed this file, surface its export count as extra candidate
+        // evidence (an exported symbol with zero detected external references
+        // is more suspicious than an unexported one). This never changes
+        // whether the issue is emitted, only its evidence -- the flagging
+        // decision above is unchanged from the existing basename-reference
+        // heuristic.
+        const facts = getParsedSourceFacts(sourceFactsIndex, file.relativePath);
+        if (facts) {
+            evidence.push(buildSourceFactsEvidence(facts));
+        }
         issues.push(makeCodeRotIssue({
             auditType: "code-rot",
             detectorId: DETECTOR_ID,
@@ -203,20 +231,25 @@ function findUnreferencedSourceFiles(ctx, pkg, docsConcat) {
             releaseBlocking: false,
             implementationBlocking: false,
             autoFixEligible: false,
-            evidence: [
-                {
-                    kind: "observation",
-                    message: "No relative import/require specifier in the scanned source/test/script set resolves to this file's basename.",
-                    filePath: file.relativePath,
-                    source: DETECTOR_ID,
-                    confidence: "low",
-                },
-            ],
+            evidence,
             affectedFiles: [file.relativePath],
         }));
     }
     return issues;
 }
+// v0.3.1 Batch 4 -- describes a parsed file's source-facts shape as an
+// evidence entry. Only called for parseStatus "parsed" facts (see callers),
+// since file-level-only/parse-error facts carry empty fact arrays that
+// would misleadingly read as "zero exports" rather than "unknown".
+function buildSourceFactsEvidence(facts) {
+    return {
+        kind: "reference",
+        message: `Source facts: the TypeScript/JavaScript analyzer parsed this file and recorded ${facts.exports.length} export(s), ${facts.declarations.length} declaration(s), and ${facts.imports.length} import(s).`,
+        filePath: facts.relativePath,
+        source: DETECTOR_ID,
+        confidence: "medium",
+    };
+}
 function findOldOrDeprecatedFilesNotInDocs(ctx, docsConcat) {
     const issues = [];
     for (const file of ctx.inventory.files) {

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

@@ -1,6 +1,7 @@
 import { readBoundedFileText } from "../utils/boundedRead.js";
-import { firstPathSegment, GENERIC_INFRA_BASENAMES, baseNameNoExt } from "../utils/filePatternUtils.js";
+import { firstPathSegment, GENERIC_DECLARATION_NAMES, GENERIC_INFRA_BASENAMES, baseNameNoExt } from "../utils/filePatternUtils.js";
 import { deduplicateIssuesById, makeCodeRotIssue } from "../utils/issueFactories.js";
+import { indexSourceFactsByPath } from "../utils/sourceFactsLookup.js";
 // ---------------------------------------------------------------------------
 // v0.3.0 Batch 4 — duplicate/parallel implementation candidate detector.
 //
@@ -60,6 +61,7 @@ export const DUPLICATE_IMPLEMENTATION_DETECTOR = {
         if (ctx.config.include.includes("architecture")) {
             issues.push(...findParallelDirectories(ctx.inventory.files.map((f) => f.relativePath)));
             issues.push(...findDuplicateBasenamesAcrossRoots(ctx.inventory.sourceFiles.map((f) => f.relativePath)));
+            issues.push(...findDuplicateDeclarationCandidates(ctx));
         }
         issues.push(...findDuplicateDetectorRegistryIds(ctx));
         return deduplicateIssuesById(issues);
@@ -214,6 +216,81 @@ function firstTopLevelUnderSrc(relativePath) {
         return null;
     return `${parts[0]}/${parts[1]}`;
 }
+// v0.3.1 Batch 4 -- source-facts-aware duplicate-declaration candidate
+// check. Weak/low-confidence signal, same spirit as
+// findDuplicateBasenamesAcrossRoots(): the same exported declaration name
+// and kind (e.g. two exported `class Logger`) appears in 2-4 distinct
+// "source"-role files that a registered analyzer actually parsed. Bounded
+// to declaration kinds that carry real implementation weight
+// (function/class/interface/type/enum) -- "variable"/"constant"/"method"/
+// "unknown" are excluded as too noisy (methods repeat across unrelated
+// classes by convention; module-scope variables/constants repeat even more
+// often). Generic declaration names (run, init, handler, ...) are excluded
+// via GENERIC_DECLARATION_NAMES for the same reason
+// GENERIC_INFRA_BASENAMES excludes generic file basenames above. Requires
+// ctx.sourceFacts -- returns no issues when it is absent (e.g. existing
+// detector unit tests that build a literal AuditDetectorContext without
+// it), so this check is purely additive.
+const NOISY_DECLARATION_KINDS = new Set(["variable", "constant", "method", "unknown"]);
+function findDuplicateDeclarationCandidates(ctx) {
+    if (!ctx.sourceFacts)
+        return [];
+    const index = indexSourceFactsByPath(ctx.sourceFacts);
+    const byKey = new Map();
+    for (const facts of index.values()) {
+        if (facts.role !== "source")
+            continue;
+        if (facts.parseStatus !== "parsed")
+            continue;
+        for (const decl of facts.declarations) {
+            if (!decl.exported)
+                continue;
+            if (NOISY_DECLARATION_KINDS.has(decl.kind))
+                continue;
+            const nameLower = decl.name.toLowerCase();
+            if (GENERIC_DECLARATION_NAMES.has(nameLower))
+                continue;
+            const key = `${decl.kind}:${nameLower}`;
+            const entry = byKey.get(key) ?? { name: decl.name, kind: decl.kind, paths: new Set() };
+            entry.paths.add(facts.relativePath);
+            byKey.set(key, entry);
+        }
+    }
+    const issues = [];
+    for (const entry of byKey.values()) {
+        if (entry.paths.size < 2 || entry.paths.size > 4)
+            continue;
+        const sortedPaths = [...entry.paths].sort((a, b) => a.localeCompare(b));
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: ["duplicate-declaration-candidate", entry.kind, entry.name.toLowerCase(), ...sortedPaths],
+            title: `Exported ${entry.kind} "${entry.name}" is declared in ${sortedPaths.length} unrelated files (weak signal)`,
+            description: `An exported ${entry.kind} named "${entry.name}" is declared in: ${sortedPaths.join(", ")}. This is a source-facts-derived candidate signal (same declaration name and kind, not a semantic-equivalence check) for parallel implementations -- inspect manually before consolidating.`,
+            severity: "info",
+            confidence: "low",
+            falsePositiveRisk: "high",
+            category: "duplicate-implementation-candidate",
+            recommendedAction: "Manually confirm whether these declarations serve genuinely different purposes before taking any action.",
+            suggestedFixStrategy: "No automatic action -- rename or consolidate only after manual review.",
+            validationCommands: ["npm run audit -- --types code-rot --include architecture"],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence: [
+                {
+                    kind: "reference",
+                    message: `Source facts: an exported ${entry.kind} named "${entry.name}" was parsed in ${sortedPaths.length} distinct files.`,
+                    excerpt: sortedPaths.join(", "),
+                    source: DETECTOR_ID,
+                    confidence: "low",
+                },
+            ],
+            affectedFiles: sortedPaths,
+        }));
+    }
+    return issues;
+}
 // Cheap regex scan (not a semantic parse) of already-small detector source
 // files for exported `id: "..."` string literals. Flags duplicates only if
 // genuinely found via this file-based check -- per the spec's own allowed

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

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 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 +43,7 @@ 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);
         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 +63,17 @@ 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) {
+                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 +128,55 @@ 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;
+}
 function findStaleNpmRunReferences(testRelativePath, content, scriptNames) {
     const issues = [];
     const seen = new Set();

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

@@ -45,3 +45,35 @@ 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.
+export const GENERIC_DECLARATION_NAMES = new Set([
+    "run",
+    "main",
+    "init",
+    "initialize",
+    "setup",
+    "handler",
+    "handle",
+    "execute",
+    "process",
+    "validate",
+    "parse",
+    "format",
+    "render",
+    "build",
+    "create",
+    "start",
+    "stop",
+    "load",
+    "save",
+    "update",
+    "remove",
+    "apply",
+    "get",
+    "set",
+    "default",
+]);

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/auditRunner.js

@@ -3,14 +3,16 @@ 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";
 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 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 = [];
@@ -59,6 +61,7 @@ export async function runAudit(options) {
         exitReason: reason,
         inventory,
         sourceOfTruth,
+        sourceFacts,
         noDetectorsRegistered: selected.length === 0,
     };
 }

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,33 @@
+import { TYPESCRIPT_JAVASCRIPT_ANALYZER } from "./typescriptJavaScriptAnalyzer.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. Python,
+// 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,
+]);

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

@@ -27,6 +27,112 @@ export const INVENTORY_FILE_CATEGORIES = [
     "report",
     "unknown",
 ];
+// ---------------------------------------------------------------------------
+// v0.3.1 Batch 1 — normalized language and file-role metadata.
+//
+// Purely additive to the v0.3.0 category model above: `category` keeps its
+// existing meaning and existing consumers (detectors, report model) are
+// untouched. `language` and `role` are deterministic, extension/path-based
+// classifications layered on top so later v0.3.1 batches (language analyzer
+// registry, per-language code-rot detectors) can select files by language
+// without re-deriving it from extensions themselves. Language detection is
+// classification-only here -- it does not imply parsing/analysis support for
+// python/java/kotlin exists yet.
+// ---------------------------------------------------------------------------
+export const NORMALIZED_LANGUAGES = [
+    "typescript",
+    "javascript",
+    "python",
+    "java",
+    "kotlin",
+    "json",
+    "markdown",
+    "yaml",
+    "xml",
+    "toml",
+    "unknown",
+];
+const EXTENSION_TO_LANGUAGE = {
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".mts": "typescript",
+    ".cts": "typescript",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".mjs": "javascript",
+    ".cjs": "javascript",
+    ".py": "python",
+    ".java": "java",
+    ".kt": "kotlin",
+    ".kts": "kotlin",
+    ".json": "json",
+    ".md": "markdown",
+    ".markdown": "markdown",
+    ".yml": "yaml",
+    ".yaml": "yaml",
+    ".xml": "xml",
+    ".toml": "toml",
+};
+function classifyLanguage(extension) {
+    return EXTENSION_TO_LANGUAGE[extension] ?? "unknown";
+}
+export const FILE_ROLES = [
+    "source",
+    "test",
+    "docs",
+    "config",
+    "package",
+    "generated",
+    "build-output",
+    "vendor",
+    "report-output",
+    "unknown",
+];
+// Path-segment markers used only when a file wasn't already excluded from
+// traversal entirely (EXCLUDED_DIR_NAMES below) -- e.g. paths reachable from
+// nested benchmark/fixture projects, or directories not yet in the hard
+// exclusion set. Deliberately conservative: matched as whole path segments,
+// not substrings.
+const VENDOR_PATH_SEGMENTS = new Set(["node_modules", "vendor"]);
+const BUILD_OUTPUT_PATH_SEGMENTS = new Set(["dist", "build", "out", ".next", ".turbo", "target", ".gradle"]);
+const GENERATED_PATH_SEGMENTS = new Set([
+    "generated",
+    ".cache",
+    ".my-dev-kit",
+    ".my-dev-kit-v1",
+    ".my-dev-kit-lab",
+]);
+const REPORT_OUTPUT_PATH_SEGMENTS = new Set(["reports", "lab-output"]);
+function classifyFileRole(relativePath, basename, extension, category) {
+    const segments = relativePath.split("/");
+    if (category === "report" ||
+        isStrayReportFile(basename) ||
+        segments.some((s) => REPORT_OUTPUT_PATH_SEGMENTS.has(s))) {
+        return "report-output";
+    }
+    if (segments.some((s) => VENDOR_PATH_SEGMENTS.has(s)))
+        return "vendor";
+    if (extension === ".tsbuildinfo" || segments.some((s) => BUILD_OUTPUT_PATH_SEGMENTS.has(s)))
+        return "build-output";
+    if (extension === ".map" || segments.some((s) => GENERATED_PATH_SEGMENTS.has(s)))
+        return "generated";
+    switch (category) {
+        case "tests":
+            return "test";
+        case "docs":
+            return "docs";
+        case "package":
+            return "package";
+        case "config":
+        case "ci":
+            return "config";
+        case "source":
+        case "scripts":
+            return "source";
+        default:
+            return "unknown";
+    }
+}
 // Directory names excluded from traversal entirely -- never descended into.
 const EXCLUDED_DIR_NAMES = new Set([
     "node_modules",
@@ -96,6 +202,24 @@ const KNOWN_SOURCE_EXTENSIONS = new Set([
     ".go",
     ".rs",
     ".java",
+    // v0.3.1 Batch 2 fix: .kt/.kts were classified as a NormalizedLanguage
+    // ("kotlin") since Batch 1 but were missing here, so a Kotlin file under
+    // src/ got category "unknown" (role "unknown") instead of "source" --
+    // silently excluding it from source-facts collection. .go/.rs above are
+    // intentionally left as "source" despite having no NormalizedLanguage
+    // mapping yet (they normalize to language "unknown"), which is the
+    // legitimate "known role, unknown language" case collectSourceFacts.ts's
+    // fallback policy handles.
+    ".kt",
+    ".kts",
+    // v0.3.1 Batch 3 fix: same class of gap as the .kt/.kts fix above -- .mts
+    // and .cts were mapped to NormalizedLanguage "typescript" since Batch 1
+    // but were missing here, so a .mts/.cts file under src/ got category
+    // "unknown" (role "unknown") and would never reach the Batch 3
+    // TypeScript/JavaScript analyzer's eligibility filter (role source/test
+    // only, see collectSourceFacts.ts).
+    ".mts",
+    ".cts",
 ]);
 // A file this large or larger is skipped entirely (not even stat'd into the
 // inventory) -- protects against pathological huge-file scan cost.
@@ -123,6 +247,8 @@ export function scanProjectInventory(targetRoot, options = {}) {
     }
     const filesByCategory = countByCategory(files);
     const filesByExtension = countByExtension(files);
+    const filesByLanguage = countByLanguage(files);
+    const filesByRole = countByRole(files);
     const excludedDirectorySummary = [...excludedDirCounts.entries()]
         .map(([name, occurrences]) => ({ name, occurrences }))
         .sort((a, b) => a.name.localeCompare(b.name));
@@ -134,6 +260,8 @@ export function scanProjectInventory(targetRoot, options = {}) {
         skippedFileCount,
         filesByCategory,
         filesByExtension,
+        filesByLanguage,
+        filesByRole,
         packageFiles: files.filter((f) => f.category === "package"),
         docsFiles: files.filter((f) => f.category === "docs"),
         sourceFiles: files.filter((f) => f.category === "source"),
@@ -192,11 +320,19 @@ export function scanProjectInventory(targetRoot, options = {}) {
             const relativePath = relativeWithinRoot(resolvedRoot, fullPath);
             const extension = path.extname(entry.name).toLowerCase();
             const category = classifyFile(relativePath, entry.name, extension);
+            const language = classifyLanguage(extension);
+            const role = classifyFileRole(relativePath, entry.name, extension, category);
             const entryResult = {
                 relativePath,
                 normalizedPath: relativePath.toLowerCase(),
                 extension,
                 category,
+                language,
+                role,
+                isGenerated: role === "generated",
+                isBuildOutput: role === "build-output",
+                isVendor: role === "vendor",
+                isReportOutput: role === "report-output",
                 sizeBytes: stat.size,
                 likelyGenerated: category === "generated" || category === "report",
                 likelyConfig: category === "config" || category === "package",
@@ -297,6 +433,20 @@ function countByCategory(files) {
     }
     return counts;
 }
+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 countByRole(files) {
+    const counts = Object.fromEntries(FILE_ROLES.map((r) => [r, 0]));
+    for (const file of files) {
+        counts[file.role] += 1;
+    }
+    return counts;
+}
 function countByExtension(files) {
     const counts = new Map();
     for (const file of files) {

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

@@ -0,0 +1,17 @@
+// ---------------------------------------------------------------------------
+// v0.3.1 Batch 2 -- normalized source facts model.
+//
+// Purely additive substrate: no concrete language analyzer exists yet (that
+// is Batch 3's TypeScript/JavaScript analyzer), so every SourceFileFacts
+// produced in this batch is either a deterministic fallback (see
+// collectSourceFacts.ts) or a parse-error record. The fact arrays
+// (imports/exports/declarations/references) are always empty in this batch
+// -- the shape exists so Batch 3 can populate them without a type change.
+// ---------------------------------------------------------------------------
+export const SOURCE_FACT_PARSE_STATUSES = [
+    "parsed",
+    "file-level-only",
+    "unsupported",
+    "parse-error",
+    "skipped",
+];

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,
+    };
+}

package/dist/src/audits/report/auditReportModel.js

@@ -22,6 +22,8 @@ export function summarizeInventory(inventory) {
         skippedFileCount: inventory.skippedFileCount,
         filesByCategory: inventory.filesByCategory,
         filesByExtension: inventory.filesByExtension,
+        filesByLanguage: inventory.filesByLanguage,
+        filesByRole: inventory.filesByRole,
         excludedDirectorySummary: inventory.excludedDirectorySummary,
         warnings: inventory.warnings,
     };
@@ -47,6 +49,15 @@ export function summarizeSourceOfTruth(sourceOfTruth) {
         warnings: sourceOfTruth.warnings,
     };
 }
+export function summarizeSourceFacts(sourceFacts) {
+    return {
+        totalFilesAnalyzed: sourceFacts.files.length,
+        filesByLanguage: sourceFacts.filesByLanguage,
+        filesByParseStatus: sourceFacts.filesByParseStatus,
+        analyzerDiagnosticCount: sourceFacts.analyzerDiagnostics.length,
+        warnings: sourceFacts.warnings,
+    };
+}
 const MAX_JSON_RECOMMENDATIONS = 200;
 const MAX_TEXT_RECOMMENDATIONS = 10;
 const SEVERITY_ORDER = ["blocker", "high", "medium", "low", "info"];
@@ -176,6 +187,7 @@ export function buildAuditReportModel(result, opts) {
         },
         inventory: summarizeInventory(result.inventory),
         sourceOfTruth: summarizeSourceOfTruth(result.sourceOfTruth),
+        sourceFacts: summarizeSourceFacts(result.sourceFacts),
         detectors,
         issues,
         skippedDetectors: result.skippedDetectors,

package/dist/src/audits/report/renderAuditJsonReport.js

@@ -18,6 +18,7 @@ export function renderAuditJsonReport(model) {
         summary: model.summary,
         inventory: model.inventory,
         sourceOfTruth: model.sourceOfTruth,
+        sourceFacts: model.sourceFacts,
         detectors: model.detectors,
         issues: model.issues,
         skippedDetectors: model.skippedDetectors,

package/dist/src/audits/report/renderAuditTextReport.js

@@ -70,10 +70,20 @@ export function renderAuditTextReport(model) {
     lines.push(divider("-"));
     lines.push(`  total=${model.inventory.totalFileCount} scanned=${model.inventory.totalScannedFileCount} skipped=${model.inventory.skippedFileCount}`);
     lines.push(`  source=${model.inventory.filesByCategory.source} tests=${model.inventory.filesByCategory.tests} docs=${model.inventory.filesByCategory.docs} package=${model.inventory.filesByCategory.package} config=${model.inventory.filesByCategory.config} scripts=${model.inventory.filesByCategory.scripts} ci=${model.inventory.filesByCategory.ci} generated=${model.inventory.filesByCategory.generated} report=${model.inventory.filesByCategory.report} unknown=${model.inventory.filesByCategory.unknown}`);
+    lines.push(`  languages: typescript=${model.inventory.filesByLanguage.typescript} javascript=${model.inventory.filesByLanguage.javascript} python=${model.inventory.filesByLanguage.python} java=${model.inventory.filesByLanguage.java} kotlin=${model.inventory.filesByLanguage.kotlin} json=${model.inventory.filesByLanguage.json} markdown=${model.inventory.filesByLanguage.markdown} yaml=${model.inventory.filesByLanguage.yaml} xml=${model.inventory.filesByLanguage.xml} toml=${model.inventory.filesByLanguage.toml} unknown=${model.inventory.filesByLanguage.unknown}`);
+    lines.push(`  roles: source=${model.inventory.filesByRole.source} test=${model.inventory.filesByRole.test} docs=${model.inventory.filesByRole.docs} config=${model.inventory.filesByRole.config} package=${model.inventory.filesByRole.package} generated=${model.inventory.filesByRole.generated} build-output=${model.inventory.filesByRole["build-output"]} vendor=${model.inventory.filesByRole.vendor} report-output=${model.inventory.filesByRole["report-output"]} unknown=${model.inventory.filesByRole.unknown}`);
     if (model.inventory.warnings.length > 0) {
         lines.push(`  warnings: ${model.inventory.warnings.length}`);
     }
     lines.push("");
+    lines.push("Source facts summary");
+    lines.push(divider("-"));
+    lines.push(`  analyzed=${model.sourceFacts.totalFilesAnalyzed}`);
+    lines.push(`  parsed=${model.sourceFacts.filesByParseStatus.parsed} file-level-only=${model.sourceFacts.filesByParseStatus["file-level-only"]} unsupported=${model.sourceFacts.filesByParseStatus.unsupported} parse-error=${model.sourceFacts.filesByParseStatus["parse-error"]} skipped=${model.sourceFacts.filesByParseStatus.skipped}`);
+    if (model.sourceFacts.analyzerDiagnosticCount > 0) {
+        lines.push(`  analyzer diagnostics: ${model.sourceFacts.analyzerDiagnosticCount}`);
+    }
+    lines.push("");
     lines.push("Source-of-truth summary");
     lines.push(divider("-"));
     lines.push(`  package: ${model.sourceOfTruth.packageName ?? "(none)"}@${model.sourceOfTruth.packageVersion ?? "?"}`);
@@ -153,12 +163,18 @@ function renderIssueBlock(issue) {
     lines.push(`      severity=${issue.severity} confidence=${issue.confidence} category=${sanitizeLine(issue.category)}`);
     lines.push(`      detector=${issue.detectorId} id=${issue.id}`);
     for (const evidence of issue.evidence.slice(0, MAX_EVIDENCE_PER_ISSUE)) {
+        // v0.3.1 Batch 5 -- an evidence entry's `message` (the human-readable
+        // "why") and `excerpt` (a quoted snippet/reference list) are
+        // independent fields on the same entry -- render both when both are
+        // present. Previously an `excerpt` silently suppressed `message`
+        // entirely, which dropped the only readable explanation for
+        // source-facts-derived findings (e.g. duplicateImplementationDetector's
+        // "Source facts: an exported ... was parsed in N distinct files.") and
+        // left only a bare file-path excerpt in text output.
+        lines.push(`      > ${sanitizeLine(evidence.message)}`);
         if (evidence.excerpt) {
             lines.push(...renderQuotedExcerpt(evidence.excerpt, "      "));
         }
-        else {
-            lines.push(`      > ${sanitizeLine(evidence.message)}`);
-        }
     }
     lines.push(`      recommendedAction: ${sanitizeLine(issue.recommendedAction)}`);
     return lines;

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "@dailephd/my-dev-kit-lab",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "description": "Evidence, benchmark, and evaluation companion for my-dev-kit.",
   "bin": {
     "my-dev-kit-lab": "dist/scripts/run-final-demo.js"
   },
-  "files": [
-    "dist/scripts/",
-    "dist/src/",
-    "benchmarks/",
+  "files": [
+    "dist/scripts/",
+    "!dist/scripts/docs/",
+    "dist/src/",
+    "benchmarks/",
     "docs/METRICS.md",
     "examples/",
     "tests/fixtures/"
@@ -63,6 +64,8 @@
     "experiment:list": "tsx scripts/experiments/listExperiments.ts",
     "experiment:describe": "tsx scripts/experiments/describeExperiment.ts",
     "experiment:run": "tsx scripts/experiments/runExperiment.ts",
+    "ecosystem:sync": "tsx scripts/docs/syncEcosystemDocs.ts",
+    "ecosystem:check": "tsx scripts/docs/checkEcosystemDocs.ts",
     "run-final-demo": "tsx scripts/run-final-demo.ts",
     "run-agent-prompt": "tsx scripts/run-agent-prompt.ts",
     "run-controlled-experiment": "tsx scripts/run-controlled-experiment.ts",