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

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

@@ -0,0 +1,350 @@
+import { readBoundedFileText } from "../utils/boundedRead.js";
+import { firstPathSegment, GENERIC_DECLARATION_NAMES, GENERIC_INFRA_BASENAMES, baseNameNoExt } from "../utils/filePatternUtils.js";
+import { deduplicateIssuesById, makeCodeRotIssue } from "../utils/issueFactories.js";
+import { indexSourceFactsByPath } from "../utils/sourceFactsLookup.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(...findDuplicateDeclarationCandidates(ctx));
+        }
+        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]}`;
+}
+// v0.3.1 Batch 4 -- source-facts-aware duplicate-declaration candidate
+// check. Weak/low-confidence signal, same spirit as
+// findDuplicateBasenamesAcrossRoots(): the same exported declaration name
+// and kind (e.g. two exported `class Logger`) appears in 2-4 distinct
+// "source"-role files that a registered analyzer actually parsed. Bounded
+// to declaration kinds that carry real implementation weight
+// (function/class/interface/type/enum) -- "variable"/"constant"/"method"/
+// "unknown" are excluded as too noisy (methods repeat across unrelated
+// classes by convention; module-scope variables/constants repeat even more
+// often). Generic declaration names (run, init, handler, ...) are excluded
+// via GENERIC_DECLARATION_NAMES for the same reason
+// GENERIC_INFRA_BASENAMES excludes generic file basenames above. Requires
+// ctx.sourceFacts -- returns no issues when it is absent (e.g. existing
+// detector unit tests that build a literal AuditDetectorContext without
+// it), so this check is purely additive.
+const NOISY_DECLARATION_KINDS = new Set(["variable", "constant", "method", "unknown"]);
+function findDuplicateDeclarationCandidates(ctx) {
+    if (!ctx.sourceFacts)
+        return [];
+    const index = indexSourceFactsByPath(ctx.sourceFacts);
+    const byKey = new Map();
+    for (const facts of index.values()) {
+        if (facts.role !== "source")
+            continue;
+        if (facts.parseStatus !== "parsed")
+            continue;
+        for (const decl of facts.declarations) {
+            if (!decl.exported)
+                continue;
+            if (NOISY_DECLARATION_KINDS.has(decl.kind))
+                continue;
+            const nameLower = decl.name.toLowerCase();
+            if (GENERIC_DECLARATION_NAMES.has(nameLower))
+                continue;
+            const key = `${decl.kind}:${nameLower}`;
+            const entry = byKey.get(key) ?? { name: decl.name, kind: decl.kind, paths: new Set() };
+            entry.paths.add(facts.relativePath);
+            byKey.set(key, entry);
+        }
+    }
+    const issues = [];
+    for (const entry of byKey.values()) {
+        if (entry.paths.size < 2 || entry.paths.size > 4)
+            continue;
+        const sortedPaths = [...entry.paths].sort((a, b) => a.localeCompare(b));
+        issues.push(makeCodeRotIssue({
+            auditType: "code-rot",
+            detectorId: DETECTOR_ID,
+            idCues: ["duplicate-declaration-candidate", entry.kind, entry.name.toLowerCase(), ...sortedPaths],
+            title: `Exported ${entry.kind} "${entry.name}" is declared in ${sortedPaths.length} unrelated files (weak signal)`,
+            description: `An exported ${entry.kind} named "${entry.name}" is declared in: ${sortedPaths.join(", ")}. This is a source-facts-derived candidate signal (same declaration name and kind, not a semantic-equivalence check) for parallel implementations -- inspect manually before consolidating.`,
+            severity: "info",
+            confidence: "low",
+            falsePositiveRisk: "high",
+            category: "duplicate-implementation-candidate",
+            recommendedAction: "Manually confirm whether these declarations 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: "reference",
+                    message: `Source facts: an exported ${entry.kind} named "${entry.name}" was parsed in ${sortedPaths.length} distinct files.`,
+                    excerpt: sortedPaths.join(", "),
+                    source: DETECTOR_ID,
+                    confidence: "low",
+                },
+            ],
+            affectedFiles: sortedPaths,
+        }));
+    }
+    return issues;
+}
+// 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;
+}

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

@@ -0,0 +1,325 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CURRENT_PACKAGE_VERSION_PATTERNS, PUBLISHED_OR_RELEASED_CLAIM_PATTERN, isHedgedNearby } from "../utils/docClaimPatterns.js";
+import { deduplicateIssuesById, makeCodeRotIssue } from "../utils/issueFactories.js";
+import { splitLines } from "../utils/textLines.js";
+// ---------------------------------------------------------------------------
+// v0.3.0 Batch 3 — package/release rot detector.
+//
+// Local-only: never runs npm pack, npm view, or any network/registry call
+// (Batch 3 scope). Owns the publish/release-claim check and the doc-vs-
+// package version-mismatch check (both also listed under
+// docsCodeMismatchDetector.ts's Batch 3 spec section, but implemented here
+// only, to avoid the same underlying signal producing two issues from two
+// detectors -- see that file's header comment for the same note from the
+// other side).
+// ---------------------------------------------------------------------------
+const DETECTOR_ID = "package-release-rot";
+const MAX_DOC_READ_BYTES = 200_000;
+// Paths that should never appear in package.json's "files" allowlist --
+// each is either generated content or private/local state, per this
+// project's own .gitignore/security-package-content conventions.
+const RISKY_FILES_ENTRY_PATTERN = /^(reports|lab-output|\.my-dev-kit|\.env)/i;
+export const PACKAGE_RELEASE_ROT_DETECTOR = {
+    id: DETECTOR_ID,
+    auditType: "code-rot",
+    title: "Package/release rot",
+    description: "Detects package.json/package-lock.json version or name drift, a missing CHANGELOG section for the current version, stale doc version mentions, unhedged publish/release claims, risky package.json files entries, and self-referencing script commands.",
+    supportedIncludeAreas: ["package", "docs", "cli"],
+    run: (ctx) => {
+        const issues = [];
+        const pkg = ctx.sourceOfTruth.package;
+        const lockfile = ctx.sourceOfTruth.lockfile;
+        if (ctx.config.include.includes("package") && pkg) {
+            if (lockfile.present && lockfile.packageManagerConsistent === false) {
+                if (lockfile.rootVersion !== null && lockfile.rootVersion !== pkg.version) {
+                    issues.push(makeVersionMismatchIssue(pkg.version, lockfile.rootVersion));
+                }
+                else if (lockfile.rootName !== null && lockfile.rootName !== pkg.name) {
+                    issues.push(makeNameMismatchIssue(pkg.name, lockfile.rootName));
+                }
+            }
+            if (pkg.files) {
+                for (const entry of pkg.files) {
+                    if (RISKY_FILES_ENTRY_PATTERN.test(entry)) {
+                        issues.push(makeRiskyFilesEntryIssue(entry));
+                    }
+                }
+            }
+            for (const [scriptName, command] of Object.entries(pkg.scripts)) {
+                for (const match of command.matchAll(/npm run ([\w:.-]+)/g)) {
+                    const referenced = match[1];
+                    if (referenced !== scriptName && !(referenced in pkg.scripts)) {
+                        issues.push(makeSelfReferenceIssue(scriptName, referenced));
+                    }
+                }
+            }
+        }
+        if (ctx.config.include.includes("docs") && pkg) {
+            const changelogFile = ctx.inventory.docsFiles.find((f) => path.basename(f.relativePath).toLowerCase() === "changelog.md");
+            if (changelogFile) {
+                const content = readBoundedText(ctx.target.rootPath, changelogFile.relativePath, changelogFile.sizeBytes);
+                if (content !== null && pkg.version) {
+                    const hasCurrentVersionSection = new RegExp(`^##\\s*\\[${escapeRegExp(pkg.version)}\\]`, "m").test(content);
+                    if (!hasCurrentVersionSection) {
+                        issues.push(makeMissingChangelogSectionIssue(changelogFile.relativePath, pkg.version));
+                    }
+                }
+            }
+            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];
+                    if (pkg.version) {
+                        for (const pattern of CURRENT_PACKAGE_VERSION_PATTERNS) {
+                            const match = line.match(pattern);
+                            if (match && match[1] !== pkg.version) {
+                                issues.push(makeStaleDocVersionIssue(docFile.relativePath, i + 1, line, match[1], pkg.version));
+                            }
+                        }
+                    }
+                    if (PUBLISHED_OR_RELEASED_CLAIM_PATTERN.test(line)) {
+                        const windowStart = Math.max(0, i - 1);
+                        const window = lines.slice(windowStart, i + 1).join(" ");
+                        if (!isHedgedNearby(window)) {
+                            issues.push(makeUnsupportedPublishClaimIssue(docFile.relativePath, i + 1, line));
+                        }
+                    }
+                }
+            }
+        }
+        return deduplicateIssuesById(issues);
+    },
+};
+function makeVersionMismatchIssue(packageVersion, lockfileVersion) {
+    return makeCodeRotIssue({
+        auditType: "code-rot",
+        detectorId: DETECTOR_ID,
+        idCues: ["version-mismatch", packageVersion ?? "unknown", lockfileVersion],
+        title: "package.json and package-lock.json version mismatch",
+        description: `package.json version is "${packageVersion}" but package-lock.json's root version is "${lockfileVersion}".`,
+        severity: "blocker",
+        confidence: "high",
+        falsePositiveRisk: "low",
+        category: "package-release-rot",
+        recommendedAction: "Run npm install to regenerate package-lock.json so both versions match.",
+        suggestedFixStrategy: "npm install (lockfile-only update is sufficient if dependencies did not change).",
+        validationCommands: ["npm install --package-lock-only"],
+        releaseBlocking: true,
+        implementationBlocking: false,
+        autoFixEligible: false,
+        evidence: [
+            {
+                kind: "file",
+                message: "Version field mismatch between package.json and package-lock.json.",
+                filePath: "package-lock.json",
+                expected: packageVersion ?? undefined,
+                observed: lockfileVersion,
+                source: DETECTOR_ID,
+                confidence: "high",
+            },
+        ],
+        affectedFiles: ["package.json", "package-lock.json"],
+    });
+}
+function makeNameMismatchIssue(packageName, lockfileName) {
+    return makeCodeRotIssue({
+        auditType: "code-rot",
+        detectorId: DETECTOR_ID,
+        idCues: ["name-mismatch", packageName ?? "unknown", lockfileName],
+        title: "package.json and package-lock.json name mismatch",
+        description: `package.json name is "${packageName}" but package-lock.json's root name is "${lockfileName}".`,
+        severity: "high",
+        confidence: "high",
+        falsePositiveRisk: "low",
+        category: "package-release-rot",
+        recommendedAction: "Run npm install to regenerate package-lock.json so both names match.",
+        suggestedFixStrategy: "npm install (lockfile-only update is sufficient if dependencies did not change).",
+        validationCommands: ["npm install --package-lock-only"],
+        releaseBlocking: false,
+        implementationBlocking: false,
+        autoFixEligible: false,
+        evidence: [
+            {
+                kind: "file",
+                message: "Name field mismatch between package.json and package-lock.json.",
+                filePath: "package-lock.json",
+                expected: packageName ?? undefined,
+                observed: lockfileName,
+                source: DETECTOR_ID,
+                confidence: "high",
+            },
+        ],
+        affectedFiles: ["package.json", "package-lock.json"],
+    });
+}
+function makeRiskyFilesEntryIssue(entry) {
+    return makeCodeRotIssue({
+        auditType: "code-rot",
+        detectorId: DETECTOR_ID,
+        idCues: ["risky-files-entry", entry],
+        title: `package.json "files" field includes a risky-looking path: "${entry}"`,
+        description: `package.json's "files" allowlist includes "${entry}", which looks like generated or private content rather than intentional package content.`,
+        severity: "medium",
+        confidence: "medium",
+        falsePositiveRisk: "low",
+        category: "package-release-rot",
+        recommendedAction: `Remove "${entry}" from package.json's "files" field unless it is intentionally published.`,
+        suggestedFixStrategy: `Edit the "files" array in package.json to drop "${entry}".`,
+        validationCommands: ["npm pack --dry-run"],
+        releaseBlocking: false,
+        implementationBlocking: false,
+        autoFixEligible: false,
+        evidence: [
+            {
+                kind: "file",
+                message: `"files" entry matches a known risky pattern.`,
+                filePath: "package.json",
+                excerpt: entry,
+                source: DETECTOR_ID,
+                confidence: "medium",
+            },
+        ],
+        affectedFiles: ["package.json"],
+    });
+}
+function makeSelfReferenceIssue(scriptName, referenced) {
+    return makeCodeRotIssue({
+        auditType: "code-rot",
+        detectorId: DETECTOR_ID,
+        idCues: ["script-references-missing-script", scriptName, referenced],
+        title: `Script "${scriptName}" references undefined script "${referenced}"`,
+        description: `package.json script "${scriptName}" runs "npm run ${referenced}", but "${referenced}" is not itself a defined script.`,
+        severity: "high",
+        confidence: "high",
+        falsePositiveRisk: "low",
+        category: "package-release-rot",
+        recommendedAction: `Add the missing "${referenced}" script, or fix "${scriptName}" to reference an existing script.`,
+        suggestedFixStrategy: `Edit package.json's "${scriptName}" script.`,
+        validationCommands: [`npm run ${scriptName}`],
+        releaseBlocking: false,
+        implementationBlocking: false,
+        autoFixEligible: false,
+        evidence: [
+            {
+                kind: "file",
+                message: `Script command references a script name that does not exist.`,
+                filePath: "package.json",
+                excerpt: `"${scriptName}": "... npm run ${referenced} ..."`,
+                source: DETECTOR_ID,
+                confidence: "high",
+            },
+        ],
+        affectedFiles: ["package.json"],
+    });
+}
+function makeMissingChangelogSectionIssue(relativePath, currentVersion) {
+    return makeCodeRotIssue({
+        auditType: "code-rot",
+        detectorId: DETECTOR_ID,
+        idCues: [relativePath, "missing-current-version-section", currentVersion],
+        title: `${relativePath} has no section for the current package version (${currentVersion})`,
+        description: `package.json version is "${currentVersion}", but ${relativePath} has no "## [${currentVersion}]" heading.`,
+        severity: "high",
+        confidence: "high",
+        falsePositiveRisk: "low",
+        category: "package-release-rot",
+        recommendedAction: `Add a "## [${currentVersion}]" section to ${relativePath} describing this release.`,
+        suggestedFixStrategy: `Convert the top Unreleased/placeholder section in ${relativePath} into a "## [${currentVersion}]" entry.`,
+        validationCommands: ["npm run audit -- --types code-rot --include package,docs"],
+        releaseBlocking: false,
+        implementationBlocking: false,
+        autoFixEligible: false,
+        evidence: [
+            {
+                kind: "file",
+                message: `No "## [${currentVersion}]" heading found.`,
+                filePath: relativePath,
+                expected: `## [${currentVersion}]`,
+                source: DETECTOR_ID,
+                confidence: "high",
+            },
+        ],
+        affectedFiles: [relativePath],
+    });
+}
+function makeStaleDocVersionIssue(relativePath, lineNumber, excerpt, docVersion, currentVersion) {
+    return makeCodeRotIssue({
+        auditType: "code-rot",
+        detectorId: DETECTOR_ID,
+        idCues: [relativePath, "stale-doc-version", docVersion],
+        title: `${relativePath} states an outdated current version (${docVersion})`,
+        description: `${relativePath}:${lineNumber} describes "${docVersion}" as the current package version, but package.json says "${currentVersion}".`,
+        severity: "medium",
+        confidence: "medium",
+        falsePositiveRisk: "medium",
+        category: "package-release-rot",
+        recommendedAction: `Update ${relativePath} to reference the current version (${currentVersion}).`,
+        suggestedFixStrategy: `Replace "${docVersion}" with "${currentVersion}" in ${relativePath}.`,
+        validationCommands: ["npm run audit -- --types code-rot --include package,docs"],
+        releaseBlocking: false,
+        implementationBlocking: false,
+        autoFixEligible: false,
+        evidence: [
+            {
+                kind: "file",
+                message: `Doc-stated current version does not match package.json.`,
+                filePath: relativePath,
+                line: lineNumber,
+                excerpt: excerpt.trim().slice(0, 200),
+                expected: currentVersion,
+                observed: docVersion,
+                source: DETECTOR_ID,
+                confidence: "medium",
+            },
+        ],
+        affectedFiles: [relativePath],
+    });
+}
+function makeUnsupportedPublishClaimIssue(relativePath, lineNumber, excerpt) {
+    return makeCodeRotIssue({
+        auditType: "code-rot",
+        detectorId: DETECTOR_ID,
+        idCues: [relativePath, "unsupported-publish-claim", String(lineNumber)],
+        title: `${relativePath} claims publication/release/tag without local support`,
+        description: `${relativePath}:${lineNumber} contains an unhedged publish/release/tag claim. This is a local-only tool with no npm registry or GitHub API access, so this claim cannot be verified and is flagged for manual confirmation.`,
+        severity: "blocker",
+        confidence: "medium",
+        falsePositiveRisk: "medium",
+        category: "package-release-rot",
+        recommendedAction: "Confirm whether publication has actually happened; if not, correct the claim to say it has not yet been published.",
+        suggestedFixStrategy: `Rephrase the claim in ${relativePath} to accurately reflect current release state.`,
+        validationCommands: ["npm run audit -- --types code-rot --include package,docs"],
+        releaseBlocking: true,
+        implementationBlocking: false,
+        autoFixEligible: false,
+        evidence: [
+            {
+                kind: "file",
+                message: "Matched an unhedged publish/release/tag claim pattern with no nearby hedge word.",
+                filePath: relativePath,
+                line: lineNumber,
+                excerpt: excerpt.trim().slice(0, 200),
+                source: DETECTOR_ID,
+                confidence: "medium",
+            },
+        ],
+        affectedFiles: [relativePath],
+    });
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+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;
+    }
+}