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

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

@@ -0,0 +1,38 @@
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 3 — shared code-rot issue construction helpers.
+//
+// Issue ids are content-addressed (detectorId + a stable, relative-path-only
+// cue) rather than counter-based, so the same underlying problem always
+// produces the same id across runs -- this is what makes de-duplication and
+// "stable issue ids" (Batch 3 spec 3.8) trivial: two candidate issues with
+// the same id are the same issue.
+// ---------------------------------------------------------------------------
+// Builds a deterministic id from a detector id and one or more relative-path
+// or short-string cues. Never embeds an absolute path -- callers must pass
+// already-relative paths (e.g. from InventoryFileEntry.relativePath).
+export function makeIssueId(detectorId, ...cues) {
+    const sanitizedCues = cues.map((cue) => cue.replace(/\\/g, "/"));
+    return [detectorId, ...sanitizedCues].join(":");
+}
+export function makeCodeRotIssue(input) {
+    const { idCues, evidence, affectedFiles, ...rest } = input;
+    return {
+        ...rest,
+        id: makeIssueId(rest.detectorId, ...idCues),
+        evidence: evidence ?? [],
+        affectedFiles: affectedFiles ?? [],
+    };
+}
+// Deduplicates a list of already-built issues by id, keeping the first
+// occurrence and preserving overall array order (stable de-duplication).
+export function deduplicateIssuesById(issues) {
+    const seen = new Set();
+    const result = [];
+    for (const issue of issues) {
+        if (seen.has(issue.id))
+            continue;
+        seen.add(issue.id);
+        result.push(issue);
+    }
+    return result;
+}

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/codeRot/utils/textLines.js

@@ -0,0 +1,12 @@
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 3 (moved in Batch 6) — shared line-splitting helper.
+//
+// The canonical implementation now lives in src/audits/core/textLines.ts
+// (core is lower-level than codeRot, and src/audits/core/sourceOfTruth.ts
+// needed the same helper -- see that file's header comment). This module is
+// kept as a transparent re-export so every existing codeRot detector/util
+// that imports `splitLines` from "../utils/textLines.js" (or
+// "./textLines.js") keeps working unchanged -- named-export re-exports are
+// transparent to importers, there is no behavior difference.
+// ---------------------------------------------------------------------------
+export { splitLines } from "../../core/textLines.js";

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

@@ -0,0 +1,125 @@
+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";
+const FLAGS_WITH_VALUE = {
+    "--target": "target",
+    "--types": "types",
+    "--include": "include",
+    "--format": "format",
+    "--fail-on": "failOn",
+    "--out": "out",
+};
+export function parseAuditArgs(argv) {
+    const result = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const key = FLAGS_WITH_VALUE[arg];
+        if (!key)
+            continue;
+        if (i + 1 >= argv.length) {
+            throw new Error(`Missing value for ${arg}. Expected a value after ${arg}.`);
+        }
+        result[key] = argv[++i];
+    }
+    return result;
+}
+export function normalizeAuditConfig(raw, toolRoot) {
+    const types = parseTypesOption(raw.types);
+    const include = parseIncludeOption(raw.include);
+    const formats = parseFormatOption(raw.format);
+    const failOn = parseFailOnOption(raw.failOn);
+    const out = raw.out !== undefined ? resolveOutDir(raw.out) : defaultOutDir(toolRoot, types.value);
+    return {
+        targetPathArg: raw.target,
+        targetMode: raw.target === undefined ? "self" : "external",
+        types: types.value,
+        typesWereDefault: types.wasDefault,
+        include: include.value,
+        includeWereDefault: include.wasDefault,
+        formats: formats.value,
+        formatsWereDefault: formats.wasDefault,
+        failOn: failOn.value,
+        failOnWasDefault: failOn.wasDefault,
+        out,
+        outWasDefault: raw.out === undefined,
+        isDefaultRun: raw.target === undefined &&
+            raw.types === undefined &&
+            raw.include === undefined &&
+            raw.format === undefined &&
+            raw.failOn === undefined &&
+            raw.out === undefined,
+    };
+}
+function splitAndNormalizeList(raw, flagName) {
+    const parts = raw.split(",").map((p) => p.trim());
+    if (parts.some((p) => p.length === 0)) {
+        throw new Error(`Invalid ${flagName} value: empty entries are not allowed. Got "${raw}".`);
+    }
+    return parts;
+}
+function parseTypesOption(raw) {
+    if (raw === undefined) {
+        return { value: [...DEFAULT_AUDIT_TYPES], wasDefault: true };
+    }
+    const parts = splitAndNormalizeList(raw, "--types");
+    const unknown = parts.filter((p) => !AUDIT_TYPES.includes(p));
+    if (unknown.length > 0) {
+        throw new Error(`Invalid --types value(s): ${unknown.join(", ")}. Valid values are: ${AUDIT_TYPES.join(", ")}.`);
+    }
+    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.`);
+    }
+    const unique = new Set(parts);
+    const ordered = AUDIT_TYPES.filter((id) => unique.has(id));
+    return { value: ordered, wasDefault: false };
+}
+function parseIncludeOption(raw) {
+    if (raw === undefined) {
+        return { value: [...DEFAULT_AUDIT_INCLUDE_AREAS], wasDefault: true };
+    }
+    const parts = splitAndNormalizeList(raw, "--include");
+    const invalid = parts.filter((p) => !AUDIT_INCLUDE_AREAS.includes(p));
+    if (invalid.length > 0) {
+        throw new Error(`Invalid --include value(s): ${invalid.join(", ")}. Valid values are: ${AUDIT_INCLUDE_AREAS.join(", ")}.`);
+    }
+    const unique = new Set(parts);
+    const ordered = AUDIT_INCLUDE_AREAS.filter((id) => unique.has(id));
+    return { value: ordered, wasDefault: false };
+}
+function parseFormatOption(raw) {
+    if (raw === undefined) {
+        return { value: [...DEFAULT_AUDIT_OUTPUT_FORMATS], wasDefault: true };
+    }
+    const parts = splitAndNormalizeList(raw, "--format");
+    const invalid = parts.filter((p) => !AUDIT_OUTPUT_FORMATS.includes(p));
+    if (invalid.length > 0) {
+        throw new Error(`Invalid --format value(s): ${invalid.join(", ")}. Valid values are: ${AUDIT_OUTPUT_FORMATS.join(", ")}.`);
+    }
+    const unique = new Set(parts);
+    const ordered = AUDIT_OUTPUT_FORMATS.filter((id) => unique.has(id));
+    return { value: ordered, wasDefault: false };
+}
+function parseFailOnOption(raw) {
+    if (raw === undefined) {
+        return { value: DEFAULT_AUDIT_FAIL_ON_THRESHOLD, wasDefault: true };
+    }
+    const value = raw.trim();
+    if (!AUDIT_FAIL_ON_THRESHOLDS.includes(value)) {
+        throw new Error(`Invalid --fail-on value: "${raw}". Valid values are: ${AUDIT_FAIL_ON_THRESHOLDS.join(", ")}.`);
+    }
+    return { value: value, wasDefault: false };
+}
+function resolveOutDir(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) {
+        throw new Error("Invalid --out value: path must not be empty.");
+    }
+    return path.resolve(trimmed);
+}
+function defaultOutDir(toolRoot, types) {
+    // Batch 1 only ever has "code-rot" as a valid resolved type, but this stays
+    // written generically so later batches (quality/security/project) don't
+    // need to touch this function, only extend the audit-type vocabulary.
+    const primaryType = types[0] ?? "code-rot";
+    return path.join(path.resolve(toolRoot), "reports", "audits", primaryType);
+}

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

@@ -0,0 +1,75 @@
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 1 — audit exit code policy.
+//
+// 0 = no issue met the --fail-on threshold (and no config/target/runtime
+//     error occurred).
+// 1 = at least one issue met or exceeded the --fail-on threshold.
+// 2 = invalid config, invalid target, or an audit runtime failure. This
+//     code is never returned by calculateAuditExitCode() below (a pure,
+//     issue-driven function) -- it is the caller's (scripts/audits/
+//     runAudit.ts) responsibility to catch parse/config/target errors and
+//     exit with AUDIT_EXIT_CODES.FATAL_ERROR directly, mirroring how
+//     scripts/security/validate.ts handles its own parse/target try/catch.
+// ---------------------------------------------------------------------------
+export const AUDIT_EXIT_CODES = {
+    SUCCESS: 0,
+    THRESHOLD_BREACHED: 1,
+    FATAL_ERROR: 2,
+};
+// "info" is a valid issue severity but is intentionally below every
+// selectable --fail-on threshold (including "low") -- it can never breach.
+const SEVERITY_RANK = {
+    info: 0,
+    low: 1,
+    medium: 2,
+    high: 3,
+    blocker: 4,
+};
+// "none" ranks above every severity so it can never be breached.
+const THRESHOLD_RANK = {
+    low: 1,
+    medium: 2,
+    high: 3,
+    blocker: 4,
+    none: Number.POSITIVE_INFINITY,
+};
+export function issueBreachesFailOnThreshold(severity, failOn) {
+    if (failOn === "none")
+        return false;
+    return SEVERITY_RANK[severity] >= THRESHOLD_RANK[failOn];
+}
+// v0.3.0 Batch 5 — additive export. Report-building code (src/audits/report/
+// auditReportModel.ts) needs the same severity ranking to compute a
+// "highest severity present" summary field, and must not hardcode a second
+// copy of this table (see Batch 5 spec 3.2). Signature/behavior of the two
+// functions above is unchanged.
+export function getHighestSeverity(issues) {
+    if (issues.length === 0)
+        return null;
+    let highest = issues[0].severity;
+    for (const issue of issues) {
+        if (SEVERITY_RANK[issue.severity] > SEVERITY_RANK[highest]) {
+            highest = issue.severity;
+        }
+    }
+    return highest;
+}
+// Pure function: given a final issue list and the configured --fail-on
+// threshold, decides between SUCCESS and THRESHOLD_BREACHED. Never returns
+// FATAL_ERROR -- see file header.
+export function calculateAuditExitCode(issues, failOn) {
+    if (failOn === "none") {
+        return { exitCode: AUDIT_EXIT_CODES.SUCCESS, reason: "--fail-on none: findings never block the command." };
+    }
+    const breaching = issues.filter((issue) => issueBreachesFailOnThreshold(issue.severity, failOn));
+    if (breaching.length > 0) {
+        return {
+            exitCode: AUDIT_EXIT_CODES.THRESHOLD_BREACHED,
+            reason: `${breaching.length} issue(s) met or exceeded the --fail-on ${failOn} threshold.`,
+        };
+    }
+    return {
+        exitCode: AUDIT_EXIT_CODES.SUCCESS,
+        reason: `No issues met the --fail-on ${failOn} threshold.`,
+    };
+}

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

@@ -0,0 +1,20 @@
+export const AUDIT_EVIDENCE_KINDS = [
+    "file",
+    "command",
+    "diff",
+    "reference",
+    "observation",
+];
+const MAX_EXCERPT_LENGTH = 400;
+// Bounds an excerpt to a safe preview length so evidence never embeds huge
+// file contents. Does not attempt secret redaction here — detectors that
+// scan for secret-shaped content are responsible for redacting before this
+// point, same division of responsibility documented in exploitEvidence.ts.
+export function boundExcerpt(raw, maxLength = MAX_EXCERPT_LENGTH) {
+    if (raw.length <= maxLength)
+        return raw;
+    return `${raw.slice(0, maxLength)}... [truncated, ${raw.length} chars total]`;
+}
+export function makeAuditEvidence(evidence) {
+    return evidence.excerpt !== undefined ? { ...evidence, excerpt: boundExcerpt(evidence.excerpt) } : evidence;
+}

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

@@ -0,0 +1,40 @@
+import { STALE_COMMAND_REFERENCE_DETECTOR, DOCS_CODE_MISMATCH_DETECTOR, PACKAGE_RELEASE_ROT_DETECTOR, DUPLICATE_IMPLEMENTATION_DETECTOR, DEAD_CODE_CANDIDATE_DETECTOR, TEST_ROT_DETECTOR, ARCHITECTURE_DRIFT_DETECTOR, DEPENDENCY_ENVIRONMENT_ROT_DETECTOR, CROSS_PLATFORM_ROT_DETECTOR, SECURITY_VALIDATION_ASSUMPTION_ROT_DETECTOR, } from "../codeRot/codeRotDetectors.js";
+// v0.3.0 Batch 3/4 — code-rot detectors. Batch 4 completes the full
+// code-rot detector family planned in docs/ROADMAP.md's v0.3.0 section:
+// stale command/workflow reference, docs/code mismatch, package/release
+// rot (Batch 3), plus duplicate-implementation, dead-code, test-rot,
+// architecture-drift, dependency/environment-rot, cross-platform-rot, and
+// security/validation-assumption-rot (Batch 4).
+export const DEFAULT_AUDIT_REGISTRY = createAuditRegistry([
+    STALE_COMMAND_REFERENCE_DETECTOR,
+    DOCS_CODE_MISMATCH_DETECTOR,
+    PACKAGE_RELEASE_ROT_DETECTOR,
+    DUPLICATE_IMPLEMENTATION_DETECTOR,
+    DEAD_CODE_CANDIDATE_DETECTOR,
+    TEST_ROT_DETECTOR,
+    ARCHITECTURE_DRIFT_DETECTOR,
+    DEPENDENCY_ENVIRONMENT_ROT_DETECTOR,
+    CROSS_PLATFORM_ROT_DETECTOR,
+    SECURITY_VALIDATION_ASSUMPTION_ROT_DETECTOR,
+]);
+// Validates a detector list has no duplicate ids. Later batches call this
+// when assembling their own registries; Batch 1's empty default trivially
+// passes.
+export function createAuditRegistry(detectors) {
+    const seen = new Set();
+    for (const detector of detectors) {
+        if (seen.has(detector.id)) {
+            throw new Error(`Duplicate audit detector id: "${detector.id}".`);
+        }
+        seen.add(detector.id);
+    }
+    return detectors;
+}
+// Filters a registry down to detectors matching the selected audit types and
+// at least one selected include area. Order is preserved from the input
+// registry (deterministic, not re-sorted).
+export function selectDetectors(registry, types, include) {
+    const typeSet = new Set(types);
+    const includeSet = new Set(include);
+    return registry.filter((detector) => typeSet.has(detector.auditType) && detector.supportedIncludeAreas.some((area) => includeSet.has(area)));
+}

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

@@ -0,0 +1,74 @@
+import { calculateAuditExitCode } from "./auditExitCode.js";
+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, sourceFacts };
+    const issues = [];
+    const skippedDetectors = [];
+    const detectorErrors = [];
+    // Sequential, in registry order -- keeps issue ordering deterministic
+    // without needing a secondary sort step.
+    for (const detector of selected) {
+        try {
+            if (detector.shouldSkip) {
+                const decision = detector.shouldSkip(ctx);
+                if (decision.skip) {
+                    skippedDetectors.push({ id: detector.id, reason: decision.reason });
+                    continue;
+                }
+            }
+            const detectorIssues = await detector.run(ctx);
+            issues.push(...detectorIssues);
+        }
+        catch (err) {
+            detectorErrors.push({
+                id: detector.id,
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    const issueCounts = countIssuesBySeverity(issues);
+    const { exitCode, reason } = calculateAuditExitCode(issues, config.failOn);
+    return {
+        configSummary: {
+            types: config.types,
+            include: config.include,
+            formats: config.formats,
+            failOn: config.failOn,
+            out: config.out,
+            isDefaultRun: config.isDefaultRun,
+        },
+        targetSummary: {
+            rootPath: target.rootPath,
+            displayName: target.displayName,
+            isSelf: target.isSelf,
+        },
+        issues,
+        skippedDetectors,
+        detectorErrors,
+        issueCounts,
+        exitCode,
+        exitReason: reason,
+        inventory,
+        sourceOfTruth,
+        sourceFacts,
+        noDetectorsRegistered: selected.length === 0,
+    };
+}
+function countIssuesBySeverity(issues) {
+    const counts = { blocker: 0, high: 0, medium: 0, low: 0, info: 0 };
+    for (const issue of issues) {
+        counts[issue.severity] += 1;
+    }
+    return counts;
+}

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

@@ -0,0 +1,19 @@
+import path from "node:path";
+import { resolveLocalProjectTarget } from "../../core/localProjectTarget.js";
+// Resolves and validates an audit target. Throws a descriptive Error (no
+// stack trace wrapper) for a missing path or a non-directory path. Does not
+// modify the target in any way.
+export function resolveAuditTarget(targetPathArg, toolRoot) {
+    const metadata = resolveLocalProjectTarget(targetPathArg, toolRoot);
+    const displayName = metadata.packageName ?? path.basename(metadata.targetRoot);
+    return {
+        rootPath: metadata.targetRoot,
+        displayName,
+        exists: true,
+        isDirectory: true,
+        packageJsonPath: metadata.hasPackageJson ? path.join(metadata.targetRoot, "package.json") : null,
+        gitRoot: metadata.hasGit ? metadata.targetRoot : null,
+        isSelf: metadata.isSelf,
+        safeReportOutputRoot: path.join(path.resolve(toolRoot), "reports", "audits"),
+    };
+}

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

@@ -0,0 +1,30 @@
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 1 — generic audit framework core vocabulary.
+//
+// Deliberately kept separate from src/securityValidation/types.ts. Audit and
+// security-validation are two distinct frameworks (see docs/ROADMAP.md); a
+// later v0.3.2 batch may integrate their results into a unified report, but
+// 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.
+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 AUDIT_INCLUDE_AREAS = ["docs", "tests", "package", "architecture", "cli"];
+export const DEFAULT_AUDIT_INCLUDE_AREAS = AUDIT_INCLUDE_AREAS;
+export const AUDIT_OUTPUT_FORMATS = ["text", "json"];
+export const DEFAULT_AUDIT_OUTPUT_FORMATS = ["text", "json"];
+// "none" is a valid, explicit opt-out — findings never block the command.
+export const AUDIT_FAIL_ON_THRESHOLDS = ["blocker", "high", "medium", "low", "none"];
+export const DEFAULT_AUDIT_FAIL_ON_THRESHOLD = "blocker";
+// Issue severity. Distinct from AuditFailOnThreshold: "info" is a valid
+// issue severity but not a selectable --fail-on threshold (an info-severity
+// issue can never breach any threshold, including "low").
+export const AUDIT_SEVERITIES = ["blocker", "high", "medium", "low", "info"];
+export const AUDIT_CONFIDENCE_LEVELS = ["high", "medium", "low"];
+export const AUDIT_FALSE_POSITIVE_RISK_LEVELS = ["high", "medium", "low"];

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