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

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;
+}

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

@@ -0,0 +1,219 @@
+import fs from "node:fs";
+import path from "node:path";
+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";
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 3 — documentation/code mismatch detector.
+//
+// Deterministic, regex/structured-cue only (no LLM, no broad semantic
+// interpretation, per Batch 3 scope). Publish/release claims and doc-vs-
+// package version mismatches are deliberately owned by
+// packageReleaseRotDetector.ts instead of here (both detectors' Batch 3
+// spec sections list overlapping bullets for those two checks; this
+// detector focuses on feature-implementation claims and the
+// full-release-gate-for-scoped-checks wording pattern, so the same
+// underlying signal is never reported twice by two different detectors).
+// ---------------------------------------------------------------------------
+const DETECTOR_ID = "docs-code-mismatch";
+const MAX_DOC_READ_BYTES = 200_000;
+// Deliberately small and conservative -- only features with an unambiguous,
+// directly-observable source-of-truth signal are checked. Audit's own
+// implementation status is intentionally excluded to avoid a
+// self-referential "is the audit tool auditing claims about itself"
+// complication in this batch.
+const FEATURE_CHECKS = [
+    {
+        featureId: "security-validation",
+        label: "security validation",
+        subjectPattern: "security validation",
+        isImplemented: (sot) => sot.security.hasSecurityValidationSourceDir && sot.security.hasSecurityValidateScript,
+    },
+    {
+        featureId: "experiment-framework",
+        label: "experiment framework",
+        subjectPattern: "experiment (?:framework|plugin)",
+        isImplemented: (sot) => sot.experiment.hasExperimentsSourceDir && sot.experiment.hasExperimentListScript,
+    },
+];
+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.",
+    supportedIncludeAreas: ["docs", "architecture", "cli", "package"],
+    shouldSkip: (ctx) => {
+        if (!ctx.config.include.includes("docs")) {
+            return { skip: true, reason: "--include does not select docs; this detector's checks are docs-based." };
+        }
+        return { skip: false };
+    },
+    run: (ctx) => {
+        const issues = [];
+        for (const docFile of ctx.inventory.docsFiles) {
+            const content = readBoundedText(ctx.target.rootPath, docFile.relativePath, docFile.sizeBytes);
+            if (content === null)
+                continue;
+            const lines = splitLines(content);
+            for (let i = 0; i < lines.length; i++) {
+                const line = lines[i];
+                for (const feature of FEATURE_CHECKS) {
+                    const currentMatch = currentClaimPatternFor(feature.subjectPattern).test(line);
+                    const plannedMatch = plannedClaimPatternFor(feature.subjectPattern).test(line);
+                    const implemented = feature.isImplemented(ctx.sourceOfTruth);
+                    if (currentMatch && plannedMatch) {
+                        // Same line claims both current and planned for the same
+                        // subject -- genuinely ambiguous, reported as low-confidence
+                        // info rather than skipped silently.
+                        issues.push(makeAmbiguousIssue(docFile.relativePath, i + 1, line, feature.label));
+                        continue;
+                    }
+                    if (currentMatch && !implemented) {
+                        issues.push(makeCurrentButMissingIssue(docFile.relativePath, i + 1, line, feature));
+                    }
+                    else if (plannedMatch && implemented) {
+                        issues.push(makePlannedButImplementedIssue(docFile.relativePath, i + 1, line, feature));
+                    }
+                }
+                if (FULL_RELEASE_GATE_FOR_SCOPED_CHECKS_PATTERN.test(line) && !isNegatedNearby(line)) {
+                    issues.push(makeFullReleaseGateIssue(docFile.relativePath, i + 1, line));
+                }
+            }
+        }
+        return deduplicateIssuesById(issues);
+    },
+};
+function makeCurrentButMissingIssue(relativePath, lineNumber, excerpt, feature) {
+    return makeCodeRotIssue({
+        auditType: "code-rot",
+        detectorId: DETECTOR_ID,
+        idCues: [relativePath, "current-but-missing", feature.featureId],
+        title: `Docs claim "${feature.label}" is implemented/current, but source-of-truth shows it is missing`,
+        description: `${relativePath}:${lineNumber} claims "${feature.label}" is implemented/current, but the expected source directory/script is not present.`,
+        severity: "high",
+        confidence: "medium",
+        falsePositiveRisk: "medium",
+        category: "docs-feature-mismatch",
+        recommendedAction: `Either implement the missing "${feature.label}" pieces, or update ${relativePath} to describe it as planned.`,
+        suggestedFixStrategy: `Correct the "${feature.label}" claim in ${relativePath} to match its actual implementation state.`,
+        validationCommands: ["npm run audit -- --types code-rot --include docs"],
+        releaseBlocking: false,
+        implementationBlocking: false,
+        autoFixEligible: false,
+        evidence: [
+            {
+                kind: "file",
+                message: `Doc claims "${feature.label}" is current/implemented; source-of-truth signal indicates it is not.`,
+                filePath: relativePath,
+                line: lineNumber,
+                excerpt: excerpt.trim().slice(0, 200),
+                source: DETECTOR_ID,
+                confidence: "medium",
+            },
+        ],
+        affectedFiles: [relativePath],
+    });
+}
+function makePlannedButImplementedIssue(relativePath, lineNumber, excerpt, feature) {
+    return makeCodeRotIssue({
+        auditType: "code-rot",
+        detectorId: DETECTOR_ID,
+        idCues: [relativePath, "planned-but-implemented", feature.featureId],
+        title: `Docs claim "${feature.label}" is planned/future, but it is already implemented`,
+        description: `${relativePath}:${lineNumber} describes "${feature.label}" as planned/future, but source-of-truth shows it is already present.`,
+        severity: "medium",
+        confidence: "medium",
+        falsePositiveRisk: "medium",
+        category: "docs-feature-mismatch",
+        recommendedAction: `Update ${relativePath} to describe "${feature.label}" as implemented/current.`,
+        suggestedFixStrategy: `Move the "${feature.label}" description out of the planned/roadmap section in ${relativePath}.`,
+        validationCommands: ["npm run audit -- --types code-rot --include docs"],
+        releaseBlocking: false,
+        implementationBlocking: false,
+        autoFixEligible: false,
+        evidence: [
+            {
+                kind: "file",
+                message: `Doc claims "${feature.label}" is planned/future; source-of-truth signal indicates it is already implemented.`,
+                filePath: relativePath,
+                line: lineNumber,
+                excerpt: excerpt.trim().slice(0, 200),
+                source: DETECTOR_ID,
+                confidence: "medium",
+            },
+        ],
+        affectedFiles: [relativePath],
+    });
+}
+function makeAmbiguousIssue(relativePath, lineNumber, excerpt, featureLabel) {
+    return makeCodeRotIssue({
+        auditType: "code-rot",
+        detectorId: DETECTOR_ID,
+        idCues: [relativePath, "ambiguous", featureLabel, String(lineNumber)],
+        title: `Ambiguous implementation-status claim for "${featureLabel}"`,
+        description: `${relativePath}:${lineNumber} appears to describe "${featureLabel}" as both current/implemented and planned/future in the same line -- not automatically resolvable.`,
+        severity: "info",
+        confidence: "low",
+        falsePositiveRisk: "high",
+        category: "docs-feature-mismatch-ambiguous",
+        recommendedAction: "Manually review this line for clarity.",
+        suggestedFixStrategy: "Rewrite the sentence so the implementation status of the feature is unambiguous.",
+        validationCommands: ["npm run audit -- --types code-rot --include docs"],
+        releaseBlocking: false,
+        implementationBlocking: false,
+        autoFixEligible: false,
+        evidence: [
+            {
+                kind: "file",
+                message: "Both a current/implemented cue and a planned/future cue matched the same line for the same subject.",
+                filePath: relativePath,
+                line: lineNumber,
+                excerpt: excerpt.trim().slice(0, 200),
+                source: DETECTOR_ID,
+                confidence: "low",
+            },
+        ],
+        affectedFiles: [relativePath],
+    });
+}
+function makeFullReleaseGateIssue(relativePath, lineNumber, excerpt) {
+    return makeCodeRotIssue({
+        auditType: "code-rot",
+        detectorId: DETECTOR_ID,
+        idCues: [relativePath, "full-release-gate-scoped-claim", String(lineNumber)],
+        title: `Docs describe a scoped run as a full release gate`,
+        description: `${relativePath}:${lineNumber} appears to describe a scoped (non-full) run as if it were a complete release gate.`,
+        severity: "medium",
+        confidence: "medium",
+        falsePositiveRisk: "medium",
+        category: "docs-feature-mismatch",
+        recommendedAction: `Clarify in ${relativePath} that a scoped run is not a full release gate.`,
+        suggestedFixStrategy: `Add explicit "scoped run, not a full release gate" wording near this claim in ${relativePath}.`,
+        validationCommands: ["npm run audit -- --types code-rot --include docs"],
+        releaseBlocking: false,
+        implementationBlocking: false,
+        autoFixEligible: false,
+        evidence: [
+            {
+                kind: "file",
+                message: "Matched a scoped-run-described-as-full-release-gate phrasing pattern.",
+                filePath: relativePath,
+                line: lineNumber,
+                excerpt: excerpt.trim().slice(0, 200),
+                source: DETECTOR_ID,
+                confidence: "medium",
+            },
+        ],
+        affectedFiles: [relativePath],
+    });
+}
+function readBoundedText(root, relativePath, sizeBytes) {
+    if (sizeBytes > MAX_DOC_READ_BYTES)
+        return null;
+    try {
+        return fs.readFileSync(path.join(root, relativePath), "utf8");
+    }
+    catch {
+        return null;
+    }
+}