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

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

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { collectJvmProjectMetadata } from "../../core/jvmProjectMetadata.js";
 import { currentClaimPatternFor, plannedClaimPatternFor, FULL_RELEASE_GATE_FOR_SCOPED_CHECKS_PATTERN, isNegatedNearby, } from "../utils/docClaimPatterns.js";
 import { deduplicateIssuesById, makeCodeRotIssue } from "../utils/issueFactories.js";
 import { splitLines } from "../utils/textLines.js";
@@ -27,20 +28,95 @@ const FEATURE_CHECKS = [
         featureId: "security-validation",
         label: "security validation",
         subjectPattern: "security validation",
-        isImplemented: (sot) => sot.security.hasSecurityValidationSourceDir && sot.security.hasSecurityValidateScript,
+        isImplemented: (ctx) => ctx.sourceOfTruth.security.hasSecurityValidationSourceDir && ctx.sourceOfTruth.security.hasSecurityValidateScript,
     },
     {
         featureId: "experiment-framework",
         label: "experiment framework",
         subjectPattern: "experiment (?:framework|plugin)",
-        isImplemented: (sot) => sot.experiment.hasExperimentsSourceDir && sot.experiment.hasExperimentListScript,
+        isImplemented: (ctx) => ctx.sourceOfTruth.experiment.hasExperimentsSourceDir && ctx.sourceOfTruth.experiment.hasExperimentListScript,
+    },
+    // v0.3.3 Batch 3 -- Gradle/Maven/Android feature-claim checks, using only
+    // static JVM metadata (see jvmProjectMetadata.ts). Never runs Gradle,
+    // Maven, or any Android tooling.
+    {
+        featureId: "gradle-support",
+        label: "Gradle",
+        subjectPattern: "Gradle",
+        isImplemented: (ctx) => ctx.jvmMetadata.hasGradleBuild || ctx.jvmMetadata.hasGradleSettings,
+    },
+    {
+        featureId: "maven-support",
+        label: "Maven",
+        subjectPattern: "Maven",
+        isImplemented: (ctx) => ctx.jvmMetadata.hasMavenPom,
+    },
+    {
+        featureId: "android-validation",
+        label: "Android validation",
+        // Negative lookbehind excludes "(non-Android)"-style negated mentions
+        // (this project's own docs legitimately describe things as
+        // "the general (non-Android) ... adapter", which is a claim about the
+        // *adapter*, not about Android -- without this guard, "is implemented"
+        // appearing later in the same sentence about the adapter would
+        // falsely match as an Android claim).
+        subjectPattern: "(?<!non-)Android(?: validation| support)?",
+        // Android automated validation is not implemented anywhere in this
+        // project (see the v0.3.x/v0.4.x roadmap) -- this is a permanently
+        // false signal, not a metadata lookup, so a claim that it is
+        // implemented/current is always a genuine mismatch until a future
+        // version actually builds it. This does not implement any Android
+        // detection itself (no AndroidManifest.xml/Gradle-Android-plugin/
+        // Compose/AGP/SDK/emulator awareness) -- it only reuses the existing
+        // current-vs-planned claim mechanism for a feature this project
+        // already knows, out of band, does not exist.
+        isImplemented: () => false,
     },
 ];
+// v0.3.3 Batch 3 -- backtick-quoted-only Java/Kotlin FQCN-shaped symbol
+// scan (T1-T4). Requiring the mention to be inside an inline code span
+// (`` `com.example.Foo` ``) is what keeps this conservative: ordinary prose
+// mentioning a capitalized word is extremely common and would be far too
+// noisy to scan directly, but a backtick-quoted, fully-dotted,
+// lowercase-package-then-Capitalized-name token is specifically how a
+// real symbol reference is conventionally written in markdown docs.
+const BACKTICK_SPAN_PATTERN = /`([^`]+)`/g;
+const JVM_FQCN_PATTERN = /^[a-z][\w]*(?:\.[a-z][\w]*)*\.[A-Z]\w*$/;
+// Reused by both the symbol-claim check and the Gradle/Maven command-claim
+// check below: a broader set of future/negative-boundary hedge phrases than
+// docClaimPatterns.ts's own HEDGE_PATTERN (which is narrowly scoped to
+// "not yet published"-style wording) -- this project's own docs
+// legitimately say things like "Android support is planned" or "does not
+// support Gradle yet", which must never be treated as a current-state claim.
+const JVM_FUTURE_OR_NEGATIVE_HEDGE_PATTERN = /\b(planned|future|deferred|not yet|out of scope|does not support|doesn't support|will support|not implemented|not supported)\b/i;
+const GRADLE_COMMAND_PATTERN = /\b(?:\.\/)?gradlew(?:\.bat)?\b|\bgradle\b/i;
+const MAVEN_COMMAND_PATTERN = /\bmvnw(?:\.cmd)?\b|\bmvn\b/i;
+// Declaration kinds treated as safe, implementation-weight symbol claims --
+// same conservative kind allowlist Batch 2's duplicate/dead-code checks
+// already use (methods/variables/constants excluded as too noisy/ambiguous
+// for a name-only, no-package-tracking cross-check).
+const JVM_SYMBOL_DECLARATION_KINDS = new Set(["class", "interface", "enum", "function"]);
+function collectKnownJvmDeclarationNames(ctx) {
+    const names = new Set();
+    if (!ctx.sourceFacts)
+        return names;
+    for (const file of ctx.sourceFacts.files) {
+        if (file.language !== "java" && file.language !== "kotlin")
+            continue;
+        if (file.parseStatus !== "parsed")
+            continue;
+        for (const decl of file.declarations) {
+            if (JVM_SYMBOL_DECLARATION_KINDS.has(decl.kind))
+                names.add(decl.name);
+        }
+    }
+    return names;
+}
 export const DOCS_CODE_MISMATCH_DETECTOR = {
     id: DETECTOR_ID,
     auditType: "code-rot",
     title: "Documentation/code mismatch",
-    description: "Detects deterministic mismatches between documentation claims and source-of-truth data: feature-implementation claims and full-release-gate-for-scoped-checks wording.",
+    description: "Detects deterministic mismatches between documentation claims and source-of-truth data: feature-implementation claims, full-release-gate-for-scoped-checks wording, and (v0.3.3) Java/Kotlin symbol claims plus Gradle/Maven feature/command claims against static JVM metadata.",
     supportedIncludeAreas: ["docs", "architecture", "cli", "package"],
     shouldSkip: (ctx) => {
         if (!ctx.config.include.includes("docs")) {
@@ -50,6 +126,13 @@ export const DOCS_CODE_MISMATCH_DETECTOR = {
     },
     run: (ctx) => {
         const issues = [];
+        // v0.3.3 Batch 3 -- computed once per run, same "cheap, static,
+        // presence-only" treatment as pythonMetadata/jvmMetadata elsewhere in
+        // this codebase (see testRotDetector.ts). Never runs Gradle/Maven/any
+        // JVM tooling.
+        const jvmMetadata = collectJvmProjectMetadata(ctx.target.rootPath, ctx.inventory);
+        const featureCtx = { sourceOfTruth: ctx.sourceOfTruth, jvmMetadata };
+        const knownJvmDeclarationNames = collectKnownJvmDeclarationNames(ctx);
         for (const docFile of ctx.inventory.docsFiles) {
             const content = readBoundedText(ctx.target.rootPath, docFile.relativePath, docFile.sizeBytes);
             if (content === null)
@@ -58,9 +141,12 @@ export const DOCS_CODE_MISMATCH_DETECTOR = {
             for (let i = 0; i < lines.length; i++) {
                 const line = lines[i];
                 for (const feature of FEATURE_CHECKS) {
+                    if (feature.featureId === "security-validation" && isAndroidScopedSecurityValidationClaim(line)) {
+                        continue;
+                    }
                     const currentMatch = currentClaimPatternFor(feature.subjectPattern).test(line);
                     const plannedMatch = plannedClaimPatternFor(feature.subjectPattern).test(line);
-                    const implemented = feature.isImplemented(ctx.sourceOfTruth);
+                    const implemented = feature.isImplemented(featureCtx);
                     if (currentMatch && plannedMatch) {
                         // Same line claims both current and planned for the same
                         // subject -- genuinely ambiguous, reported as low-confidence
@@ -78,11 +164,120 @@ export const DOCS_CODE_MISMATCH_DETECTOR = {
                 if (FULL_RELEASE_GATE_FOR_SCOPED_CHECKS_PATTERN.test(line) && !isNegatedNearby(line)) {
                     issues.push(makeFullReleaseGateIssue(docFile.relativePath, i + 1, line));
                 }
+                if (!JVM_FUTURE_OR_NEGATIVE_HEDGE_PATTERN.test(line)) {
+                    issues.push(...findJvmSymbolClaimMismatches(docFile.relativePath, i + 1, line, jvmMetadata, knownJvmDeclarationNames));
+                    issues.push(...findJvmBuildCommandClaimMismatches(docFile.relativePath, i + 1, line, jvmMetadata));
+                }
             }
         }
         return deduplicateIssuesById(issues);
     },
 };
+// v0.3.3 Batch 3 -- T1/T2/T3/T4. Gated on the project having ANY real
+// Java/Kotlin source at all (jvmMetadata.hasJavaSource/hasKotlinSource) --
+// without this gate, a project with no JVM code whatsoever (e.g. this repo
+// itself) would have every backtick-quoted FQCN-shaped mention trivially
+// "fail" to match anything, which would be pure noise rather than a real
+// signal. Matches by simple declaration name only (see
+// collectKnownJvmDeclarationNames()'s header comment) -- this cannot verify
+// the claimed package prefix actually matches, only that some declaration
+// with that name exists somewhere in the scanned Java/Kotlin source, which
+// is why this is always a "weak signal" candidate, never a proof.
+function findJvmSymbolClaimMismatches(relativePath, lineNumber, line, jvmMetadata, knownJvmDeclarationNames) {
+    if (!jvmMetadata.hasJavaSource && !jvmMetadata.hasKotlinSource)
+        return [];
+    const issues = [];
+    BACKTICK_SPAN_PATTERN.lastIndex = 0;
+    for (const match of line.matchAll(BACKTICK_SPAN_PATTERN)) {
+        const candidate = match[1];
+        if (!JVM_FQCN_PATTERN.test(candidate))
+            continue;
+        const simpleName = candidate.slice(candidate.lastIndexOf(".") + 1);
+        if (knownJvmDeclarationNames.has(simpleName))
+            continue;
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: [relativePath, "jvm-symbol-claim-mismatch", String(lineNumber), candidate],
+            title: `Docs mention a Java/Kotlin symbol not found in static source facts: "${candidate}"`,
+            description: `${relativePath}:${lineNumber} mentions \`${candidate}\`, but no scanned Java/Kotlin declaration named "${simpleName}" was found. This is a static source-facts signal from a conservative, name-only scan -- it cannot verify the claimed package prefix, only that no declaration with this simple name exists anywhere in the scanned Java/Kotlin file set, so this is a candidate docs-code mismatch (weak signal), not proof.`,
+            severity: "info",
+            confidence: "low",
+            falsePositiveRisk: "high",
+            category: "docs-feature-mismatch",
+            recommendedAction: `Confirm "${candidate}" exists (it may be defined outside the scanned source set) before treating this as stale documentation.`,
+            suggestedFixStrategy: `Update ${relativePath} to reference an existing Java/Kotlin symbol, or add the missing declaration.`,
+            validationCommands: ["npm run audit -- --types code-rot --include docs"],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence: [
+                {
+                    kind: "file",
+                    message: `Static source-facts check did not find a Java/Kotlin declaration named "${simpleName}" in the scanned file set.`,
+                    filePath: relativePath,
+                    line: lineNumber,
+                    excerpt: line.trim().slice(0, 200),
+                    source: DETECTOR_ID,
+                    confidence: "low",
+                },
+            ],
+            affectedFiles: [relativePath],
+        }));
+    }
+    return issues;
+}
+// v0.3.3 Batch 3 -- T6/T7/T8/T9. Only matches a Gradle/Maven command token
+// inside a backtick-quoted inline code span, for the same "conventionally
+// how a real command example is written" reasoning as the symbol check
+// above. This never claims the command would actually succeed -- only that
+// docs present a command example implying a build tool this project's
+// static metadata does not show any trace of.
+function findJvmBuildCommandClaimMismatches(relativePath, lineNumber, line, jvmMetadata) {
+    const issues = [];
+    BACKTICK_SPAN_PATTERN.lastIndex = 0;
+    for (const match of line.matchAll(BACKTICK_SPAN_PATTERN)) {
+        const candidate = match[1];
+        if (GRADLE_COMMAND_PATTERN.test(candidate) && !jvmMetadata.hasGradleBuild && !jvmMetadata.hasGradleSettings && !jvmMetadata.hasGradleWrapper) {
+            issues.push(makeBuildCommandIssue(relativePath, lineNumber, line, candidate, "Gradle", "no Gradle execution was performed"));
+        }
+        if (MAVEN_COMMAND_PATTERN.test(candidate) && !jvmMetadata.hasMavenPom) {
+            issues.push(makeBuildCommandIssue(relativePath, lineNumber, line, candidate, "Maven", "no Maven execution was performed"));
+        }
+    }
+    return issues;
+}
+function makeBuildCommandIssue(relativePath, lineNumber, line, commandExcerpt, toolLabel, executionNote) {
+    return makeCodeRotIssue({
+        auditType: "code-rot",
+        detectorId: DETECTOR_ID,
+        idCues: [relativePath, `${toolLabel.toLowerCase()}-command-claim-mismatch`, String(lineNumber), commandExcerpt],
+        title: `Docs include a ${toolLabel} command example, but no ${toolLabel} metadata was found: "${commandExcerpt}"`,
+        description: `${relativePath}:${lineNumber} shows the command \`${commandExcerpt}\`, but no ${toolLabel} build/config metadata was found in the project (see jvmProjectMetadata.ts's static presence checks). This is a candidate docs-code mismatch (weak signal), not proof -- ${executionNote}, so this scan cannot confirm the command would actually run.`,
+        severity: "info",
+        confidence: "low",
+        falsePositiveRisk: "high",
+        category: "docs-feature-mismatch",
+        recommendedAction: `Confirm ${toolLabel} metadata exists (it may live outside the scanned inventory) before treating this as stale documentation.`,
+        suggestedFixStrategy: `Update ${relativePath} to remove or correct the ${toolLabel} command example, or add the corresponding ${toolLabel} project files.`,
+        validationCommands: ["npm run audit -- --types code-rot --include docs"],
+        releaseBlocking: false,
+        implementationBlocking: false,
+        autoFixEligible: false,
+        evidence: [
+            {
+                kind: "file",
+                message: `Static source-facts/metadata check did not find ${toolLabel} build metadata; ${executionNote}.`,
+                filePath: relativePath,
+                line: lineNumber,
+                excerpt: line.trim().slice(0, 200),
+                source: DETECTOR_ID,
+                confidence: "low",
+            },
+        ],
+        affectedFiles: [relativePath],
+    });
+}
 function makeCurrentButMissingIssue(relativePath, lineNumber, excerpt, feature) {
     return makeCodeRotIssue({
         auditType: "code-rot",
@@ -217,3 +412,6 @@ function readBoundedText(root, relativePath, sizeBytes) {
         return null;
     }
 }
+function isAndroidScopedSecurityValidationClaim(line) {
+    return /\bAndroid\b[^.\n]{0,60}\bsecurity validation\b/i.test(line) || /\bsecurity validation\b[^.\n]{0,30}\bfor Android\b/i.test(line);
+}

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

@@ -1,7 +1,8 @@
 import { readBoundedFileText } from "../utils/boundedRead.js";
-import { firstPathSegment, GENERIC_DECLARATION_NAMES, 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";
+import { isJvmCommonLowSignalDeclarationName } from "../utils/jvmSourceFactsUtils.js";
 // ---------------------------------------------------------------------------
 // v0.3.0 Batch 4 — duplicate/parallel implementation candidate detector.
 //
@@ -225,12 +226,12 @@ function firstTopLevelUnderSrc(relativePath) {
 // (function/class/interface/type/enum) -- "variable"/"constant"/"method"/
 // "unknown" are excluded as too noisy (methods repeat across unrelated
 // classes by convention; module-scope variables/constants repeat even more
-// often). Generic declaration names (run, init, handler, ...) are excluded
-// via GENERIC_DECLARATION_NAMES for the same reason
-// GENERIC_INFRA_BASENAMES excludes generic file basenames above. Requires
-// ctx.sourceFacts -- returns no issues when it is absent (e.g. existing
-// detector unit tests that build a literal AuditDetectorContext without
-// it), so this check is purely additive.
+// 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)
@@ -248,9 +249,41 @@ function findDuplicateDeclarationCandidates(ctx) {
             if (NOISY_DECLARATION_KINDS.has(decl.kind))
                 continue;
             const nameLower = decl.name.toLowerCase();
-            if (GENERIC_DECLARATION_NAMES.has(nameLower))
+            if (isGenericOrTestPrefixedDeclarationName(nameLower))
                 continue;
-            const key = `${decl.kind}:${nameLower}`;
+            // v0.3.3 Batch 2 -- Java/Kotlin-specific common/low-signal name
+            // suppression (Main, App, Config, Service, Controller, test*, ...).
+            // Gated to java/kotlin so existing TS/JS/Python behavior is
+            // unaffected -- a TS/JS file exporting `class Service {}` (a very
+            // ordinary, non-generic name in that ecosystem) must keep being
+            // considered, unlike the JVM ecosystem where these names are
+            // conventionally near-meaningless boilerplate labels.
+            if ((facts.language === "java" || facts.language === "kotlin") && isJvmCommonLowSignalDeclarationName(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. v0.3.3 Batch 2 -- this same scoping is
+            // why Java ("java-analyzer") and Kotlin ("kotlin-analyzer") never
+            // group with each other, TS/JS, or Python: they are two distinct
+            // analyzers with two distinct ids, deliberately not unified into one
+            // "JVM" scope in this batch (a same-named Java class and Kotlin
+            // class are not the same declaration in the same language, and
+            // conflating them risks a false "duplicate" signal across languages
+            // that don't even share syntax).
+            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);

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

@@ -1,9 +1,13 @@
 import fs from "node:fs";
 import path from "node:path";
+import { collectPythonProjectMetadata } from "../../core/pythonProjectMetadata.js";
+import { collectJvmProjectMetadata } from "../../core/jvmProjectMetadata.js";
 import { readBoundedFileText } from "../utils/boundedRead.js";
+import { baseNameNoExt } from "../utils/filePatternUtils.js";
 import { deduplicateIssuesById, makeCodeRotIssue } from "../utils/issueFactories.js";
 import { getParsedSourceFacts, indexSourceFactsByPath } from "../utils/sourceFactsLookup.js";
 import { splitLines } from "../utils/textLines.js";
+import { jvmImportCandidatePaths, jvmImportLooksPossiblyLocal, jvmImportSimpleName, } from "../utils/jvmSourceFactsUtils.js";
 // ---------------------------------------------------------------------------
 // v0.3.0 Batch 4 — test-rot detector.
 //
@@ -44,6 +48,15 @@ export const TEST_ROT_DETECTOR = {
         const scriptNames = new Set(ctx.sourceOfTruth.commands.allScriptNames);
         const currentVersion = ctx.sourceOfTruth.package?.version ?? null;
         const sourceFactsIndex = indexSourceFactsByPath(ctx.sourceFacts);
+        // v0.3.2 Batch 2 -- computed once per run, not per test file. Presence-
+        // only/simple-text-extraction (see pythonProjectMetadata.ts); used below
+        // purely as weak supporting context on Python findings, never as a
+        // required condition -- its absence must not change whether a finding
+        // is emitted, only add or omit one extra evidence line.
+        const pythonMetadata = collectPythonProjectMetadata(ctx.target.rootPath, ctx.inventory);
+        // v0.3.3 Batch 2 -- same "computed once, weak supporting context only"
+        // treatment as pythonMetadata above.
+        const jvmMetadata = collectJvmProjectMetadata(ctx.target.rootPath, ctx.inventory);
         for (const testFile of ctx.inventory.testFiles) {
             const content = readBoundedFileText(ctx.target.rootPath, testFile.relativePath, testFile.sizeBytes, MAX_READ_BYTES);
             if (content === null)
@@ -71,7 +84,25 @@ export const TEST_ROT_DETECTOR = {
             // (testRelativePath, "missing-source-import", specifier), so an
             // identical id is deduplicated by deduplicateIssuesById() below.
             const parsedFacts = getParsedSourceFacts(sourceFactsIndex, testFile.relativePath);
-            if (parsedFacts) {
+            if (parsedFacts?.language === "python") {
+                // v0.3.2 Batch 2 -- Python relative imports use dotted-module
+                // notation (".module", "..pkg.module"), not TS/JS's path-like
+                // "./module" syntax. Routing Python facts through the TS/JS
+                // resolver below would misresolve every relative Python import and
+                // flag it as missing regardless of whether it actually exists --
+                // this guard is the fix for that latent cross-language bug.
+                issues.push(...findMissingPythonSourceImports(ctx, testFile.relativePath, parsedFacts, pythonMetadata));
+            }
+            else if (parsedFacts?.language === "java" || parsedFacts?.language === "kotlin") {
+                // v0.3.3 Batch 2 -- Java/Kotlin imports are fully-qualified dotted
+                // package names ("com.example.Foo"), neither TS/JS's path-like
+                // "./module" syntax nor Python's dotted-relative-import syntax.
+                // Routing them through either existing resolver would misresolve
+                // every import -- this guard is the JVM analogue of the Python
+                // guard immediately above.
+                issues.push(...findMissingJvmSourceImports(ctx, testFile.relativePath, parsedFacts, jvmMetadata));
+            }
+            else if (parsedFacts) {
                 issues.push(...findMissingSourceImportsFromSourceFacts(ctx, testFile.relativePath, parsedFacts));
             }
             issues.push(...findStaleNpmRunReferences(testFile.relativePath, content, scriptNames));
@@ -177,6 +208,215 @@ function findMissingSourceImportsFromSourceFacts(ctx, testRelativePath, facts) {
     }
     return issues;
 }
+// v0.3.2 Batch 2 -- resolves a Python relative-import source (".module",
+// "..pkg.sub", or bare "."/".." paired with `from . import name`-style
+// imported names) to candidate local file paths, using Python's own
+// relative-import level semantics (one leading dot = the importing file's
+// own directory, each additional dot = one directory further up). This is a
+// conservative, path-based approximation -- it does not resolve namespace
+// packages, `sys.path` manipulation, editable installs, or anything beyond
+// simple on-disk file/package presence, so returning zero matches is a
+// candidate "may indicate a missing module" signal, not proof.
+function resolvePythonRelativeImportCandidatePaths(testDir, importSource, importedNames) {
+    if (!importSource.startsWith("."))
+        return [];
+    let dotCount = 0;
+    while (dotCount < importSource.length && importSource[dotCount] === ".")
+        dotCount += 1;
+    const remainder = importSource.slice(dotCount);
+    const upLevels = dotCount - 1;
+    let baseDir = testDir;
+    for (let i = 0; i < upLevels; i++)
+        baseDir = path.dirname(baseDir);
+    const candidates = [];
+    const pushCandidatesFor = (moduleSegment) => {
+        candidates.push(path.join(baseDir, `${moduleSegment}.py`).replace(/\\/g, "/"));
+        candidates.push(path.join(baseDir, moduleSegment, "__init__.py").replace(/\\/g, "/"));
+    };
+    if (remainder) {
+        pushCandidatesFor(remainder.split(".").join("/"));
+    }
+    else {
+        // Bare "." / ".." (e.g. `from . import sibling`) -- the module lives
+        // in `importedNames`, not in `importSource` itself.
+        for (const name of importedNames ?? [])
+            pushCandidatesFor(name);
+    }
+    return candidates;
+}
+// v0.3.2 Batch 2 -- Python-specific counterpart to
+// findMissingSourceImportsFromSourceFacts() above. Only ever called for
+// facts with `language === "python"` (see caller) -- the two functions are
+// kept fully separate rather than parameterized by language, because their
+// resolution algorithms are genuinely different (dotted-module relative-
+// import-level semantics vs. path-like specifier semantics), and conflating
+// them risked silently misresolving one language or the other. Deliberately
+// lower severity/confidence than the TS/JS counterpart: this scan has no
+// real package/sys.path awareness, so it is weaker evidence than the
+// TS/JS analyzer's near-exact relative-path resolution.
+function findMissingPythonSourceImports(ctx, testRelativePath, facts, pythonMetadata) {
+    const issues = [];
+    const testDir = path.dirname(testRelativePath);
+    for (const imp of facts.imports) {
+        if (!imp.source.startsWith("."))
+            continue; // conservative: only relative Python imports are checked
+        const candidates = resolvePythonRelativeImportCandidatePaths(testDir, imp.source, imp.importedNames);
+        if (candidates.length === 0)
+            continue; // nothing checkable (e.g. bare "." with no imported names)
+        const resolved = candidates.some((candidate) => fs.existsSync(path.join(ctx.target.rootPath, candidate)));
+        if (resolved)
+            continue;
+        const evidence = [
+            {
+                kind: "file",
+                message: "Analyzer-recorded relative Python import does not resolve to a candidate local module/package file. This is a best-effort, path-based check -- it does not resolve Python's real package/sys.path rules, so confirm manually before treating it as stale.",
+                filePath: testRelativePath,
+                excerpt: imp.source,
+                source: DETECTOR_ID,
+                confidence: "low",
+            },
+        ];
+        if (pythonMetadata.hasPytestConfiguration) {
+            evidence.push({
+                kind: "observation",
+                message: "Weak supporting context: this project has a detected pytest configuration (pytest.ini, or a pyproject.toml/setup.cfg pytest section), consistent with pytest-style test conventions -- not a requirement for this finding.",
+                source: DETECTOR_ID,
+                confidence: "low",
+            });
+        }
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: [testRelativePath, "missing-python-source-import", imp.source],
+            title: `Test "${testRelativePath}" imports a Python module that may not exist: "${imp.source}"`,
+            description: `${testRelativePath} imports "${imp.source}" (source-facts-derived via the Python analyzer). No candidate local module or package file was found relative to the test file. This is a deterministic source-facts signal from a conservative, non-semantic scan -- it does not resolve Python's real package/sys.path rules, namespace packages, or editable installs, so this may indicate a stale import but is not proof.`,
+            severity: "low",
+            confidence: "low",
+            falsePositiveRisk: "medium",
+            category: "test-rot",
+            recommendedAction: "Confirm the imported Python module exists (it may resolve via a path this scan cannot see) before treating this as stale.",
+            suggestedFixStrategy: `Update or remove the import "${imp.source}" in ${testRelativePath} if confirmed stale.`,
+            validationCommands: [`npx vitest run ${testRelativePath}`],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence,
+            affectedFiles: [testRelativePath],
+        }));
+    }
+    return issues;
+}
+// v0.3.3 Batch 2 -- Java/Kotlin-specific counterpart to
+// findMissingSourceImportsFromSourceFacts()/findMissingPythonSourceImports()
+// above. Only ever called for facts with `language === "java"` or
+// `"kotlin"` (see caller) -- kept fully separate from both existing
+// resolvers for the same reason the Python resolver is kept separate from
+// the TS/JS one: the resolution algorithm (fully-qualified dotted package
+// names -> conventional Gradle/Maven source-set paths) is genuinely
+// different from either.
+//
+// Deliberately lower severity/confidence than the TS/JS counterpart, same
+// tier as the Python counterpart: this scan has no real classpath/build
+// awareness (no Gradle/Maven execution, no compiler), so it is weaker
+// evidence than the TS/JS analyzer's near-exact relative-path resolution.
+// Standard-library, common third-party test-framework, and wildcard
+// imports are skipped entirely via jvmImportLooksPossiblyLocal() -- see
+// jvmSourceFactsUtils.ts for the full skip-prefix list and rationale.
+function findMissingJvmSourceImports(ctx, testRelativePath, facts, jvmMetadata) {
+    const issues = [];
+    const isKotlin = facts.language === "kotlin";
+    const languageLabel = isKotlin ? "Kotlin" : "Java";
+    // Kotlin may legitimately import Java source in a mixed JVM project;
+    // Java never imports Kotlin-only source through a plain `import`
+    // statement in the way this conservative scan can see, so a Java test
+    // only ever checks .java candidates.
+    const extensions = isKotlin ? ["kt", "java"] : ["java"];
+    // Both recognized main and test source-set directories are checked --
+    // the latter specifically covers the "importing a test-scoped helper
+    // from another test-set file" case (the importing file here is, by
+    // definition, already test-scoped, since this function is only ever
+    // called from the per-test-file loop above).
+    const candidateDirs = [...jvmMetadata.recognizedSourceDirectories, ...jvmMetadata.recognizedTestDirectories];
+    const inventoryBasenameIndex = buildJvmInventoryBasenameIndex(ctx, extensions);
+    for (const imp of facts.imports) {
+        if (!jvmImportLooksPossiblyLocal(imp))
+            continue;
+        // A Java `import static com.example.Foo.bar;` (or a Kotlin top-level
+        // member import) has its *member* name as the last dotted segment, not
+        // a class name -- this analyzer's ImportFact model (shared across
+        // every language) does not distinguish "static import of a member"
+        // from "plain class import", so both interpretations are tried: the
+        // full dotted path as-is (the common, plain-class-import case), and
+        // with its last segment dropped (the static/member-import case). This
+        // is a detector-side fix, not a change to javaAnalyzer.ts/
+        // kotlinAnalyzer.ts's ImportFact shape.
+        const parentSource = imp.source.includes(".") ? imp.source.slice(0, imp.source.lastIndexOf(".")) : null;
+        const conventionalCandidates = [
+            ...jvmImportCandidatePaths(imp.source, candidateDirs, extensions),
+            ...(parentSource ? jvmImportCandidatePaths(parentSource, candidateDirs, extensions) : []),
+        ];
+        const resolved = conventionalCandidates.some((candidate) => fs.existsSync(path.join(ctx.target.rootPath, candidate))) ||
+            inventoryBasenameIndex.has(jvmImportSimpleName(imp.source)) ||
+            (parentSource !== null && inventoryBasenameIndex.has(jvmImportSimpleName(parentSource)));
+        if (resolved)
+            continue;
+        const evidence = [
+            {
+                kind: "file",
+                message: `Analyzer-recorded ${languageLabel} import does not resolve to a candidate local source file under a recognized source-set directory, nor to any inventoried file with a matching basename. This is a best-effort, path-based check -- no compiler/classpath analysis was performed, and no Gradle/Maven execution was performed, so confirm manually before treating it as stale.`,
+                filePath: testRelativePath,
+                excerpt: imp.source,
+                source: DETECTOR_ID,
+                confidence: "low",
+            },
+        ];
+        if (candidateDirs.length > 0) {
+            evidence.push({
+                kind: "observation",
+                message: `Weak supporting context: recognized source-set directories for this project are: ${candidateDirs.join(", ")}.`,
+                source: DETECTOR_ID,
+                confidence: "low",
+            });
+        }
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: [testRelativePath, `missing-${facts.language}-source-import`, imp.source],
+            title: `Test "${testRelativePath}" imports a ${languageLabel} class that may not exist: "${imp.source}"`,
+            description: `${testRelativePath} imports "${imp.source}" (source-facts-derived via the ${languageLabel} analyzer). No candidate local source file was found under a recognized source-set directory, and no inventoried file shares its simple name. This is a deterministic source-facts signal from a conservative, non-semantic scan -- no compiler/classpath analysis was performed, and no Gradle/Maven execution was performed, so this does not resolve the real classpath, package visibility, or multi-module project layout. It may indicate a stale import but is not proof.`,
+            severity: "low",
+            confidence: "low",
+            falsePositiveRisk: "medium",
+            category: "test-rot",
+            recommendedAction: "Confirm the imported class exists (it may resolve via a module/classpath this scan cannot see) before treating this as stale.",
+            suggestedFixStrategy: `Update or remove the import "${imp.source}" in ${testRelativePath} if confirmed stale.`,
+            validationCommands: [`npx vitest run ${testRelativePath}`],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence,
+            affectedFiles: [testRelativePath],
+        }));
+    }
+    return issues;
+}
+// Lowercased-basename index (without extension) of every inventoried
+// Java/Kotlin file matching the given extensions -- the lenient,
+// last-resort fallback used by findMissingJvmSourceImports() above so a
+// real (if unconventionally placed) local file is never flagged as
+// missing merely because the project doesn't follow the conventional
+// src/main/{java,kotlin} source-set layout (mirrors
+// jvmProjectMetadata.ts's own "non-conventional layout" reasoning).
+function buildJvmInventoryBasenameIndex(ctx, extensions) {
+    const extSet = new Set(extensions.map((e) => `.${e}`));
+    const basenames = new Set();
+    for (const file of ctx.inventory.files) {
+        if (!extSet.has(file.extension))
+            continue;
+        basenames.add(baseNameNoExt(file.relativePath));
+    }
+    return basenames;
+}
 function findStaleNpmRunReferences(testRelativePath, content, scriptNames) {
     const issues = [];
     const seen = new Set();

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

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