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

package/README.md

@@ -1,10 +1,10 @@
 # my-dev-kit-lab
 
-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-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.2`. `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; `v0.3.2` added Python-aware code-rot support and a first security-validation audit adapter. 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 implementation is ahead of the published baseline: release-prepared, not-yet-published `v0.3.3` work adds Java/Kotlin source-facts support and JVM-aware code-rot detector integration on top of the published `v0.3.2` baseline. Package metadata is now `0.3.3` as part of release preparation. Java/Kotlin support is conservative static analysis only: dependency-free scanners, static Gradle/Maven metadata detection, and no compiler, classpath, Gradle, Maven, Android, or target-test execution. 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.
 
@@ -33,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 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.
+- 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, TypeScript/JavaScript, Python, Java, and Kotlin analyzers, and conservative detector integrations for `dead-code-candidate`, `duplicate-implementation-candidate`, `test-rot`, and `docs-code-mismatch`. Python project metadata remains a top-level audit report field. Java/Kotlin support adds static JVM project metadata detection for Gradle/Maven/source-set shape and conservative source-facts evidence, but no compiler parsing, type resolution, classpath resolution, Gradle/Maven execution, Android validation, or target-project test execution. No `SourceFacts` schema change or new audit command was added for `v0.3.3`.
+- 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,16 +205,18 @@ 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 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
+## 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.2`, which includes the generic audit framework, the code-rot detector family, the language-aware code-rot substrate with TypeScript/JavaScript and Python support, and a first security-validation audit adapter, on top of the earlier experiment and automated security-validation work.
+
+The release-prepared, not-yet-published `v0.3.3` implementation extends that baseline with Java/Kotlin analyzers, JVM metadata detection, Java/Kotlin detector support, and Java/Kotlin/Gradle/Maven docs-code-mismatch checks. This work is documented here as checked-out behavior, not as a published package state; package metadata is now `0.3.3`, while `v0.3.2` remains the previous published baseline until publication completes.
+
+Planned roadmap direction after the published baseline:
+
+- `v0.3.3`: Java/Kotlin code-rot support (release-prepared, not yet published)
+- `v0.3.4`: 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
 
 ---
 
@@ -220,6 +224,8 @@ Planned roadmap direction after the published baseline:
 
 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
@@ -250,7 +256,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. 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.
+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,9 +80,15 @@ 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}`);

package/dist/scripts/security/validate.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-import path from "node:path";
-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 { renderTextReport } from "../../src/securityValidation/report/renderSecurityReport.js";
+import { writeSecurityReportFiles } from "../../src/securityValidation/report/writeSecurityReportFiles.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,55 +81,24 @@ 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
 const reportsDir = config.out;
-if (!fs.existsSync(reportsDir)) {
-    fs.mkdirSync(reportsDir, { recursive: true });
-}
 // Determine report filename prefix
 const prefix = args.reportPrefix ?? reportFilenamePrefix(target);
-const txtPath = path.join(reportsDir, `${prefix}-security-validation.txt`);
-const jsonPath = path.join(reportsDir, `${prefix}-security-validation.json`);
-const writtenPaths = [];
-if (config.formats.includes("text")) {
-    fs.writeFileSync(txtPath, textReport, "utf8");
-    writtenPaths.push(txtPath);
-}
-if (config.formats.includes("json")) {
-    fs.writeFileSync(jsonPath, jsonReport, "utf8");
-    writtenPaths.push(jsonPath);
-}
+const { textPath: txtPath, jsonPath, writtenPaths } = writeSecurityReportFiles({
+    outDir: reportsDir,
+    prefix,
+    report,
+    formats: config.formats,
+});
 // Print report to stdout
 console.log(textReport);
 console.log(`\nReports written:`);

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

@@ -1,8 +1,9 @@
 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";
+import { isJvmLifecycleOrConventionalDeclarationName, jvmImportSimpleName } from "../utils/jvmSourceFactsUtils.js";
 // ---------------------------------------------------------------------------
 // v0.3.0 Batch 4 — dead-code candidate detector.
 //
@@ -50,6 +51,10 @@ 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));
+            issues.push(...findPossiblyUnreferencedJvmDeclarations(ctx));
+        }
         return deduplicateIssuesById(issues);
     },
 };
@@ -250,6 +255,191 @@ function buildSourceFactsEvidence(facts) {
         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;
+}
+// v0.3.3 Batch 2 -- conservative, declaration-level Java/Kotlin dead-code
+// candidate check. Same spirit and lowest severity/confidence tier as
+// findPossiblyUnreferencedPythonDeclarations() above, adapted for the two
+// key differences in what Java/Kotlin source facts can safely support:
+//
+//   - Method/constructor declarations (DeclarationFactKind "method") are
+//     EXCLUDED ENTIRELY, for both languages. There is no call-tracking
+//     evidence in this project's source-facts model for any language
+//     (`references` stays empty everywhere -- see javaAnalyzer.ts's and
+//     kotlinAnalyzer.ts's own header comments), so a method-level check
+//     would have zero real evidence behind it and would flag nearly every
+//     method with equal (lack of) signal -- pure noise. This mirrors the
+//     existing Python check's own "methods are excluded entirely" rule
+//     exactly (see above), just extended to two more languages. This also
+//     conservatively covers Java constructors without needing a dedicated
+//     constructor detector, since javaAnalyzer.ts represents constructors
+//     as kind "method" too.
+//   - Kotlin top-level `fun` declarations (kind "function") ARE
+//     considered, the direct analogue of Python's module-level `def` --
+//     but Java has no equivalent (every Java method lives inside a
+//     class/interface/enum), so only class/interface/enum kinds are
+//     considered for Java.
+//
+// `exported` already folds Java's public/protected/private/package-private
+// and Kotlin's public/internal/protected/private visibility into a single
+// boolean (see both analyzers' "Visibility mapping" header comments) --
+// exported (public) declarations are skipped entirely here, since a public
+// API is expected to be used from outside the scanned file set and this
+// scan has no way to see that.
+function findPossiblyUnreferencedJvmDeclarations(ctx) {
+    if (!ctx.sourceFacts)
+        return [];
+    const index = indexSourceFactsByPath(ctx.sourceFacts);
+    // Cross-file "this simple name was imported somewhere" signal, combined
+    // across Java and Kotlin since either language can import the other in a
+    // mixed JVM project -- the strongest signal this conservative scan can
+    // offer, same role as Python's importedNamesAcrossProject above.
+    const importedSimpleNamesAcrossProject = new Set();
+    for (const facts of index.values()) {
+        if ((facts.language !== "java" && facts.language !== "kotlin") || facts.parseStatus !== "parsed")
+            continue;
+        for (const imp of facts.imports) {
+            importedSimpleNamesAcrossProject.add(jvmImportSimpleName(imp.source));
+        }
+    }
+    const issues = [];
+    for (const facts of index.values()) {
+        if (facts.language !== "java" && facts.language !== "kotlin")
+            continue;
+        if (facts.role !== "source" || facts.parseStatus !== "parsed")
+            continue;
+        for (const decl of facts.declarations) {
+            if (decl.kind === "method")
+                continue; // methods/constructors -- see header comment
+            if (facts.language === "java" && decl.kind === "function")
+                continue; // never produced by javaAnalyzer.ts, defensive
+            if (decl.exported)
+                continue; // public (Java) / public-by-default-or-explicit (Kotlin)
+            if (isJvmLifecycleOrConventionalDeclarationName(decl.name))
+                continue;
+            if (importedSimpleNamesAcrossProject.has(decl.name))
+                continue;
+            const languageLabel = facts.language === "java" ? "Java" : "Kotlin";
+            issues.push(makeCodeRotIssue({
+                auditType: "code-rot",
+                detectorId: DETECTOR_ID,
+                idCues: [`unreferenced-${facts.language}-declaration`, facts.relativePath, decl.kind, decl.name],
+                title: `${languageLabel} ${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 is not exported/public, and does not appear as an imported simple name in any other scanned Java/Kotlin file. This is a deterministic static source-facts signal from a conservative, non-semantic scan -- no compiler/classpath analysis was performed, and no Gradle/Maven execution was performed, so this cannot see reflection-based access, dependency-injection wiring, framework/plugin discovery, or usage from outside the scanned project. It may indicate a candidate for removal 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 ${languageLabel} analyzer parsed this file and found no other scanned Java/Kotlin file importing the simple name "${decl.name}". Static-analysis limitation -- confidence reduced because this scan cannot see reflection/DI usage, framework discovery, or usage outside the scanned file set, and no compiler/classpath analysis was performed.`,
+                        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) {