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

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

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

@@ -0,0 +1,273 @@
+import { readBoundedFileText } from "../utils/boundedRead.js";
+import { firstPathSegment, GENERIC_INFRA_BASENAMES, baseNameNoExt } from "../utils/filePatternUtils.js";
+import { deduplicateIssuesById, makeCodeRotIssue } from "../utils/issueFactories.js";
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 4 — duplicate/parallel implementation candidate detector.
+//
+// Every check here is a *candidate* signal, never proof of duplication --
+// title/description wording is deliberately hedged throughout. Bounded,
+// deterministic, no fuzzy text similarity and no large file reads (only a
+// cheap regex scan of already-small detector source files for the
+// registry-id-duplicate sub-check).
+//
+// Simplifications made relative to the full Batch 4 spec bullet list (see
+// docs handed to this batch for the original wording):
+//   - "multiple report renderers for same feature family" is folded into the
+//     generic same-basename-across-unrelated-roots check (below) rather than
+//     a separate report-specific check -- a dedicated report-directory scan
+//     would duplicate that same logic for one category of directory.
+//   - "multiple validation runners for same command surface" and "duplicated
+//     script families where only one is documented" are SKIPPED: both
+//     require inferring "same command surface"/"same family" from script
+//     naming, which risks false positives without semantic judgment (out of
+//     scope). Left for a future batch if a cheap deterministic signal is
+//     found.
+//   - The registry-duplicate-id check is intentionally narrow: it scans
+//     source text of files under src/audits/codeRot/detectors/ for
+//     `id: "..."` string literals via a cheap regex (not a semantic parse),
+//     per the spec's own suggested simplification for that bullet.
+// ---------------------------------------------------------------------------
+const DETECTOR_ID = "duplicate-implementation-candidate";
+const MAX_READ_BYTES = 200_000;
+// Directory-name pairs commonly conflated in real projects (singular vs.
+// plural, or synonym pairs). Flagged only when BOTH variants exist as a
+// first path segment among inventoried files.
+const PARALLEL_DIR_PAIRS = [
+    ["report", "reports"],
+    ["test", "tests"],
+    ["util", "utils"],
+    ["script", "scripts"],
+    ["doc", "docs"],
+];
+export const DUPLICATE_IMPLEMENTATION_DETECTOR = {
+    id: DETECTOR_ID,
+    auditType: "code-rot",
+    title: "Duplicate/parallel implementation candidate",
+    description: "Detects candidate (not proven) duplicate or parallel implementations: overlapping npm script entrypoints, parallel singular/plural directories, duplicate detector-registry ids, and repeated basenames across unrelated source roots.",
+    supportedIncludeAreas: ["cli", "package", "architecture"],
+    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 scripts." };
+        }
+        return { skip: false };
+    },
+    run: (ctx) => {
+        const issues = [];
+        const pkg = ctx.sourceOfTruth.package;
+        if (pkg) {
+            issues.push(...findDuplicateScriptEntrypoints(pkg.scripts));
+        }
+        if (ctx.config.include.includes("architecture")) {
+            issues.push(...findParallelDirectories(ctx.inventory.files.map((f) => f.relativePath)));
+            issues.push(...findDuplicateBasenamesAcrossRoots(ctx.inventory.sourceFiles.map((f) => f.relativePath)));
+        }
+        issues.push(...findDuplicateDetectorRegistryIds(ctx));
+        return deduplicateIssuesById(issues);
+    },
+};
+// Groups scripts by the file path they invoke (first "scripts/..." token in
+// the command) and flags when 2+ distinct script names invoke the exact
+// same target file -- a strong, low-noise duplicate-entrypoint signal.
+function findDuplicateScriptEntrypoints(scripts) {
+    const byTarget = new Map();
+    for (const [name, command] of Object.entries(scripts)) {
+        const match = command.match(/\b(scripts\/[\w./-]+\.[cm]?[jt]sx?)\b/);
+        if (!match)
+            continue;
+        const target = match[1];
+        const names = byTarget.get(target) ?? [];
+        names.push(name);
+        byTarget.set(target, names);
+    }
+    const issues = [];
+    for (const [target, names] of byTarget) {
+        if (names.length < 2)
+            continue;
+        const sortedNames = [...names].sort((a, b) => a.localeCompare(b));
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: ["script-entrypoint-candidate", target],
+            title: `Multiple npm scripts may be duplicate entrypoints for "${target}"`,
+            description: `Scripts ${sortedNames.map((n) => `"${n}"`).join(", ")} all invoke "${target}" -- this may indicate duplicate/parallel CLI entrypoints for the same feature, or may be intentional aliasing. Inspect manually before consolidating.`,
+            severity: "medium",
+            confidence: "medium",
+            falsePositiveRisk: "medium",
+            category: "duplicate-implementation-candidate",
+            recommendedAction: "Manually confirm whether these scripts are intentional aliases or accidental duplicates before consolidating or removing any of them.",
+            suggestedFixStrategy: "If duplicated unintentionally, keep one canonical script name and remove or redirect the others.",
+            validationCommands: ["npm run audit -- --types code-rot --include package"],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence: [
+                {
+                    kind: "reference",
+                    message: `${sortedNames.length} package.json scripts invoke the same target file.`,
+                    filePath: "package.json",
+                    excerpt: sortedNames.join(", "),
+                    source: DETECTOR_ID,
+                    confidence: "medium",
+                },
+            ],
+            affectedFiles: ["package.json", target],
+        }));
+    }
+    return issues;
+}
+function findParallelDirectories(relativePaths) {
+    const topSegments = new Set(relativePaths.map((p) => firstPathSegment(p)).filter((s) => s !== null));
+    // Also consider the file itself as a "segment" for root-level layout
+    // (rare, but keeps this check symmetric for flat projects).
+    for (const p of relativePaths) {
+        if (!p.includes("/"))
+            topSegments.add(p);
+    }
+    const issues = [];
+    for (const [a, b] of PARALLEL_DIR_PAIRS) {
+        if (topSegments.has(a) && topSegments.has(b)) {
+            issues.push(makeCodeRotIssue({
+                auditType: "code-rot",
+                detectorId: DETECTOR_ID,
+                idCues: ["parallel-directory-candidate", a, b],
+                title: `Both "${a}/" and "${b}/" exist as top-level directories`,
+                description: `Both "${a}/" and "${b}/" are present at the project root -- this may indicate parallel/overlapping directories for the same responsibility. Inspect manually before consolidating.`,
+                severity: "low",
+                confidence: "low",
+                falsePositiveRisk: "medium",
+                category: "duplicate-implementation-candidate",
+                recommendedAction: `Confirm whether "${a}/" and "${b}/" serve distinct purposes; if not, consolidate into one.`,
+                suggestedFixStrategy: `Merge "${a}/" and "${b}/" or rename one to make the distinction explicit.`,
+                validationCommands: ["npm run audit -- --types code-rot --include architecture"],
+                releaseBlocking: false,
+                implementationBlocking: false,
+                autoFixEligible: false,
+                evidence: [
+                    {
+                        kind: "observation",
+                        message: `Both "${a}/" and "${b}/" exist as top-level project directories.`,
+                        source: DETECTOR_ID,
+                        confidence: "low",
+                    },
+                ],
+                affectedFiles: [`${a}/`, `${b}/`],
+            }));
+        }
+    }
+    return issues;
+}
+// Weak/low-confidence signal: the same basename repeated across 2-3
+// unrelated top-level source roots, excluding generic infra names (index,
+// types, config, etc.) that legitimately repeat by convention.
+function findDuplicateBasenamesAcrossRoots(sourceRelativePaths) {
+    const byBasename = new Map();
+    for (const relativePath of sourceRelativePaths) {
+        const base = baseNameNoExt(relativePath).toLowerCase();
+        if (GENERIC_INFRA_BASENAMES.has(base))
+            continue;
+        const top = firstTopLevelUnderSrc(relativePath);
+        if (top === null)
+            continue;
+        const roots = byBasename.get(base) ?? new Set();
+        roots.add(top);
+        byBasename.set(base, roots);
+    }
+    const issues = [];
+    for (const [base, roots] of byBasename) {
+        if (roots.size < 2 || roots.size > 3)
+            continue;
+        const sortedRoots = [...roots].sort((a, b) => a.localeCompare(b));
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: ["basename-repeat-candidate", base, ...sortedRoots],
+            title: `Basename "${base}" repeats across unrelated source roots (weak signal)`,
+            description: `A file named "${base}.*" exists under multiple unrelated top-level source directories: ${sortedRoots.join(", ")}. This is a weak candidate signal for parallel implementations -- inspect manually.`,
+            severity: "info",
+            confidence: "low",
+            falsePositiveRisk: "high",
+            category: "duplicate-implementation-candidate",
+            recommendedAction: "Manually confirm whether these files serve genuinely different purposes before taking any action.",
+            suggestedFixStrategy: "No automatic action -- rename or consolidate only after manual review.",
+            validationCommands: ["npm run audit -- --types code-rot --include architecture"],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence: [
+                {
+                    kind: "observation",
+                    message: `Basename "${base}" appears under ${sortedRoots.length} different top-level source directories.`,
+                    source: DETECTOR_ID,
+                    confidence: "low",
+                },
+            ],
+            affectedFiles: sortedRoots,
+        }));
+    }
+    return issues;
+}
+function firstTopLevelUnderSrc(relativePath) {
+    const parts = relativePath.split("/");
+    if (parts.length < 3)
+        return null; // need at least src/<dir>/file
+    if (parts[0] !== "src" && parts[0] !== "scripts")
+        return null;
+    return `${parts[0]}/${parts[1]}`;
+}
+// Cheap regex scan (not a semantic parse) of already-small detector source
+// files for exported `id: "..."` string literals. Flags duplicates only if
+// genuinely found via this file-based check -- per the spec's own allowed
+// simplification, this does not attempt to reconcile against
+// DEFAULT_AUDIT_REGISTRY at runtime (that would be circular).
+function findDuplicateDetectorRegistryIds(ctx) {
+    const detectorFiles = ctx.inventory.sourceFiles.filter((f) => /\/detectors\/[\w-]+\.ts$/.test(f.relativePath));
+    if (detectorFiles.length === 0)
+        return [];
+    const idsToFiles = new Map();
+    for (const file of detectorFiles) {
+        const content = readBoundedFileText(ctx.target.rootPath, file.relativePath, file.sizeBytes, MAX_READ_BYTES);
+        if (content === null)
+            continue;
+        const match = content.match(/\bid:\s*DETECTOR_ID\b/) ? content.match(/const DETECTOR_ID\s*=\s*"([^"]+)"/) : content.match(/\bid:\s*"([^"]+)"/);
+        if (!match)
+            continue;
+        const id = match[1];
+        const files = idsToFiles.get(id) ?? [];
+        files.push(file.relativePath);
+        idsToFiles.set(id, files);
+    }
+    const issues = [];
+    for (const [id, files] of idsToFiles) {
+        if (files.length < 2)
+            continue;
+        const sortedFiles = [...files].sort((a, b) => a.localeCompare(b));
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: ["duplicate-detector-id", id],
+            title: `Multiple detector files declare the same detector id "${id}"`,
+            description: `Files ${sortedFiles.map((f) => `"${f}"`).join(", ")} appear to declare the same detector id "${id}". Registry construction rejects true duplicate ids at runtime; this file-based scan is a defensive early signal.`,
+            severity: "medium",
+            confidence: "medium",
+            falsePositiveRisk: "low",
+            category: "duplicate-implementation-candidate",
+            recommendedAction: "Rename one of the conflicting detector ids.",
+            suggestedFixStrategy: `Give each detector a unique id string.`,
+            validationCommands: ["npm run audit -- --types code-rot --include architecture"],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence: [
+                {
+                    kind: "reference",
+                    message: `Detector id "${id}" found in ${sortedFiles.length} files.`,
+                    excerpt: sortedFiles.join(", "),
+                    source: DETECTOR_ID,
+                    confidence: "medium",
+                },
+            ],
+            affectedFiles: sortedFiles,
+        }));
+    }
+    return issues;
+}