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

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.
+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 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.
+The current published baseline is `v0.3.1`. `v0.3.0` introduced the generic audit framework and the first implemented code-rot detector family; `v0.3.1` added the language-aware code-rot substrate plus TypeScript/JavaScript support. 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 state is `v0.3.2` release-prepared on top of the published `v0.3.1` baseline: Python-aware code-rot support (a Python source-facts analyzer, Python project metadata, and Python-aware dead-code/duplicate-implementation/test-rot detector signals) and a security-validation audit adapter (`npm run audit -- --types security`, mapped security findings, and a `securitySummary` audit report field). Package metadata is bumped for release preparation, but `v0.3.2` is not published yet; Java, Kotlin, cross-language stability, Android validation, framework-aware profiles, and the `quality`/`project`/`all` 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.
 
@@ -31,8 +33,10 @@ my-dev-kit is most useful when the repository is larger than the task. It helps
 - First experiment plugin: `context-strategy-comparison`
 - 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.
+- 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>`. `security:validate` remains the standalone, focused security-validation command; it is not replaced by the audit adapter below.
+- Generic audit framework, current published baseline: `npm run audit` runs heuristic, conservative code-rot detectors and writes text/JSON reports under `reports/audits/code-rot/` by default. `code-rot` and `security` are the currently implemented audit types (`--types code-rot`, `--types security`, or combined `--types code-rot,security`); `quality`, `project`, and `all` audit types are planned and fail cleanly instead of running. `npm run audit` supports `--target`, `--types`, and other flags — see [docs/COMMANDS.md](docs/COMMANDS.md). Audit does not modify target files and does not auto-fix issues.
+- Language-aware code-rot support, current checked-out package state: normalized language/file-role inventory, a source-facts model and collector, a TypeScript/JavaScript analyzer, and a Python analyzer. Source facts feed the `dead-code-candidate`, `duplicate-implementation-candidate`, and `test-rot` detectors with parsed-import/export/declaration evidence for both languages. Python project metadata (presence of `pyproject.toml`, `requirements.txt`, `setup.py`/`setup.cfg`, `tox.ini`, `pytest.ini`, and a best-effort project name) is collected and reported as its own audit report field. Java and Kotlin remain inventory-classified but fallback-only; no analyzer is registered for them yet.
+- Security-validation audit adapter, current checked-out package state: `npm run audit -- --types security` runs security validation through the shared audit/report surface by calling the same `runSecurityValidation()` internals `security:validate` uses, maps security findings into audit-issue-shaped entries, and adds a `securitySummary` field (verdict, check counts, finding counts, and links to the original `reports/security/*.txt`/`*.json` report) to audit JSON/text reports. `npm run audit -- --types code-rot,security` runs both audit types together. The original `security:validate` command and its `reports/security/` output are unchanged.
 
 ---
 
@@ -203,7 +207,14 @@ 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.
+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.1`, which includes the generic audit framework, the code-rot detector family, and the language-aware code-rot substrate with TypeScript/JavaScript support, on top of the earlier experiment and automated security-validation work.
+
+Planned roadmap direction after the published baseline:
+
+- `v0.3.2`: Python code-rot support plus a first security-validation audit adapter, release-prepared and not yet published
+- `v0.3.3` through `v0.3.4`: Java/Kotlin and cross-language stability for the language-aware code-rot track
+- `v0.4.0` through `v0.4.2`: Android automated security validation, including an Android-specific extension of the security audit adapter
+- manual pentest: post-v1 / version TBD
 
 ---
 
@@ -211,6 +222,8 @@ my-dev-kit-lab is at a working baseline. The raw-vs-indexed experiment pipeline
 
 my-dev-kit-lab owns a release-security validation track for **my-dev-kit**. This work is separate from the experiment pipeline and does not replace the generic experiment-plugin roadmap. Its purpose is to generate release-validation evidence for the local CLI/package before release preparation.
 
+`security:validate` remains the standalone, focused command for this validation and is unaffected by the current checked-out state. `npm run audit -- --types security` additionally adapts the same `security:validate` internals into the shared audit/report surface (mapped issues, a `securitySummary` field, and links to the original `reports/security/` output) — it does not replace or duplicate `security:validate`'s own checks or reports.
+
 This is not a web application pentest framework. **my-dev-kit** is a local CLI/package, so the validation model is CLI/package adversarial testing focused on whether it remains:
 
 - local-first
@@ -241,7 +254,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

@@ -18,7 +18,7 @@ import { writeAuditReports } from "../../src/audits/report/writeAuditReports.js"
 // renderAuditJsonReport.ts, renderAuditTextReport.ts, writeAuditReports.ts.
 // Mirrors the structure of scripts/security/validate.ts.
 // ---------------------------------------------------------------------------
-const USAGE = "Usage: npm run audit -- [--target <path>] [--types code-rot] " +
+const USAGE = "Usage: npm run audit -- [--target <path>] [--types code-rot,security] " +
     "[--include docs,tests,package,architecture,cli] [--format text,json] " +
     "[--fail-on blocker|high|medium|low|none] [--out <path>]";
 const rawArgs = process.argv.slice(2);
@@ -80,12 +80,19 @@ if (model.summary.detectorErrorCount > 0) {
         console.log(`  [${e.id}] ${e.message}`);
     }
 }
-if (model.summary.noDetectorsRegistered) {
+if (model.summary.noDetectorsRegistered && !model.securitySummary.ran) {
     console.log(`Note: no code-rot detectors are registered for this run's --types/--include selection -- this run collected inventory/source-of-truth data only.`);
 }
+if (model.securitySummary.ran) {
+    console.log(`\nSecurity validation: verdict=${model.securitySummary.verdictLabel} checks=${model.securitySummary.totalChecks} findings(blocker=${model.securitySummary.findingCounts.blocker} major=${model.securitySummary.findingCounts.major} minor=${model.securitySummary.findingCounts.minor} info=${model.securitySummary.findingCounts.informational})`);
+    if (model.securitySummary.reportPaths.text) {
+        console.log(`  Full report: ${model.securitySummary.reportPaths.text}`);
+    }
+}
 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/scripts/security/validate.js

@@ -4,6 +4,7 @@ import fs from "node:fs";
 import { runSecurityValidation } from "../../src/securityValidation/validate/runSecurityValidation.js";
 import { resolveValidationTarget, reportFilenamePrefix } from "../../src/securityValidation/validate/resolveTarget.js";
 import { renderTextReport, renderJsonReport } from "../../src/securityValidation/report/renderSecurityReport.js";
+import { buildSecurityReportFromSummary } from "../../src/securityValidation/report/buildSecurityReport.js";
 import { parseSecurityValidateArgs, normalizeSecurityValidateConfig, applyProfileDefaultChecksIfApplicable, } from "../../src/securityValidation/validate/cliOptions.js";
 import { resolveAttackProfile } from "../../src/securityValidation/attackScenarios/attackProfile.js";
 import { findingsBreachFailOnThreshold } from "../../src/securityValidation/validate/verdict.js";
@@ -81,35 +82,13 @@ const summary = await runSecurityValidation({
 // downgrade an existing blocker.
 const failOnBreached = findingsBreachFailOnThreshold(summary.findings, config.failOnThreshold);
 // Build report object
-const report = {
-    metadata: {
-        toolRoot: summary.toolRoot,
-        toolPackageName: summary.toolPackageName,
-        toolPackageVersion: summary.toolPackageVersion,
-        targetRoot: summary.targetRoot,
-        targetDescription: summary.targetDescription,
-        packageName: summary.packageName,
-        packageVersion: summary.packageVersion,
-        branch: summary.auditedBranch,
-        commit: summary.auditedCommit,
-        isSelf: summary.isSelf,
-        generatedAt: summary.finishedAt,
-        totalDurationMs: new Date(summary.finishedAt).getTime() - new Date(summary.startedAt).getTime(),
-        profile: config.profile,
-        selectedChecks: config.checks,
-        failOnThreshold: config.failOnThreshold,
-        formats: config.formats,
-        failOnBreached,
-        isFullReleaseGate: summary.isFullReleaseGate,
-    },
-    sections: [],
-    allChecks: summary.checks,
-    allFindings: summary.findings,
-    verdict: summary.verdict,
-    recommendedNextStep: summary.recommendedNextStep,
-    attackResults: summary.attackResults,
-    verdictReasonSummary: summary.verdictReasonSummary,
-};
+const report = buildSecurityReportFromSummary(summary, {
+    profile: config.profile,
+    selectedChecks: config.checks,
+    failOnThreshold: config.failOnThreshold,
+    formats: config.formats,
+    failOnBreached,
+});
 const textReport = renderTextReport(report);
 const jsonReport = renderJsonReport(report);
 // Determine output directory

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

@@ -1,7 +1,8 @@
 import path from "node:path";
 import { readBoundedFileText } from "../utils/boundedRead.js";
-import { baseNameNoExt } from "../utils/filePatternUtils.js";
+import { baseNameNoExt, isGenericOrTestPrefixedDeclarationName } 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.
 //
@@ -49,6 +50,9 @@ export const DEAD_CODE_CANDIDATE_DETECTOR = {
         if (ctx.config.include.includes("tests")) {
             issues.push(...findUnreferencedFixtures(ctx));
         }
+        if (ctx.config.include.includes("cli") || ctx.config.include.includes("architecture")) {
+            issues.push(...findPossiblyUnreferencedPythonDeclarations(ctx));
+        }
         return deduplicateIssuesById(issues);
     },
 };
@@ -140,7 +144,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 +174,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 +198,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 +234,116 @@ 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",
+    };
+}
+// v0.3.2 Batch 2 -- conservative, declaration-level Python dead-code
+// candidate check. TS/JS module-level "unused exported symbol" detection is
+// explicitly SKIPPED in this file's own header comment (no safe/cheap way
+// without a real type-checker) -- this Python-only check is narrower and
+// safer than that skipped TS/JS idea would be, because Python source facts
+// already carry declarations *and* a repo-wide cross-file "imported name"
+// index (unlike anything comparable for TS/JS bare specifiers), so the
+// false-positive surface is much smaller. Every one of the skip conditions
+// below is a deliberate, spec-required conservatism -- see the requirements
+// list in this batch's task description. Findings stay at the lowest
+// severity/confidence tier in this detector's own schema (matches
+// findUnreferencedFixtures()'s tier) and use "candidate"/"may indicate"
+// wording throughout, never "unused" or "dead".
+function findPossiblyUnreferencedPythonDeclarations(ctx) {
+    if (!ctx.sourceFacts)
+        return [];
+    const index = indexSourceFactsByPath(ctx.sourceFacts);
+    // Cross-file "this name was imported somewhere" signal -- a declaration
+    // named here is referenced by at least one `from module import name`
+    // elsewhere in the scanned Python file set, which is the strongest signal
+    // this conservative scan can offer (Python source facts carry no
+    // call/identifier reference tracking -- see pythonAnalyzer.ts's header
+    // comment on why `references` stays empty by design).
+    const importedNamesAcrossProject = new Set();
+    for (const facts of index.values()) {
+        if (facts.language !== "python" || facts.parseStatus !== "parsed")
+            continue;
+        for (const imp of facts.imports) {
+            for (const name of imp.importedNames ?? [])
+                importedNamesAcrossProject.add(name);
+        }
+    }
+    const issues = [];
+    for (const facts of index.values()) {
+        if (facts.language !== "python" || facts.role !== "source" || facts.parseStatus !== "parsed")
+            continue;
+        // __init__.py commonly exists only to re-export a package's public
+        // surface or to mark a directory as a package -- its declarations (if
+        // any) are conservatively excluded entirely rather than guessed at.
+        if (path.basename(facts.relativePath) === "__init__.py")
+            continue;
+        for (const decl of facts.declarations) {
+            // Methods are excluded entirely -- this detector has no existing
+            // method-level dead-code evidence model for any language (TS/JS
+            // methods are never flagged either), and Python method visibility is
+            // even harder to infer safely (inherited/overridden/dispatched via
+            // duck typing).
+            if (decl.kind === "method")
+                continue;
+            if (!decl.exported)
+                continue; // leading-underscore convention already applied by pythonAnalyzer.ts
+            if (isGenericOrTestPrefixedDeclarationName(decl.name))
+                continue; // main/run/setup/teardown/__init__/__call__/test_*
+            // A name explicitly listed in a real `__all__` is the file's own
+            // strongest "this is public API" declaration -- skip rather than
+            // second-guess it.
+            if (facts.exports.some((e) => e.name === decl.name))
+                continue;
+            if (importedNamesAcrossProject.has(decl.name))
+                continue;
+            issues.push(makeCodeRotIssue({
+                auditType: "code-rot",
+                detectorId: DETECTOR_ID,
+                idCues: ["unreferenced-python-declaration", facts.relativePath, decl.kind, decl.name],
+                title: `Python ${decl.kind} "${decl.name}" in "${facts.relativePath}" has no detected cross-file import (weak signal)`,
+                description: `"${decl.name}" (${decl.kind}) is declared in "${facts.relativePath}" and does not appear as an imported name in any other scanned Python file. This is a deterministic source-facts signal from a conservative, non-semantic scan -- it does not resolve dynamic imports, framework/plugin discovery, string-based dispatch, or usage from outside the scanned project, so it may indicate dead code but is not proof. Confirm manually before removing.`,
+                severity: "info",
+                confidence: "low",
+                falsePositiveRisk: "high",
+                category: "dead-code-candidate",
+                recommendedAction: "Confirm the declaration is genuinely unused before removing it.",
+                suggestedFixStrategy: `Remove "${decl.name}" from "${facts.relativePath}" if confirmed unused, or reference it from another module.`,
+                validationCommands: ["npm run audit -- --types code-rot --include cli"],
+                releaseBlocking: false,
+                implementationBlocking: false,
+                autoFixEligible: false,
+                evidence: [
+                    {
+                        kind: "reference",
+                        message: `Source facts: the Python analyzer parsed this file and found no other scanned Python file importing the name "${decl.name}". Static-analysis limitation -- confidence reduced because this scan cannot see dynamic imports or usage outside the scanned file set.`,
+                        filePath: facts.relativePath,
+                        source: DETECTOR_ID,
+                        confidence: "low",
+                    },
+                ],
+                affectedFiles: [facts.relativePath],
+            }));
+        }
+    }
+    return issues;
+}
 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_INFRA_BASENAMES, baseNameNoExt, isGenericOrTestPrefixedDeclarationName, } 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,96 @@ 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/lifecycle declaration names (run, init, handler, __init__,
+// test_*, ...) are excluded via isGenericOrTestPrefixedDeclarationName() 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 (isGenericOrTestPrefixedDeclarationName(nameLower))
+                continue;
+            // v0.3.2 Batch 2 -- the key is scoped by `facts.analyzerId` (not
+            // `facts.language`) so a Python declaration is only ever compared
+            // against other Python declarations, never against a same-named
+            // TypeScript/JavaScript one. `analyzerId`, not `language`, is the
+            // right scope here: TypeScript and JavaScript are two different
+            // NormalizedLanguage values but share one analyzer
+            // (typescript-javascript-analyzer) and were already compared together
+            // before this batch -- scoping by `language` instead would have
+            // silently split that existing, still-desired TS/JS pairing in two
+            // (each side then below the "2+ files" threshold, so both would be
+            // dropped entirely), which is exactly the "preserve existing
+            // TypeScript/JavaScript duplicate behavior" regression this batch
+            // must not introduce. Scoping by `analyzerId` fixes the real
+            // cross-language bug (Python vs TS/JS) without touching TS/JS's own
+            // existing behavior at all.
+            const key = `${facts.analyzerId}:${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