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

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.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.
 
@@ -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, 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,16 +205,16 @@ See [docs/METRICS.md](docs/METRICS.md) for full metric definitions.
 
 ---
 
-## Current baseline release positioning
-
-my-dev-kit-lab is at a working baseline. The raw-vs-indexed experiment pipeline is fully implemented and produces reproducible artifacts. Real-agent campaign support exists for Codex and Claude. The 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.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
 
 ---
 
@@ -220,6 +222,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 +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. 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

@@ -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,6 +1,6 @@
 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";
 // ---------------------------------------------------------------------------
@@ -50,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);
     },
 };
@@ -250,6 +253,97 @@ 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;
+}
 function findOldOrDeprecatedFilesNotInDocs(ctx, docsConcat) {
     const issues = [];
     for (const file of ctx.inventory.files) {

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

@@ -1,5 +1,5 @@
 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";
 // ---------------------------------------------------------------------------
@@ -225,12 +225,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 +248,24 @@ 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.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);

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

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { collectPythonProjectMetadata } from "../../core/pythonProjectMetadata.js";
 import { readBoundedFileText } from "../utils/boundedRead.js";
 import { deduplicateIssuesById, makeCodeRotIssue } from "../utils/issueFactories.js";
 import { getParsedSourceFacts, indexSourceFactsByPath } from "../utils/sourceFactsLookup.js";
@@ -44,6 +45,12 @@ 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);
         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 +78,16 @@ 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) {
                 issues.push(...findMissingSourceImportsFromSourceFacts(ctx, testFile.relativePath, parsedFacts));
             }
             issues.push(...findStaleNpmRunReferences(testFile.relativePath, content, scriptNames));
@@ -177,6 +193,104 @@ 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;
+}
 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_");
+}

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

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { AUDIT_FAIL_ON_THRESHOLDS, AUDIT_INCLUDE_AREAS, AUDIT_OUTPUT_FORMATS, AUDIT_TYPES, DEFAULT_AUDIT_FAIL_ON_THRESHOLD, DEFAULT_AUDIT_INCLUDE_AREAS, DEFAULT_AUDIT_OUTPUT_FORMATS, DEFAULT_AUDIT_TYPES, PLANNED_AUDIT_TYPES, } from "./auditTypes.js";
+import { AUDIT_FAIL_ON_THRESHOLDS, AUDIT_INCLUDE_AREAS, AUDIT_OUTPUT_FORMATS, AUDIT_TYPES, DEFAULT_AUDIT_FAIL_ON_THRESHOLD, DEFAULT_AUDIT_INCLUDE_AREAS, DEFAULT_AUDIT_OUTPUT_FORMATS, DEFAULT_AUDIT_TYPES, IMPLEMENTED_AUDIT_TYPES, PLANNED_AUDIT_TYPES, } from "./auditTypes.js";
 const FLAGS_WITH_VALUE = {
     "--target": "target",
     "--types": "types",
@@ -67,7 +67,7 @@ function parseTypesOption(raw) {
     }
     const planned = parts.filter((p) => PLANNED_AUDIT_TYPES.includes(p));
     if (planned.length > 0) {
-        throw new Error(`--types value(s) planned but not implemented: ${planned.join(", ")}. Only "code-rot" is implemented in this version.`);
+        throw new Error(`--types value(s) planned but not implemented: ${planned.join(", ")}. Implemented audit types: ${IMPLEMENTED_AUDIT_TYPES.join(", ")}.`);
     }
     const unique = new Set(parts);
     const ordered = AUDIT_TYPES.filter((id) => unique.has(id));

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

@@ -4,6 +4,9 @@ import { resolveAuditTarget } from "./auditTarget.js";
 import { scanProjectInventory } from "./projectInventory.js";
 import { collectSourceOfTruth } from "./sourceOfTruth.js";
 import { collectSourceFacts } from "./collectSourceFacts.js";
+import { collectPythonProjectMetadata } from "./pythonProjectMetadata.js";
+import { runSecurityAuditAdapter } from "../security/securityAuditAdapter.js";
+import { SECURITY_AUDIT_NOT_RUN_SUMMARY } from "../security/securityAuditTypes.js";
 export async function runAudit(options) {
     const { config, toolRoot } = options;
     const registry = options.registry ?? DEFAULT_AUDIT_REGISTRY;
@@ -11,6 +14,7 @@ export async function runAudit(options) {
     const inventory = scanProjectInventory(target.rootPath);
     const sourceOfTruth = collectSourceOfTruth(target.rootPath, inventory);
     const sourceFacts = await collectSourceFacts(target.rootPath, inventory);
+    const pythonProjectMetadata = collectPythonProjectMetadata(target.rootPath, inventory);
     const selected = selectDetectors(registry, config.types, config.include);
     const ctx = { target, config, inventory, sourceOfTruth, sourceFacts };
     const issues = [];
@@ -37,6 +41,19 @@ export async function runAudit(options) {
             });
         }
     }
+    // v0.3.2 Batch 4 -- security audit adapter. Conditional (see the
+    // AuditResult.securitySummary field comment above): only runs when --types
+    // explicitly includes "security", never as part of a default/code-rot-only
+    // run. Appended after the code-rot detector loop above, so combined
+    // `--types code-rot,security` runs keep a deterministic issue order:
+    // code-rot detector issues (registry order) first, then security findings
+    // (security-validation check-execution order).
+    let securitySummary = SECURITY_AUDIT_NOT_RUN_SUMMARY;
+    if (config.types.includes("security")) {
+        const securityAudit = await runSecurityAuditAdapter({ toolRoot, config });
+        issues.push(...securityAudit.issues);
+        securitySummary = securityAudit.summary;
+    }
     const issueCounts = countIssuesBySeverity(issues);
     const { exitCode, reason } = calculateAuditExitCode(issues, config.failOn);
     return {
@@ -62,6 +79,8 @@ export async function runAudit(options) {
         inventory,
         sourceOfTruth,
         sourceFacts,
+        pythonProjectMetadata,
+        securitySummary,
         noDetectorsRegistered: selected.length === 0,
     };
 }

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

@@ -7,14 +7,21 @@
 // this batch keeps the audit issue schema independent even where a
 // vocabulary word (e.g. "blocker") happens to be shared.
 // ---------------------------------------------------------------------------
-// Recognized --types values. Only "code-rot" has real detector coverage in
-// Batch 1 — the rest are known, named future audit types that must fail
-// cleanly with a "planned but not implemented" message rather than being
-// silently accepted or treated as an unknown/garbage value.
+// Recognized --types values. "code-rot" (Batch 1) and "security" (v0.3.2
+// Batch 4, via the security-validation audit adapter) have real coverage —
+// the rest are known, named future audit types that must fail cleanly with a
+// "planned but not implemented" message rather than being silently accepted
+// or treated as an unknown/garbage value.
 export const AUDIT_TYPES = ["code-rot", "quality", "security", "project", "all"];
-export const IMPLEMENTED_AUDIT_TYPES = ["code-rot"];
-export const PLANNED_AUDIT_TYPES = ["quality", "security", "project", "all"];
-export const DEFAULT_AUDIT_TYPES = IMPLEMENTED_AUDIT_TYPES;
+export const IMPLEMENTED_AUDIT_TYPES = ["code-rot", "security"];
+export const PLANNED_AUDIT_TYPES = ["quality", "project", "all"];
+// v0.3.2 Batch 4 — deliberately NOT derived from IMPLEMENTED_AUDIT_TYPES.
+// "security" becomes selectable via --types security (and --types
+// code-rot,security) but must never join the *default* (no --types flag)
+// audit run, since it shells out to npm audit/CodeQL/Semgrep/fuzz and is far
+// more expensive than the always-on code-rot detectors — a default,
+// unqualified `npm run audit` must keep its existing code-rot-only behavior.
+export const DEFAULT_AUDIT_TYPES = ["code-rot"];
 export const AUDIT_INCLUDE_AREAS = ["docs", "tests", "package", "architecture", "cli"];
 export const DEFAULT_AUDIT_INCLUDE_AREAS = AUDIT_INCLUDE_AREAS;
 export const AUDIT_OUTPUT_FORMATS = ["text", "json"];

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

@@ -1,4 +1,5 @@
 import { TYPESCRIPT_JAVASCRIPT_ANALYZER } from "./typescriptJavaScriptAnalyzer.js";
+import { PYTHON_ANALYZER } from "./pythonAnalyzer.js";
 // Validates a list has no duplicate analyzer ids. Later batches call this
 // when assembling their own registries; Batch 2's empty default trivially
 // passes.
@@ -25,9 +26,11 @@ export function selectLanguageAnalyzer(registry, language, extension) {
     }
     return null;
 }
-// v0.3.1 Batch 3 -- registers the TypeScript/JavaScript analyzer. Python,
-// Java, and Kotlin remain fallback-only (no analyzer registered for them) --
-// see collectSourceFacts.ts's fallback policy.
+// v0.3.1 Batch 3 -- registers the TypeScript/JavaScript analyzer. v0.3.2
+// Batch 1 adds the Python analyzer alongside it. Java and Kotlin remain
+// fallback-only (no analyzer registered for them) -- see
+// collectSourceFacts.ts's fallback policy.
 export const DEFAULT_LANGUAGE_ANALYZER_REGISTRY = createLanguageAnalyzerRegistry([
     TYPESCRIPT_JAVASCRIPT_ANALYZER,
+    PYTHON_ANALYZER,
 ]);