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

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

@@ -0,0 +1,348 @@
+import fs from "node:fs";
+import path from "node:path";
+import { readBoundedFileText } from "../utils/boundedRead.js";
+import { deduplicateIssuesById, makeCodeRotIssue } from "../utils/issueFactories.js";
+import { splitLines } from "../utils/textLines.js";
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 4 — test-rot detector.
+//
+// Bounded (per-file MAX_READ_BYTES skip), regex/structural only.
+//
+// Two spec bullets are intentionally SKIPPED here to avoid duplicate
+// reporting with other detectors (documented in the Batch 4 spec itself):
+//   - "fixtures not referenced by tests" is implemented once, in
+//     deadCodeCandidateDetector.ts's findUnreferencedFixtures(), not here.
+//   - "test commands documented in docs but missing from package.json
+//     scripts" overlaps with staleCommandReferenceDetector.ts's existing
+//     doc-command check and is intentionally not re-implemented here.
+// ---------------------------------------------------------------------------
+const DETECTOR_ID = "test-rot";
+const MAX_READ_BYTES = 200_000;
+const RELATIVE_IMPORT_PATTERN = /(?:from|require\()\s*["'](\.\.?\/[^"']+)["']/g;
+const NPM_RUN_PATTERN = /npm run ([\w:.-]+)/g;
+const SKIP_PATTERN = /\b(describe|it|test)\.skip\s*\(/g;
+const ONLY_PATTERN = /\b(describe|it|test)\.only\s*\(/g;
+const TEST_TITLE_VERSION_PATTERN = /\b(describe|it|test)\s*\(\s*["'`][^"'`]*\bv(\d+\.\d+\.\d+)\b/;
+const HISTORICAL_HEDGE_PATTERN = /\b(regression|historical|legacy)\b/i;
+const RESOLVE_EXTENSIONS = ["", ".ts", ".tsx", ".js", ".mjs", ".cjs"];
+const VITEST_RUN_ARG_PATTERN = /vitest run ([^\s&|]+)/g;
+export const TEST_ROT_DETECTOR = {
+    id: DETECTOR_ID,
+    auditType: "code-rot",
+    title: "Test rot",
+    description: "Detects test files importing missing source files, stale npm-run references, committed .skip/.only usage, stale version mentions in test titles, and package scripts referencing missing test paths.",
+    supportedIncludeAreas: ["tests", "cli", "package"],
+    shouldSkip: (ctx) => {
+        if (!ctx.config.include.includes("tests")) {
+            return { skip: true, reason: "--include does not select tests; this detector's checks are test-file-based." };
+        }
+        return { skip: false };
+    },
+    run: (ctx) => {
+        const issues = [];
+        const scriptNames = new Set(ctx.sourceOfTruth.commands.allScriptNames);
+        const currentVersion = ctx.sourceOfTruth.package?.version ?? null;
+        for (const testFile of ctx.inventory.testFiles) {
+            const content = readBoundedFileText(ctx.target.rootPath, testFile.relativePath, testFile.sizeBytes, MAX_READ_BYTES);
+            if (content === null)
+                continue;
+            // tests/audits/codeRot/ is this project's own audit-detector test
+            // suite. Its whole purpose is to construct FIXTURE content (via
+            // writeFile() string arguments) that mimics the exact textual
+            // patterns this file's checks look for -- fake relative imports,
+            // fake "npm run <command>" references, "describe.skip("/"it.only(",
+            // and version-numbered test titles like `it("... v0.2.1 ...")`.
+            // Scanning those fixture strings as if they were real test-file
+            // content produces false positives against this repo's own accurate
+            // tests (confirmed via self-testing on every one of the checks
+            // below). This whole subdirectory is therefore excluded from this
+            // detector's per-file checks -- a project without an audit-detector
+            // test suite of its own would never hit this exclusion.
+            if (testFile.relativePath.startsWith("tests/audits/codeRot/"))
+                continue;
+            issues.push(...findMissingSourceImports(ctx, testFile.relativePath, content));
+            issues.push(...findStaleNpmRunReferences(testFile.relativePath, content, scriptNames));
+            issues.push(...findSkipUsage(testFile.relativePath, content));
+            issues.push(...findOnlyUsage(testFile.relativePath, content));
+            if (currentVersion)
+                issues.push(...findStaleVersionMentions(testFile.relativePath, content, currentVersion));
+        }
+        if (ctx.config.include.includes("package") && ctx.sourceOfTruth.package) {
+            issues.push(...findScriptsReferencingMissingTestPaths(ctx));
+        }
+        return deduplicateIssuesById(issues);
+    },
+};
+function findMissingSourceImports(ctx, testRelativePath, content) {
+    const issues = [];
+    const testDir = path.dirname(testRelativePath);
+    RELATIVE_IMPORT_PATTERN.lastIndex = 0;
+    for (const match of content.matchAll(RELATIVE_IMPORT_PATTERN)) {
+        const specifier = match[1];
+        const resolvedBase = path.join(testDir, specifier).replace(/\\/g, "/");
+        const strippedBase = resolvedBase.replace(/\.[cm]?[jt]sx?$/, "");
+        const resolved = RESOLVE_EXTENSIONS.some((ext) => fs.existsSync(path.join(ctx.target.rootPath, `${strippedBase}${ext}`)));
+        if (resolved)
+            continue;
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: [testRelativePath, "missing-source-import", specifier],
+            title: `Test "${testRelativePath}" imports a missing source file: "${specifier}"`,
+            description: `${testRelativePath} imports "${specifier}", which does not resolve to an existing file on disk (checked common TS/JS extensions relative to the test file).`,
+            severity: "medium",
+            confidence: "high",
+            falsePositiveRisk: "low",
+            category: "test-rot",
+            recommendedAction: "Fix or remove the stale import.",
+            suggestedFixStrategy: `Update the import specifier "${specifier}" in ${testRelativePath} to point to an existing file.`,
+            validationCommands: [`npx vitest run ${testRelativePath}`],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence: [
+                {
+                    kind: "file",
+                    message: "Relative import specifier does not resolve to an existing file.",
+                    filePath: testRelativePath,
+                    excerpt: specifier,
+                    source: DETECTOR_ID,
+                    confidence: "high",
+                },
+            ],
+            affectedFiles: [testRelativePath],
+        }));
+    }
+    return issues;
+}
+function findStaleNpmRunReferences(testRelativePath, content, scriptNames) {
+    const issues = [];
+    const seen = new Set();
+    // Scanned per-line (not whole-content) so a line can be cheaply excluded
+    // when it's clearly constructing FIXTURE content for another detector's
+    // test (e.g. `writeFile(root, "README.md", "Run \`npm run fake-cmd\`
+    // ...")`) rather than a real reference to an npm command. This is the
+    // exact shape used throughout this repo's own audit-detector test files
+    // (see tests/audits/codeRot/*.test.ts) -- without this exclusion, this
+    // detector flags this repo's own accurate test suite as if its
+    // synthetic fixture strings were real stale command references, a false
+    // positive confirmed via self-testing.
+    const lines = splitLines(content);
+    for (const line of lines) {
+        if (/\bwriteFile\s*\(/.test(line))
+            continue;
+        NPM_RUN_PATTERN.lastIndex = 0;
+        for (const match of line.matchAll(NPM_RUN_PATTERN)) {
+            const scriptName = match[1];
+            if (scriptNames.has(scriptName) || seen.has(scriptName))
+                continue;
+            seen.add(scriptName);
+            issues.push(makeCodeRotIssue({
+                auditType: "code-rot",
+                detectorId: DETECTOR_ID,
+                idCues: [testRelativePath, "stale-npm-run-reference", scriptName],
+                title: `Test "${testRelativePath}" references "npm run ${scriptName}", which is not a current package.json script`,
+                description: `${testRelativePath} references "npm run ${scriptName}" but no such script exists in package.json.`,
+                severity: "medium",
+                confidence: "medium",
+                falsePositiveRisk: "medium",
+                category: "test-rot",
+                recommendedAction: "Update the test to reference a current script name, or add the missing script.",
+                suggestedFixStrategy: `Correct the "npm run ${scriptName}" reference in ${testRelativePath}.`,
+                validationCommands: [`npx vitest run ${testRelativePath}`],
+                releaseBlocking: false,
+                implementationBlocking: false,
+                autoFixEligible: false,
+                evidence: [
+                    {
+                        kind: "file",
+                        message: `Referenced command "npm run ${scriptName}" not found in package.json scripts.`,
+                        filePath: testRelativePath,
+                        source: DETECTOR_ID,
+                        confidence: "medium",
+                    },
+                ],
+                affectedFiles: [testRelativePath],
+            }));
+        }
+    }
+    return issues;
+}
+function findSkipUsage(testRelativePath, content) {
+    const issues = [];
+    const lines = splitLines(content);
+    for (let i = 0; i < lines.length; i++) {
+        SKIP_PATTERN.lastIndex = 0;
+        const match = SKIP_PATTERN.exec(lines[i]);
+        if (!match)
+            continue;
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: [testRelativePath, "skip-usage", String(i + 1)],
+            title: `Committed "${match[1]}.skip(" in "${testRelativePath}"`,
+            description: `${testRelativePath}:${i + 1} uses "${match[1]}.skip(" -- confirm this is intentional and not accidentally committed.`,
+            severity: "medium",
+            confidence: "high",
+            falsePositiveRisk: "low",
+            category: "test-rot",
+            recommendedAction: "Remove .skip if the test should run, or add a comment explaining why it is skipped.",
+            suggestedFixStrategy: `Remove "${match[1]}.skip(" at ${testRelativePath}:${i + 1} or document why it is intentionally skipped.`,
+            validationCommands: [`npx vitest run ${testRelativePath}`],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence: [
+                {
+                    kind: "file",
+                    message: `Found "${match[1]}.skip(" usage.`,
+                    filePath: testRelativePath,
+                    line: i + 1,
+                    excerpt: lines[i].trim().slice(0, 200),
+                    source: DETECTOR_ID,
+                    confidence: "high",
+                },
+            ],
+            affectedFiles: [testRelativePath],
+        }));
+    }
+    return issues;
+}
+function findOnlyUsage(testRelativePath, content) {
+    const issues = [];
+    const lines = splitLines(content);
+    for (let i = 0; i < lines.length; i++) {
+        ONLY_PATTERN.lastIndex = 0;
+        const match = ONLY_PATTERN.exec(lines[i]);
+        if (!match)
+            continue;
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: [testRelativePath, "only-usage", String(i + 1)],
+            title: `Committed "${match[1]}.only(" in "${testRelativePath}"`,
+            description: `${testRelativePath}:${i + 1} uses "${match[1]}.only(" -- this silently excludes every other test in a CI run and is almost always accidental.`,
+            severity: "high",
+            confidence: "high",
+            falsePositiveRisk: "low",
+            category: "test-rot",
+            recommendedAction: "Remove .only before committing/merging.",
+            suggestedFixStrategy: `Remove "${match[1]}.only(" at ${testRelativePath}:${i + 1}.`,
+            validationCommands: [`npx vitest run ${testRelativePath}`],
+            releaseBlocking: true,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence: [
+                {
+                    kind: "file",
+                    message: `Found "${match[1]}.only(" usage.`,
+                    filePath: testRelativePath,
+                    line: i + 1,
+                    excerpt: lines[i].trim().slice(0, 200),
+                    source: DETECTOR_ID,
+                    confidence: "high",
+                },
+            ],
+            affectedFiles: [testRelativePath],
+        }));
+    }
+    return issues;
+}
+function findStaleVersionMentions(testRelativePath, content, currentVersion) {
+    const issues = [];
+    const lines = splitLines(content);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const match = line.match(TEST_TITLE_VERSION_PATTERN);
+        if (!match)
+            continue;
+        const mentionedVersion = match[2];
+        if (mentionedVersion === currentVersion)
+            continue;
+        if (HISTORICAL_HEDGE_PATTERN.test(line))
+            continue;
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: [testRelativePath, "stale-version-mention", String(i + 1), mentionedVersion],
+            title: `Test title in "${testRelativePath}" mentions version v${mentionedVersion}, not the current package version`,
+            description: `${testRelativePath}:${i + 1} mentions "v${mentionedVersion}" in a test title, but the current package version is "${currentVersion}". If this is intentionally a historical/regression reference, mention that in the title.`,
+            severity: "low",
+            confidence: "low",
+            falsePositiveRisk: "medium",
+            category: "test-rot",
+            recommendedAction: "Confirm whether the version mention should be updated or is intentionally historical.",
+            suggestedFixStrategy: `Update the test title in ${testRelativePath} or add "regression"/"historical" wording if intentional.`,
+            validationCommands: [`npx vitest run ${testRelativePath}`],
+            releaseBlocking: false,
+            implementationBlocking: false,
+            autoFixEligible: false,
+            evidence: [
+                {
+                    kind: "file",
+                    message: `Test title mentions "v${mentionedVersion}", current package version is "${currentVersion}".`,
+                    filePath: testRelativePath,
+                    line: i + 1,
+                    excerpt: line.trim().slice(0, 200),
+                    source: DETECTOR_ID,
+                    confidence: "low",
+                },
+            ],
+            affectedFiles: [testRelativePath],
+        }));
+    }
+    return issues;
+}
+function findScriptsReferencingMissingTestPaths(ctx) {
+    const issues = [];
+    const pkg = ctx.sourceOfTruth.package;
+    if (!pkg)
+        return issues;
+    const knownPaths = new Set(ctx.inventory.files.map((f) => f.relativePath));
+    const knownDirPrefixes = new Set(ctx.inventory.files.flatMap((f) => {
+        const parts = f.relativePath.split("/");
+        const prefixes = [];
+        for (let i = 1; i < parts.length; i++)
+            prefixes.push(parts.slice(0, i).join("/"));
+        return prefixes;
+    }));
+    for (const [scriptName, command] of Object.entries(pkg.scripts)) {
+        VITEST_RUN_ARG_PATTERN.lastIndex = 0;
+        for (const match of command.matchAll(VITEST_RUN_ARG_PATTERN)) {
+            const referencedPath = match[1].replace(/^["']|["']$/g, "");
+            if (knownPaths.has(referencedPath) || knownDirPrefixes.has(referencedPath))
+                continue;
+            if (fs.existsSync(path.join(ctx.target.rootPath, referencedPath)))
+                continue;
+            issues.push(makeCodeRotIssue({
+                auditType: "code-rot",
+                detectorId: DETECTOR_ID,
+                idCues: ["script-references-missing-test-path", scriptName, referencedPath],
+                title: `Script "${scriptName}" references a test path that does not exist: "${referencedPath}"`,
+                description: `package.json script "${scriptName}" runs "vitest run ${referencedPath}", but "${referencedPath}" does not exist in the project.`,
+                severity: "medium",
+                confidence: "high",
+                falsePositiveRisk: "low",
+                category: "test-rot",
+                recommendedAction: "Fix the script's test path, or restore/remove the referenced tests.",
+                suggestedFixStrategy: `Edit package.json's "${scriptName}" script to reference an existing test path.`,
+                validationCommands: [`npm run ${scriptName}`],
+                releaseBlocking: false,
+                implementationBlocking: false,
+                autoFixEligible: false,
+                evidence: [
+                    {
+                        kind: "file",
+                        message: `Script command references a test path that does not exist.`,
+                        filePath: "package.json",
+                        excerpt: `"${scriptName}": "... vitest run ${referencedPath} ..."`,
+                        source: DETECTOR_ID,
+                        confidence: "high",
+                    },
+                ],
+                affectedFiles: ["package.json"],
+            }));
+        }
+    }
+    return issues;
+}

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

@@ -0,0 +1,23 @@
+import fs from "node:fs";
+import path from "node:path";
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 4 — shared bounded file-read helper.
+//
+// Every Batch 3 detector duplicated its own local readBoundedText() helper.
+// Batch 4 factors the identical logic out once so the seven new detectors
+// don't each re-implement it. Behavior is unchanged: returns null (never
+// throws) for an oversized file or an unreadable path.
+// ---------------------------------------------------------------------------
+export function readBoundedFileText(root, relativePath, sizeBytes, maxBytes) {
+    if (sizeBytes > maxBytes)
+        return null;
+    try {
+        return fs.readFileSync(path.join(root, relativePath), "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+export function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

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

@@ -0,0 +1,62 @@
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 3 — deterministic doc-claim regex patterns.
+//
+// Shared by docsCodeMismatchDetector.ts and packageReleaseRotDetector.ts.
+// Every pattern here matches a narrow, explicit phrase rather than inferring
+// meaning from prose -- per Batch 3 scope, no LLM and no broad semantic
+// interpretation. Ambiguous or ISF-style hedged wording ("not yet
+// published", "planned for a later version") deliberately does not match
+// these "unhedged claim" patterns.
+// ---------------------------------------------------------------------------
+// An unhedged claim that publication/release/tagging has already happened.
+// A nearby hedge word ("not yet", "has not", "no") should be checked by the
+// caller before treating a match as a real claim -- see
+// isHedgedNearby() below.
+export const PUBLISHED_OR_RELEASED_CLAIM_PATTERN = /\b(is now published|has been published to npm|npm publish (?:has |)(?:completed|succeeded)|published to npm|github release (?:has been created|exists|created)|release has been created|has been tagged|git tag (?:has been created|created))\b/i;
+// Common hedge words that, if present in the same line/window, indicate the
+// author is explicitly describing something as NOT having happened yet --
+// used to suppress a false match on "is now published" when the actual
+// sentence is "... has not been published to npm" etc.
+const HEDGE_PATTERN = /\b(not yet|has not|have not|hasn't|haven't|no(?:t)?\b.{0,20}\byet\b|never)\b/i;
+export function isHedgedNearby(windowText) {
+    return HEDGE_PATTERN.test(windowText);
+}
+// Matches "current package is v1.2.3" / "current version is `1.2.3`" /
+// "package is version 1.2.3" style phrasing used across this project's own
+// docs (README.md, docs/CURRENT_STATE.md, docs/PROJECT_OVERVIEW.md).
+export const CURRENT_PACKAGE_VERSION_PATTERNS = [
+    /current package is `?v?(\d+\.\d+\.\d+)`?/i,
+    /current package (?:version )?(?:is|remains) `?v?(\d+\.\d+\.\d+)`?/i,
+    /package is version `?(\d+\.\d+\.\d+)`?/i,
+];
+// A scoped (non-full) --checks run being described as if it were a complete
+// release gate. Matches the bare phrase; callers must additionally check
+// isNegatedNearby() before treating a match as a real (mistaken) claim --
+// this project's own docs correctly say things like "rather than described
+// as a full release gate" and "it is not the same as a full release gate",
+// which contain the phrase precisely BECAUSE they are correctly denying it.
+export const FULL_RELEASE_GATE_FOR_SCOPED_CHECKS_PATTERN = /scoped[^.\n]{0,80}(full release gate|full audit coverage|complete release gate)/i;
+// Negation cues that, appearing in the same sentence as a
+// FULL_RELEASE_GATE_FOR_SCOPED_CHECKS_PATTERN match, indicate the sentence
+// is correctly denying the claim rather than making it.
+const NEGATION_PATTERN = /\b(not|rather than|isn't|is not|n't)\b/i;
+export function isNegatedNearby(windowText) {
+    return NEGATION_PATTERN.test(windowText);
+}
+// Feature-implementation claim phrasing: "<subject> is implemented" /
+// "<subject> is current" vs "<subject> is planned" / "<subject> is future".
+//
+// Deliberately narrow (subject-anchored, not a freestanding scan for
+// "current"/"planned" anywhere in a line) -- this project's own docs
+// legitimately use both words in the same sentence when correctly
+// describing a roadmap (e.g. "separates the implemented baseline from
+// planned work"), and a broad co-occurrence scan would flag that as
+// ambiguous noise. Anchoring both patterns to the same feature subject
+// keeps false positives near zero: a real ambiguous match requires the
+// SAME subject to be described as both implemented and planned.
+export function currentClaimPatternFor(subjectPattern) {
+    return new RegExp(`${subjectPattern}[^.\\n]{0,40}\\b(is implemented|is current|is now implemented)\\b`, "i");
+}
+export function plannedClaimPatternFor(subjectPattern) {
+    return new RegExp(`${subjectPattern}[^.\\n]{0,40}\\b(is planned|is future|is not yet implemented|not implemented)\\b`, "i");
+}

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

@@ -0,0 +1,64 @@
+import { splitLines } from "./textLines.js";
+// Skips optional leading "npm run" flags (e.g. "npm run --silent <script>")
+// before capturing the actual script name -- without this, "--silent" itself
+// gets captured as if it were the script name.
+const NPM_RUN_PATTERN = /npm run (?:--\S+\s+)*([\w:.-]+)/g;
+// Cues that mark a nearby command reference as planned/future/intentionally-
+// unimplemented rather than a current, working example. Deliberately
+// conservative wording match (whole word/phrase), not broad semantic
+// inference. "avoid" covers this project's own "commands to avoid unless
+// truly necessary" roadmap convention for commands that are deliberately
+// never meant to exist.
+const PLANNED_LABEL_PATTERN = /\b(planned|future|roadmap|not implemented|not yet implemented|later version|coming soon|avoid)\b/i;
+// How many lines above the reference line to include when checking for a
+// planned-label cue, in addition to the enclosing-heading check below.
+// Covers a preceding sentence or list-intro line that isn't itself a
+// markdown heading (e.g. "Commands to avoid unless truly necessary:") and
+// may be more than a few lines above the last item in a long bullet list.
+const PLANNED_LABEL_WINDOW_LINES = 15;
+const HEADING_PATTERN = /^(#{1,6})\s+(.*)$/;
+export function extractDocCommandReferences(content) {
+    const lines = splitLines(content);
+    const refs = [];
+    const seenOnLine = new Set();
+    // Tracks the most recently seen heading text at each markdown heading
+    // depth (1-6) as we scan top to bottom. A reference nested arbitrarily
+    // deep under a "## Planned ..." section inherits that section's framing
+    // even when the nearest local text (a sibling "### v0.4.0 ..." heading,
+    // say) doesn't itself contain a planned-label word -- this is what makes
+    // the check robust to roadmap documents with many nested version
+    // subsections, without an unbounded backward text scan.
+    const headingStack = new Array(7).fill(undefined);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const headingMatch = line.match(HEADING_PATTERN);
+        if (headingMatch) {
+            const depth = headingMatch[1].length;
+            headingStack[depth] = headingMatch[2];
+            // A new heading at depth N implicitly starts a fresh subsection for
+            // every deeper level -- clear them so a later, unrelated deep
+            // heading under a different parent doesn't leak stale context.
+            for (let d = depth + 1; d < headingStack.length; d++)
+                headingStack[d] = undefined;
+        }
+        NPM_RUN_PATTERN.lastIndex = 0;
+        for (const match of line.matchAll(NPM_RUN_PATTERN)) {
+            const command = match[1];
+            const key = `${i}:${command}`;
+            if (seenOnLine.has(key))
+                continue;
+            seenOnLine.add(key);
+            const windowStart = Math.max(0, i - PLANNED_LABEL_WINDOW_LINES);
+            const localWindow = lines.slice(windowStart, i + 1).join(" ");
+            const headingContext = headingStack.filter((h) => h !== undefined).join(" ");
+            const combined = `${headingContext} ${localWindow}`;
+            refs.push({
+                command,
+                lineNumber: i + 1,
+                excerpt: line.trim().slice(0, 200),
+                isLabeledPlanned: PLANNED_LABEL_PATTERN.test(combined),
+            });
+        }
+    }
+    return refs;
+}

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

@@ -0,0 +1,47 @@
+import path from "node:path";
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 4 — shared file-path pattern helpers.
+//
+// Small, deterministic path helpers reused by the Batch 4 candidate-based
+// detectors (duplicate implementation, dead code, architecture drift).
+// Deliberately forward-slash only -- inventory relativePath values are
+// already forward-slash normalized by projectInventory.ts.
+// ---------------------------------------------------------------------------
+// Returns the first path segment (e.g. "src/audits/foo.ts" -> "src") or null
+// for a root-level file with no directory segment.
+export function firstPathSegment(relativePath) {
+    const idx = relativePath.indexOf("/");
+    return idx === -1 ? null : relativePath.slice(0, idx);
+}
+// Returns the first two path segments joined (e.g. "src/audits/foo.ts" ->
+// "src/audits"), or the single segment if there is no second one.
+export function firstTwoPathSegments(relativePath) {
+    const parts = relativePath.split("/");
+    return parts.length <= 2 ? (parts[0] ?? relativePath) : `${parts[0]}/${parts[1]}`;
+}
+export function baseNameNoExt(relativePath) {
+    const basename = path.basename(relativePath);
+    const ext = path.extname(basename);
+    return ext ? basename.slice(0, -ext.length) : basename;
+}
+// Common, generic infra-ish basenames that are expected to repeat across
+// unrelated directories legitimately (barrels, shared type files, etc.) --
+// excluded from the "same basename across unrelated roots" duplicate-
+// candidate heuristic to keep false positives near zero.
+export const GENERIC_INFRA_BASENAMES = new Set([
+    "index",
+    "types",
+    "type",
+    "config",
+    "utils",
+    "util",
+    "helpers",
+    "helper",
+    "constants",
+    "constant",
+    "setup",
+    "fixtures",
+    "fixture",
+    "errors",
+    "error",
+]);

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

@@ -0,0 +1,38 @@
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 3 — shared code-rot issue construction helpers.
+//
+// Issue ids are content-addressed (detectorId + a stable, relative-path-only
+// cue) rather than counter-based, so the same underlying problem always
+// produces the same id across runs -- this is what makes de-duplication and
+// "stable issue ids" (Batch 3 spec 3.8) trivial: two candidate issues with
+// the same id are the same issue.
+// ---------------------------------------------------------------------------
+// Builds a deterministic id from a detector id and one or more relative-path
+// or short-string cues. Never embeds an absolute path -- callers must pass
+// already-relative paths (e.g. from InventoryFileEntry.relativePath).
+export function makeIssueId(detectorId, ...cues) {
+    const sanitizedCues = cues.map((cue) => cue.replace(/\\/g, "/"));
+    return [detectorId, ...sanitizedCues].join(":");
+}
+export function makeCodeRotIssue(input) {
+    const { idCues, evidence, affectedFiles, ...rest } = input;
+    return {
+        ...rest,
+        id: makeIssueId(rest.detectorId, ...idCues),
+        evidence: evidence ?? [],
+        affectedFiles: affectedFiles ?? [],
+    };
+}
+// Deduplicates a list of already-built issues by id, keeping the first
+// occurrence and preserving overall array order (stable de-duplication).
+export function deduplicateIssuesById(issues) {
+    const seen = new Set();
+    const result = [];
+    for (const issue of issues) {
+        if (seen.has(issue.id))
+            continue;
+        seen.add(issue.id);
+        result.push(issue);
+    }
+    return result;
+}

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

@@ -0,0 +1,12 @@
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 3 (moved in Batch 6) — shared line-splitting helper.
+//
+// The canonical implementation now lives in src/audits/core/textLines.ts
+// (core is lower-level than codeRot, and src/audits/core/sourceOfTruth.ts
+// needed the same helper -- see that file's header comment). This module is
+// kept as a transparent re-export so every existing codeRot detector/util
+// that imports `splitLines` from "../utils/textLines.js" (or
+// "./textLines.js") keeps working unchanged -- named-export re-exports are
+// transparent to importers, there is no behavior difference.
+// ---------------------------------------------------------------------------
+export { splitLines } from "../../core/textLines.js";