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

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

@@ -0,0 +1,344 @@
+import path from "node:path";
+import { readBoundedFileText } from "../utils/boundedRead.js";
+import { baseNameNoExt } from "../utils/filePatternUtils.js";
+import { deduplicateIssuesById, makeCodeRotIssue } from "../utils/issueFactories.js";
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 4 — dead-code candidate detector.
+//
+// Every finding here is a candidate, not proof of dead code -- title wording
+// stays hedged throughout. Bounded (per-file MAX_READ_BYTES skip), no
+// subprocess, no exports/type-usage analysis (see SKIPPED note below).
+//
+// Explicitly SKIPPED (spec-documented, not implemented in this batch):
+//   - "exported symbols unused" -- there is no existing safe/cheap way in
+//     this repo to determine which exported symbols are referenced
+//     elsewhere without a real TypeScript program (ts-morph/checker), which
+//     is out of scope for a bounded regex-based detector. Not implemented.
+// ---------------------------------------------------------------------------
+const DETECTOR_ID = "dead-code-candidate";
+const MAX_READ_BYTES = 200_000;
+const OLD_DIR_SEGMENT_PATTERN = /^(old|deprecated|legacy|_archive)$/i;
+const ORPHAN_GENERATED_PATTERN = /\.generated\.|\.bak$|\.orig$/;
+const IMPORT_SPECIFIER_PATTERN = /(?:from|require\()\s*["']([^"']+)["']/g;
+const PLANNED_LABEL_PATTERN = /\b(planned|future|roadmap|not implemented|not yet implemented|coming soon)\b/i;
+const SETUP_FILE_PATTERN = /setup[tT]ests?|vitest\.setup|test-setup/i;
+export const DEAD_CODE_CANDIDATE_DETECTOR = {
+    id: DETECTOR_ID,
+    auditType: "code-rot",
+    title: "Dead-code candidate",
+    description: "Detects candidate (not proven) unused files: scripts/ files not referenced by any package.json script, source files with no in-repo importer, files under old/deprecated/legacy directories not mentioned in docs, and orphaned generated-looking files.",
+    supportedIncludeAreas: ["cli", "package", "tests"],
+    shouldSkip: (ctx) => {
+        if (!ctx.config.include.includes("package") && !ctx.config.include.includes("tests")) {
+            return { skip: true, reason: "--include selects neither package nor tests; this detector's checks need at least one." };
+        }
+        return { skip: false };
+    },
+    run: (ctx) => {
+        const issues = [];
+        const pkg = ctx.sourceOfTruth.package;
+        const docsConcat = concatDocsContent(ctx);
+        if (ctx.config.include.includes("package") && pkg) {
+            issues.push(...findUnreferencedScriptFiles(ctx, pkg));
+        }
+        if (ctx.config.include.includes("cli") || ctx.config.include.includes("architecture")) {
+            issues.push(...findUnreferencedSourceFiles(ctx, pkg, docsConcat));
+        }
+        issues.push(...findOldOrDeprecatedFilesNotInDocs(ctx, docsConcat));
+        issues.push(...findOrphanedGeneratedFiles(ctx.inventory.files));
+        if (ctx.config.include.includes("tests")) {
+            issues.push(...findUnreferencedFixtures(ctx));
+        }
+        return deduplicateIssuesById(issues);
+    },
+};
+function concatDocsContent(ctx) {
+    const parts = [];
+    for (const docFile of ctx.inventory.docsFiles) {
+        const content = readBoundedFileText(ctx.target.rootPath, docFile.relativePath, docFile.sizeBytes, MAX_READ_BYTES);
+        if (content !== null)
+            parts.push(content);
+    }
+    return parts.join("\n");
+}
+function docsDescribeAsPlanned(docsConcat, relativePath) {
+    const base = baseNameNoExt(relativePath);
+    const idx = docsConcat.indexOf(base);
+    if (idx === -1)
+        return false;
+    const windowStart = Math.max(0, idx - 100);
+    const windowEnd = Math.min(docsConcat.length, idx + base.length + 100);
+    return PLANNED_LABEL_PATTERN.test(docsConcat.slice(windowStart, windowEnd));
+}
+function binTargetsAsSourceCandidates(pkg) {
+    const raw = pkg.bin === null ? [] : typeof pkg.bin === "string" ? [pkg.bin] : Object.values(pkg.bin);
+    const candidates = new Set();
+    for (const target of raw) {
+        candidates.add(target);
+        if (target.startsWith("dist/") && target.endsWith(".js")) {
+            candidates.add(`${target.slice("dist/".length, -".js".length)}.ts`);
+        }
+    }
+    if (pkg.main)
+        candidates.add(pkg.main);
+    if (pkg.module)
+        candidates.add(pkg.module);
+    if (pkg.types)
+        candidates.add(pkg.types);
+    return candidates;
+}
+function findUnreferencedScriptFiles(ctx, pkg) {
+    const scriptCommandsBlob = Object.values(pkg.scripts).join(" \n ");
+    const binCandidates = binTargetsAsSourceCandidates(pkg);
+    // A scripts/ file that is imported by another script (a shared helper
+    // module rather than a CLI entrypoint, e.g.
+    // scripts/security/resolveToolRoot.ts) is not dead code even though no
+    // package.json script command names it directly -- discovered via a real
+    // false positive during self-testing.
+    const referencedBasenames = buildReverseReferenceIndex(ctx);
+    const issues = [];
+    for (const file of ctx.inventory.scriptFiles) {
+        const base = baseNameNoExt(file.relativePath);
+        if (base.toLowerCase() === "index")
+            continue;
+        if (SETUP_FILE_PATTERN.test(path.basename(file.relativePath)))
+            continue;
+        if (binCandidates.has(file.relativePath))
+            continue;
+        if (scriptCommandsBlob.includes(file.relativePath) || scriptCommandsBlob.includes(base))
+            continue;
+        if (referencedBasenames.has(base.toLowerCase()))
+            continue;
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: ["unreferenced-script-file", file.relativePath],
+            title: `Script file "${file.relativePath}" is not referenced by any package.json script`,
+            description: `"${file.relativePath}" exists under scripts/ but no package.json script command mentions its path or basename. This is a candidate for dead code -- confirm it isn't invoked another way (e.g. imported by another script) before removing.`,
+            severity: "medium",
+            confidence: "medium",
+            falsePositiveRisk: "medium",
+            category: "dead-code-candidate",
+            recommendedAction: "Confirm the file is unused, then either add a script entry or remove the file.",
+            suggestedFixStrategy: `Remove "${file.relativePath}" or wire it up to a package.json script.`,
+            validationCommands: ["npm run audit -- --types code-rot --include package"],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence: [
+                {
+                    kind: "reference",
+                    message: "No package.json script command references this file's path or basename.",
+                    filePath: file.relativePath,
+                    source: DETECTOR_ID,
+                    confidence: "medium",
+                },
+            ],
+            affectedFiles: [file.relativePath],
+        }));
+    }
+    return issues;
+}
+function buildReverseReferenceIndex(ctx) {
+    const referencedBasenames = new Set();
+    const allCandidateFiles = [
+        ...ctx.inventory.sourceFiles,
+        ...ctx.inventory.testFiles,
+        ...ctx.inventory.scriptFiles,
+    ];
+    for (const file of allCandidateFiles) {
+        const content = readBoundedFileText(ctx.target.rootPath, file.relativePath, file.sizeBytes, MAX_READ_BYTES);
+        if (content === null)
+            continue;
+        IMPORT_SPECIFIER_PATTERN.lastIndex = 0;
+        for (const match of content.matchAll(IMPORT_SPECIFIER_PATTERN)) {
+            const specifier = match[1];
+            if (!specifier.startsWith("."))
+                continue; // only relative/local specifiers are meaningful here
+            const specifierBase = baseNameNoExt(specifier.split("?")[0]);
+            referencedBasenames.add(specifierBase.toLowerCase());
+        }
+    }
+    return referencedBasenames;
+}
+function findUnreferencedSourceFiles(ctx, pkg, docsConcat) {
+    const referencedBasenames = buildReverseReferenceIndex(ctx);
+    const binCandidates = pkg ? binTargetsAsSourceCandidates(pkg) : new Set();
+    const issues = [];
+    for (const file of ctx.inventory.sourceFiles) {
+        if (file.sizeBytes > MAX_READ_BYTES)
+            continue;
+        // benchmarks/ and examples/ hold standalone fixture/example project
+        // content (often in other languages, e.g. Python) that is meant to be
+        // read by the tool under test, not imported by this project's own
+        // TS/JS import graph -- scanning them against a TS/JS import-specifier
+        // reverse-reference index produces false positives, confirmed via
+        // self-testing.
+        if (file.relativePath.startsWith("benchmarks/") || file.relativePath.startsWith("examples/"))
+            continue;
+        const base = baseNameNoExt(file.relativePath);
+        if (base.toLowerCase() === "index")
+            continue;
+        if (SETUP_FILE_PATTERN.test(path.basename(file.relativePath)))
+            continue;
+        if (binCandidates.has(file.relativePath))
+            continue;
+        if (docsDescribeAsPlanned(docsConcat, file.relativePath))
+            continue;
+        if (referencedBasenames.has(base.toLowerCase()))
+            continue;
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: ["unreferenced-source-file", file.relativePath],
+            title: `Source file "${file.relativePath}" has no detected in-repo importer`,
+            description: `No other source or test file's relative import/require specifier appears to reference "${file.relativePath}" by basename. This is a bounded regex-based candidate signal, not a type-level unused-file proof -- confirm manually (dynamic imports, re-exports, or CLI-only usage can evade this scan).`,
+            severity: "low",
+            confidence: "low",
+            falsePositiveRisk: "medium",
+            category: "dead-code-candidate",
+            recommendedAction: "Confirm the file is genuinely unused before removing it.",
+            suggestedFixStrategy: `Remove "${file.relativePath}" if confirmed unused, or wire it into an existing import graph.`,
+            validationCommands: ["npm run audit -- --types code-rot --include cli"],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence: [
+                {
+                    kind: "observation",
+                    message: "No relative import/require specifier in the scanned source/test/script set resolves to this file's basename.",
+                    filePath: file.relativePath,
+                    source: DETECTOR_ID,
+                    confidence: "low",
+                },
+            ],
+            affectedFiles: [file.relativePath],
+        }));
+    }
+    return issues;
+}
+function findOldOrDeprecatedFilesNotInDocs(ctx, docsConcat) {
+    const issues = [];
+    for (const file of ctx.inventory.files) {
+        const segments = file.relativePath.split("/");
+        const hasOldSegment = segments.slice(0, -1).some((seg) => OLD_DIR_SEGMENT_PATTERN.test(seg));
+        if (!hasOldSegment)
+            continue;
+        if (docsConcat.includes(file.relativePath) || docsConcat.includes(path.basename(file.relativePath)))
+            continue;
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: ["old-deprecated-file-not-in-docs", file.relativePath],
+            title: `File under an old/deprecated/legacy directory is not mentioned in docs: "${file.relativePath}"`,
+            description: `"${file.relativePath}" sits under a directory named old/deprecated/legacy/_archive, and no doc file mentions its path or basename. This is a candidate for dead code.`,
+            severity: "medium",
+            confidence: "medium",
+            falsePositiveRisk: "low",
+            category: "dead-code-candidate",
+            recommendedAction: "Confirm the file is genuinely obsolete, then remove it or document why it is retained.",
+            suggestedFixStrategy: `Remove "${file.relativePath}" or add a doc note explaining why it is kept.`,
+            validationCommands: ["npm run audit -- --types code-rot --include cli"],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence: [
+                {
+                    kind: "file",
+                    message: "File is under an old/deprecated/legacy/_archive-named directory and is not mentioned in any doc file.",
+                    filePath: file.relativePath,
+                    source: DETECTOR_ID,
+                    confidence: "medium",
+                },
+            ],
+            affectedFiles: [file.relativePath],
+        }));
+    }
+    return issues;
+}
+function findOrphanedGeneratedFiles(files) {
+    const issues = [];
+    for (const file of files) {
+        if (file.likelyGenerated)
+            continue; // already caught by inventory's own generated category
+        if (!ORPHAN_GENERATED_PATTERN.test(path.basename(file.relativePath)))
+            continue;
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: ["orphaned-generated-looking-file", file.relativePath],
+            title: `Orphaned generated-looking file: "${file.relativePath}"`,
+            description: `"${file.relativePath}" has a generated/backup-looking name (.generated., .bak, .orig) but is not classified as generated content by the project inventory. This is a candidate for dead code.`,
+            severity: "low",
+            confidence: "medium",
+            falsePositiveRisk: "medium",
+            category: "dead-code-candidate",
+            recommendedAction: "Confirm the file is stale generated/backup content, then remove it.",
+            suggestedFixStrategy: `Remove "${file.relativePath}" if confirmed stale.`,
+            validationCommands: ["npm run audit -- --types code-rot --include cli"],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence: [
+                {
+                    kind: "file",
+                    message: "Filename matches a generated/backup-looking pattern outside the inventory's own generated-file classification.",
+                    filePath: file.relativePath,
+                    source: DETECTOR_ID,
+                    confidence: "medium",
+                },
+            ],
+            affectedFiles: [file.relativePath],
+        }));
+    }
+    return issues;
+}
+// Housed here (not in testRotDetector.ts) per the Batch 4 spec's explicit
+// instruction to implement this check exactly once to avoid duplicate
+// reporting between the two detectors.
+function findUnreferencedFixtures(ctx) {
+    const fixtureFiles = ctx.inventory.files.filter((f) => f.relativePath.includes("/fixtures/") || f.relativePath.startsWith("fixtures/"));
+    if (fixtureFiles.length === 0)
+        return [];
+    const testFilesContent = [];
+    for (const testFile of ctx.inventory.testFiles) {
+        const content = readBoundedFileText(ctx.target.rootPath, testFile.relativePath, testFile.sizeBytes, MAX_READ_BYTES);
+        if (content !== null)
+            testFilesContent.push(content);
+    }
+    const combinedTestContent = testFilesContent.join("\n");
+    const issues = [];
+    for (const fixture of fixtureFiles) {
+        const base = path.basename(fixture.relativePath);
+        if (combinedTestContent.includes(base))
+            continue;
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: ["unreferenced-fixture", fixture.relativePath],
+            title: `Fixture "${fixture.relativePath}" is not referenced by any test file`,
+            description: `"${fixture.relativePath}" is under a fixtures/ directory, but its basename does not appear in any test file's content. This is a weak candidate signal for an unused fixture.`,
+            severity: "info",
+            confidence: "low",
+            falsePositiveRisk: "high",
+            category: "dead-code-candidate",
+            recommendedAction: "Confirm the fixture is genuinely unused before removing it.",
+            suggestedFixStrategy: `Remove "${fixture.relativePath}" if confirmed unused.`,
+            validationCommands: ["npm run audit -- --types code-rot --include tests"],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence: [
+                {
+                    kind: "observation",
+                    message: "Fixture basename does not appear in any test file's bounded content scan.",
+                    filePath: fixture.relativePath,
+                    source: DETECTOR_ID,
+                    confidence: "low",
+                },
+            ],
+            affectedFiles: [fixture.relativePath],
+        }));
+    }
+    return issues;
+}

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

@@ -0,0 +1,244 @@
+import { readBoundedFileText } from "../utils/boundedRead.js";
+import { deduplicateIssuesById, makeCodeRotIssue } from "../utils/issueFactories.js";
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 4 — dependency/environment rot detector.
+//
+// Purely local: reads already-collected sourceOfTruth plus a bounded direct
+// read of docs content. No npm install/audit/registry calls and no
+// subprocess execution anywhere in this file (enforced by a structural
+// test, see dependencyEnvironmentRotDetector.test.ts).
+// ---------------------------------------------------------------------------
+const DETECTOR_ID = "dependency-environment-rot";
+const MAX_READ_BYTES = 200_000;
+const OTHER_PACKAGE_MANAGER_INSTALL_PATTERN = /\b(yarn add|pnpm add|pnpm install)\b/gi;
+const NPM_INSTALL_NEARBY_PATTERN = /\bnpm (install|ci)\b/i;
+const NODE_POLICY_CLAIM_PATTERN = /latest[- ]two|node (?:lts )?policy/i;
+const OPTIONAL_TOOL_PATTERN = /\b(codeql|semgrep|osv-scanner)\b/gi;
+export const DEPENDENCY_ENVIRONMENT_ROT_DETECTOR = {
+    id: DETECTOR_ID,
+    auditType: "code-rot",
+    title: "Dependency/environment rot",
+    description: "Detects package-manager instruction mismatches against the lockfile, Node engine/CI version mismatches, unverifiable Node-policy claims, and scripts invoking optional external tools that are undocumented.",
+    supportedIncludeAreas: ["package", "docs", "cli"],
+    shouldSkip: (ctx) => {
+        if (!ctx.config.include.includes("package")) {
+            return { skip: true, reason: "--include does not select package; this detector's primary signal is package.json/lockfile/CI metadata." };
+        }
+        return { skip: false };
+    },
+    run: (ctx) => {
+        const issues = [];
+        const pkg = ctx.sourceOfTruth.package;
+        if (!pkg)
+            return issues;
+        if (ctx.config.include.includes("docs")) {
+            const docsConcat = concatDocsContent(ctx);
+            issues.push(...findPackageManagerMismatch(ctx, docsConcat));
+            issues.push(...findNodePolicyClaimMismatch(ctx, docsConcat));
+            issues.push(...findUndocumentedOptionalTools(ctx, docsConcat));
+        }
+        issues.push(...findNodeEngineCiMismatch(ctx));
+        return deduplicateIssuesById(issues);
+    },
+};
+function concatDocsContent(ctx) {
+    const parts = [];
+    for (const docFile of ctx.inventory.docsFiles) {
+        const content = readBoundedFileText(ctx.target.rootPath, docFile.relativePath, docFile.sizeBytes, MAX_READ_BYTES);
+        if (content !== null)
+            parts.push({ relativePath: docFile.relativePath, content });
+    }
+    return parts;
+}
+function findPackageManagerMismatch(ctx, docs) {
+    if (!ctx.sourceOfTruth.lockfile.present)
+        return [];
+    const issues = [];
+    for (const doc of docs) {
+        OTHER_PACKAGE_MANAGER_INSTALL_PATTERN.lastIndex = 0;
+        for (const match of doc.content.matchAll(OTHER_PACKAGE_MANAGER_INSTALL_PATTERN)) {
+            const matchIndex = match.index ?? 0;
+            const windowStart = Math.max(0, matchIndex - 150);
+            const windowEnd = Math.min(doc.content.length, matchIndex + match[0].length + 150);
+            const window = doc.content.slice(windowStart, windowEnd);
+            if (NPM_INSTALL_NEARBY_PATTERN.test(window))
+                continue;
+            issues.push(makeCodeRotIssue({
+                auditType: "code-rot",
+                detectorId: DETECTOR_ID,
+                idCues: [doc.relativePath, "package-manager-mismatch", match[0].toLowerCase()],
+                title: `${doc.relativePath} instructs "${match[0]}" as install method, but package-lock.json (npm) is present`,
+                description: `${doc.relativePath} mentions "${match[0]}" as an install instruction with no nearby "npm install"/"npm ci" mention, but this project has an npm package-lock.json as its lockfile.`,
+                severity: "medium",
+                confidence: "medium",
+                falsePositiveRisk: "medium",
+                category: "dependency-environment-rot",
+                recommendedAction: `Update ${doc.relativePath} to instruct "npm install" or "npm ci" instead.`,
+                suggestedFixStrategy: `Replace "${match[0]}" with the npm equivalent in ${doc.relativePath}.`,
+                validationCommands: ["npm run audit -- --types code-rot --include package,docs"],
+                releaseBlocking: false,
+                implementationBlocking: false,
+                autoFixEligible: false,
+                evidence: [
+                    {
+                        kind: "file",
+                        message: `Doc references "${match[0]}" without a nearby npm install/ci mention, while package-lock.json (npm) is present.`,
+                        filePath: doc.relativePath,
+                        source: DETECTOR_ID,
+                        confidence: "medium",
+                    },
+                ],
+                affectedFiles: [doc.relativePath, "package-lock.json"],
+            }));
+        }
+    }
+    return issues;
+}
+function findNodeEngineCiMismatch(ctx) {
+    const engines = ctx.sourceOfTruth.package?.engines;
+    const nodeEngine = engines?.node;
+    if (!nodeEngine)
+        return [];
+    const minMatch = nodeEngine.match(/>=?\s*(\d+)/);
+    if (!minMatch)
+        return [];
+    const minVersion = Number(minMatch[1]);
+    const issues = [];
+    for (const workflow of ctx.sourceOfTruth.ci.workflows) {
+        for (const versionStr of workflow.nodeVersionsReferenced) {
+            const versionNum = Number(versionStr);
+            if (Number.isNaN(versionNum))
+                continue;
+            if (versionNum >= minVersion)
+                continue;
+            issues.push(makeCodeRotIssue({
+                auditType: "code-rot",
+                detectorId: DETECTOR_ID,
+                idCues: [workflow.relativePath, "node-engine-ci-mismatch", versionStr],
+                title: `CI workflow "${workflow.relativePath}" uses Node ${versionStr}, below package.json's engines.node minimum (${nodeEngine})`,
+                description: `package.json declares "engines.node": "${nodeEngine}" (minimum ${minVersion}), but ${workflow.relativePath} references Node ${versionStr}.`,
+                severity: "medium",
+                confidence: "high",
+                falsePositiveRisk: "low",
+                category: "dependency-environment-rot",
+                recommendedAction: `Update ${workflow.relativePath}'s Node version matrix or relax package.json's engines.node constraint.`,
+                suggestedFixStrategy: `Align the Node version in ${workflow.relativePath} with package.json's "engines.node" field.`,
+                validationCommands: ["npm run audit -- --types code-rot --include package"],
+                releaseBlocking: false,
+                implementationBlocking: false,
+                autoFixEligible: false,
+                evidence: [
+                    {
+                        kind: "file",
+                        message: `CI Node version (${versionStr}) is below package.json's engines.node minimum (${minVersion}).`,
+                        filePath: workflow.relativePath,
+                        expected: nodeEngine,
+                        observed: versionStr,
+                        source: DETECTOR_ID,
+                        confidence: "high",
+                    },
+                ],
+                affectedFiles: [workflow.relativePath, "package.json"],
+            }));
+        }
+    }
+    return issues;
+}
+function findNodePolicyClaimMismatch(ctx, docs) {
+    const allWorkflowVersions = new Set();
+    for (const workflow of ctx.sourceOfTruth.ci.workflows) {
+        for (const v of workflow.nodeVersionsReferenced)
+            allWorkflowVersions.add(v);
+    }
+    // Only flag when the claim is checkable in a low-noise way: CI has exactly
+    // one pinned version total, yet docs explicitly claim a multi-version
+    // policy.
+    if (allWorkflowVersions.size !== 1)
+        return [];
+    const issues = [];
+    for (const doc of docs) {
+        if (!NODE_POLICY_CLAIM_PATTERN.test(doc.content))
+            continue;
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: [doc.relativePath, "node-policy-claim-mismatch"],
+            title: `${doc.relativePath} claims a multi-version Node policy, but CI pins exactly one Node version`,
+            description: `${doc.relativePath} mentions a "latest two"/Node LTS policy claim, but CI workflows collectively reference exactly one Node version (${[...allWorkflowVersions][0]}).`,
+            severity: "medium",
+            confidence: "medium",
+            falsePositiveRisk: "medium",
+            category: "dependency-environment-rot",
+            recommendedAction: `Update ${doc.relativePath} or expand the CI Node version matrix to match the claim.`,
+            suggestedFixStrategy: `Align the Node-version policy claim in ${doc.relativePath} with the actual CI matrix.`,
+            validationCommands: ["npm run audit -- --types code-rot --include package,docs"],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence: [
+                {
+                    kind: "observation",
+                    message: "Doc claims a multi-version Node policy while CI references exactly one Node version.",
+                    filePath: doc.relativePath,
+                    source: DETECTOR_ID,
+                    confidence: "medium",
+                },
+            ],
+            affectedFiles: [doc.relativePath],
+        }));
+    }
+    return issues;
+}
+function findUndocumentedOptionalTools(ctx, docs) {
+    const pkg = ctx.sourceOfTruth.package;
+    if (!pkg)
+        return [];
+    const mentionedTools = new Set();
+    for (const [scriptName, command] of Object.entries(pkg.scripts)) {
+        OPTIONAL_TOOL_PATTERN.lastIndex = 0;
+        for (const match of command.matchAll(OPTIONAL_TOOL_PATTERN)) {
+            mentionedTools.add(`${match[1].toLowerCase()}::${scriptName}`);
+        }
+    }
+    if (mentionedTools.size === 0)
+        return [];
+    const combinedDocsLower = docs.map((d) => d.content).join("\n").toLowerCase();
+    const issues = [];
+    const seenTools = new Set();
+    for (const entry of mentionedTools) {
+        const [tool, scriptName] = entry.split("::");
+        if (seenTools.has(tool))
+            continue;
+        if (combinedDocsLower.includes(tool))
+            continue;
+        seenTools.add(tool);
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: ["undocumented-optional-tool", tool],
+            title: `Script "${scriptName}" invokes external tool "${tool}", which is not mentioned in any doc`,
+            description: `package.json script "${scriptName}" invokes "${tool}", but no doc file mentions it as optional or required.`,
+            severity: "low",
+            confidence: "low",
+            falsePositiveRisk: "medium",
+            category: "dependency-environment-rot",
+            recommendedAction: `Document "${tool}" as an optional/required tool in the relevant docs.`,
+            suggestedFixStrategy: `Add a short mention of "${tool}" (optional/required, and how it's skipped when unavailable) to docs/COMMANDS.md.`,
+            validationCommands: ["npm run audit -- --types code-rot --include package,docs"],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence: [
+                {
+                    kind: "observation",
+                    message: `"${tool}" appears in a package.json script command but not in any doc file.`,
+                    filePath: "package.json",
+                    source: DETECTOR_ID,
+                    confidence: "low",
+                },
+            ],
+            affectedFiles: ["package.json"],
+        }));
+    }
+    return issues;
+}