@promptci/core 0.0.1

package/dist/detectors.js

@@ -0,0 +1,160 @@
+import { detectAgentPractices } from './agent-practices.js';
+import { detectCanonicalOwner } from './canonical-owner.js';
+import { detectCiAlignment } from './ci-alignment.js';
+import { detectProductBoundary } from './product-boundary.js';
+import { detectCompetingTechConflicts, detectConflicts, detectVersionConflicts } from './conflicts.js';
+import { detectCommandValidity } from './command-validity.js';
+import { detectContextBloat } from './context-bloat.js';
+import { detectContextCost } from './context-cost.js';
+import { detectDeadReferences } from './dead-references.js';
+import { detectDuplicates, detectDuplicateHeadings } from './duplicates.js';
+import { detectManifestConsistency } from './manifest-consistency.js';
+import { detectMissingContext } from './missing-context.js';
+import { detectStaleInstructions } from './stale-instructions.js';
+import { detectVagueGuidance } from './vague-guidance.js';
+import { detectSecurityPack } from './security-pack.js';
+import { runFrameworkPacks } from './framework-packs.js';
+import { detectPromptCacheFriendliness } from './prompt-cache.js';
+import { detectCheapModelRouting } from './cheap-model-routing.js';
+import { detectOutputVerbosity } from './output-verbosity.js';
+import { detectMcpTooling } from './mcp-detector.js';
+import { detectCliOutputFilter } from './cli-output-filter.js';
+import { detectNativeToolPreference } from './native-tool-preference.js';
+export const DETECTORS = [
+    {
+        id: 'duplicates',
+        group: 'scan',
+        run: (context) => detectDuplicates(context.files),
+    },
+    {
+        id: 'duplicate-headings',
+        group: 'scan',
+        run: (context) => detectDuplicateHeadings(context.files),
+    },
+    {
+        id: 'conflicts',
+        group: 'scan',
+        run: (context) => detectConflicts(context.files),
+    },
+    {
+        id: 'version-conflicts',
+        group: 'scan',
+        run: (context) => detectVersionConflicts(context.files),
+    },
+    {
+        id: 'competing-tech-conflicts',
+        group: 'scan',
+        run: (context) => detectCompetingTechConflicts(context.files),
+    },
+    {
+        id: 'context-bloat',
+        group: 'scan',
+        run: (context) => detectContextBloat(context.files, {
+            totalWarning: context.contextBudget,
+            totalHigh: context.contextBudget ? context.contextBudget * 2 : undefined,
+            fileWarning: context.fileContextBudget,
+            fileHigh: context.fileContextBudget ? context.fileContextBudget * 2.5 : undefined,
+        }),
+    },
+    {
+        id: 'stale-instructions',
+        group: 'scan',
+        run: (context) => detectStaleInstructions(context.files),
+    },
+    {
+        id: 'command-validity',
+        group: 'scan',
+        run: (context) => detectCommandValidity(context),
+    },
+    {
+        id: 'missing-context',
+        group: 'scan',
+        run: (context) => detectMissingContext(context.files, context.projectType),
+    },
+    {
+        id: 'manifest-consistency',
+        group: 'scan',
+        run: (context) => detectManifestConsistency(context),
+    },
+    {
+        id: 'vague-guidance',
+        group: 'scan',
+        run: (context) => detectVagueGuidance(context.files),
+    },
+    {
+        id: 'dead-references',
+        group: 'scan',
+        run: (context) => detectDeadReferences(context.files, context.repoRoot),
+    },
+    {
+        id: 'agent-practices',
+        group: 'scan',
+        run: (context) => detectAgentPractices(context.files),
+    },
+    {
+        id: 'canonical-owner',
+        group: 'scan',
+        run: (context) => detectCanonicalOwner(context.files),
+    },
+    {
+        id: 'ci-alignment',
+        group: 'scan',
+        run: (context) => detectCiAlignment(context),
+    },
+    {
+        id: 'product-boundary',
+        group: 'scan',
+        run: (context) => detectProductBoundary(context),
+    },
+    {
+        id: 'security-pack',
+        group: 'scan',
+        run: (context) => detectSecurityPack(context),
+    },
+    {
+        id: 'framework-packs',
+        group: 'scan',
+        run: (context) => runFrameworkPacks(context),
+    },
+    {
+        id: 'prompt-cache-friendliness',
+        group: 'scan',
+        run: (context) => detectPromptCacheFriendliness(context.files),
+    },
+    {
+        id: 'cheap-model-routing',
+        group: 'scan',
+        run: (context) => detectCheapModelRouting(context),
+    },
+    {
+        id: 'output-verbosity',
+        group: 'scan',
+        run: (context) => detectOutputVerbosity(context.files),
+    },
+    {
+        id: 'mcp-tooling',
+        group: 'scan',
+        run: (context) => detectMcpTooling(context),
+    },
+    {
+        id: 'cli-output-filter',
+        group: 'scan',
+        run: (context) => detectCliOutputFilter(context),
+    },
+    {
+        id: 'native-tool-preference',
+        group: 'scan',
+        run: (context) => detectNativeToolPreference(context.files),
+    },
+    {
+        id: 'context-cost',
+        group: 'context',
+        run: detectContextCost,
+    },
+];
+export function runDetectors(context, group) {
+    return DETECTORS
+        .filter((detector) => detector.group === group)
+        .flatMap((detector) => detector.run(context));
+}
+//# sourceMappingURL=detectors.js.map

package/dist/detectors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detectors.js","sourceRoot":"","sources":["../src/detectors.ts"],"names":[],"mappings":"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"}

package/dist/duplicates.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Duplicate section detector for PromptCI.
+ *
+ * Compares sections across all instruction files and flags groups that are
+ * exact matches or near-duplicates (Jaccard ≥ 0.8).
+ *
+ * When the same section appears in N files, ONE issue is emitted listing
+ * all N files — not N*(N-1)/2 pairwise issues.
+ *
+ * Wording is intentionally cautious — all findings are heuristic.
+ */
+import type { InstructionFile, PromptCiIssue } from './types.js';
+/** Normalise text for comparison: lowercase, collapse whitespace, strip markdown syntax. */
+export declare function normalizeSection(text: string): string;
+/**
+ * Detect duplicate or near-duplicate sections across all instruction files.
+ *
+ * Groups all N-way duplicates into a single issue instead of N*(N-1)/2 pairs.
+ *
+ * - Exact normalised match → severity "high", confidence 0.95
+ * - Jaccard ≥ 0.80         → severity "warning", confidence 0.75
+ */
+export declare function detectDuplicates(files: InstructionFile[]): PromptCiIssue[];
+/**
+ * Detect when the same section heading appears more than once in a single
+ * instruction file. This is almost always a structural mistake — accidental
+ * copy/paste, merged conflicts, or two incremental additions that were never
+ * consolidated.
+ *
+ * Unlike the Jaccard-based detector above, this fires on heading identity alone
+ * (case-insensitive, markdown stripped) regardless of content similarity.
+ *
+ * Severity: warning, confidence 0.85.
+ */
+export declare function detectDuplicateHeadings(files: InstructionFile[]): PromptCiIssue[];
+//# sourceMappingURL=duplicates.d.ts.map

package/dist/duplicates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duplicates.d.ts","sourceRoot":"","sources":["../src/duplicates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAsB,aAAa,EAAE,MAAM,YAAY,CAAC;AAuDrF,4FAA4F;AAC5F,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQrD;AAwED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,aAAa,EAAE,CA8L1E;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,aAAa,EAAE,CAsHjF"}

package/dist/duplicates.js

@@ -0,0 +1,436 @@
+/**
+ * Duplicate section detector for PromptCI.
+ *
+ * Compares sections across all instruction files and flags groups that are
+ * exact matches or near-duplicates (Jaccard ≥ 0.8).
+ *
+ * When the same section appears in N files, ONE issue is emitted listing
+ * all N files — not N*(N-1)/2 pairwise issues.
+ *
+ * Wording is intentionally cautious — all findings are heuristic.
+ */
+import * as crypto from 'node:crypto';
+/**
+ * Cross-file: sections shorter than this (normalised chars) are too noisy to flag.
+ * Within-file: we use a lower bar so short but verbatim-repeated bash blocks are caught.
+ */
+const MIN_SECTION_LENGTH = 150; // cross-file minimum
+const WITHIN_FILE_MIN_SECTION_LENGTH = 80; // BUG-001: within-file exact/near-dups need less content
+const MIN_TOKEN_COUNT = 10; // lowered from 20 — short blocks can have fewer tokens
+/**
+ * Jaccard similarity threshold for near-duplicate detection.
+ * Within the same file a lower threshold is appropriate because a repeated
+ * section (e.g. condensed bullet-list restatement of a prose section) is
+ * almost always an accidental duplicate rather than intentional.
+ *
+ * BUG-003: A second, lower cross-file threshold catches borderline near-duplicates
+ * (e.g. "Getting Started" vs "Environment Setup" with ~60% overlap) at info severity.
+ * These are worth flagging but with lower confidence than clear duplicates.
+ */
+const CROSS_FILE_JACCARD_THRESHOLD = 0.8;
+const CROSS_FILE_JACCARD_THRESHOLD_INFO = 0.60; // BUG-003: info-level borderline duplicates
+const WITHIN_FILE_JACCARD_THRESHOLD = 0.6; // BUG-001
+/**
+ * Generic boilerplate headings that commonly appear in every instruction file
+ * but don't represent actionable duplicate content.
+ * BUG-010: Added summary/description terms so short project-preamble sections
+ * in multiple instruction files are not flagged as duplicates.
+ */
+const BOILERPLATE_HEADINGS = new Set([
+    'introduction',
+    'overview',
+    'notes',
+    'note',
+    'about',
+    'background',
+    'context',
+    'disclaimer',
+    'warning',
+    'important',
+    'readme',
+    // BUG-010 additions
+    'summary',
+    'project summary',
+    'project overview',
+    'project description',
+    'description',
+    'what is this',
+    'table of contents',
+    'contents',
+    'license',
+    'changelog',
+]);
+/** Normalise text for comparison: lowercase, collapse whitespace, strip markdown syntax. */
+export function normalizeSection(text) {
+    return text
+        .toLowerCase()
+        .replace(/^#{1,6}\s+/gm, '')
+        .replace(/^[\s]*[-*+]\s+/gm, '')
+        .replace(/^[\s]*\d+\.\s+/gm, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/** Tokenise text into a Set of lowercase words for Jaccard calculation. */
+function tokenize(text) {
+    const words = text.match(/\b\w+\b/g) ?? [];
+    return new Set(words);
+}
+/** Jaccard similarity between two token sets. Returns 0–1. */
+function jaccardSimilarity(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 1;
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let intersectionSize = 0;
+    for (const token of a) {
+        if (b.has(token))
+            intersectionSize++;
+    }
+    return intersectionSize / (a.size + b.size - intersectionSize);
+}
+/** First 200 chars of a string, trimmed. */
+function snippet(text) {
+    return text.length <= 200 ? text : `${text.slice(0, 200)}…`;
+}
+function isBoilerplateHeading(heading) {
+    if (!heading)
+        return false;
+    const lower = heading.toLowerCase().trim();
+    if (BOILERPLATE_HEADINGS.has(lower))
+        return true;
+    // BUG-010: also match headings that START WITH a boilerplate term (e.g.
+    // "Project Summary / NovaSaaS — Claude Code Instructions" starts with "project summary").
+    for (const term of BOILERPLATE_HEADINGS) {
+        if (lower.startsWith(term))
+            return true;
+    }
+    return false;
+}
+function normalizedHeading(heading) {
+    return heading?.toLowerCase().replace(/\s+/g, ' ').trim() ?? '';
+}
+function isActionableShortExactDuplicate(a, b) {
+    const headingA = normalizedHeading(a.heading);
+    const headingB = normalizedHeading(b.heading);
+    return headingA.length > 0 && headingA === headingB;
+}
+// ── Union-Find ────────────────────────────────────────────────────────────────
+function find(parent, key) {
+    if (!parent.has(key))
+        return key;
+    const root = find(parent, parent.get(key));
+    parent.set(key, root); // path compression
+    return root;
+}
+function union(parent, a, b) {
+    const ra = find(parent, a);
+    const rb = find(parent, b);
+    if (ra !== rb)
+        parent.set(ra, rb);
+}
+// ── ID helpers ────────────────────────────────────────────────────────────────
+/** Deterministic ID for a cluster of section keys. */
+function clusterIssueId(keys) {
+    const sorted = [...keys].sort().join('|');
+    const hash = crypto.createHash('sha1').update(sorted).digest('hex').slice(0, 12);
+    return `duplicate-${hash}`;
+}
+// ── Detector ─────────────────────────────────────────────────────────────────
+/**
+ * Detect duplicate or near-duplicate sections across all instruction files.
+ *
+ * Groups all N-way duplicates into a single issue instead of N*(N-1)/2 pairs.
+ *
+ * - Exact normalised match → severity "high", confidence 0.95
+ * - Jaccard ≥ 0.80         → severity "warning", confidence 0.75
+ */
+export function detectDuplicates(files) {
+    // Flatten eligible sections.
+    // Use the lower within-file threshold here; the cross-file threshold is
+    // enforced per-pair in the comparison loop below.
+    const eligible = [];
+    for (const file of files) {
+        for (const section of file.sections) {
+            const norm = normalizeSection(section.text);
+            if (norm.length < WITHIN_FILE_MIN_SECTION_LENGTH)
+                continue; // BUG-001: lower global floor
+            if (tokenize(norm).size < MIN_TOKEN_COUNT)
+                continue;
+            eligible.push({ ...section, normalizedText: norm });
+        }
+    }
+    // Union-Find parent map and per-section metadata
+    const parent = new Map();
+    // sectionByKey: key → section
+    const sectionByKey = new Map();
+    /**
+     * DU1: every matching pair's severity/confidence, recorded WITHOUT trying to
+     * attribute it to a cluster root yet. Union-find roots can change after a
+     * pair is processed — e.g. A==B (root becomes keyB) unions with A~C later,
+     * which re-roots the WHOLE {A,B} cluster onto keyC. The old code recorded
+     * severity keyed by "the root at the moment this pair was unioned"
+     * (`clusterSeverity.set(find(parent, keyA), severity)`), so a later
+     * re-rooting orphaned that entry — the final lookup by the NEW root missed
+     * it entirely and silently fell back to the pair processed last, even if
+     * an earlier pair in the same cluster had a stronger severity.
+     * Deferring root attribution to a second pass (after ALL unions are done,
+     * see below) makes this immune to re-rooting.
+     */
+    const edges = [];
+    for (let i = 0; i < eligible.length; i++) {
+        for (let j = i + 1; j < eligible.length; j++) {
+            const a = eligible[i];
+            const b = eligible[j];
+            if (a.filePath === b.filePath && a.startLine === b.startLine)
+                continue;
+            const keyA = `${a.filePath}:${a.startLine}`;
+            const keyB = `${b.filePath}:${b.startLine}`;
+            const normA = a.normalizedText;
+            const normB = b.normalizedText;
+            let severity = null;
+            let confidence = 0;
+            // BUG-010: Apply boilerplate heading filter to ALL comparisons, including exact
+            // matches. "Project Summary" and similar sections are intentionally duplicated
+            // across instruction files and should never be flagged.
+            if (isBoilerplateHeading(a.heading) || isBoilerplateHeading(b.heading))
+                continue;
+            const sameFile = a.filePath === b.filePath;
+            if (normA === normB) {
+                if (!sameFile &&
+                    (normA.length < MIN_SECTION_LENGTH || normB.length < MIN_SECTION_LENGTH) &&
+                    !isActionableShortExactDuplicate(a, b)) {
+                    continue;
+                }
+                severity = 'high';
+                confidence = 0.95;
+            }
+            else {
+                // BUG-001: apply a stricter length floor for cross-file near-duplicate
+                // comparisons so short same-file repeated blocks are caught while
+                // cross-file noise is kept low. Short exact duplicates are handled
+                // above only when their matching headings make them actionable.
+                if (!sameFile && (normA.length < MIN_SECTION_LENGTH || normB.length < MIN_SECTION_LENGTH)) {
+                    continue;
+                }
+                // BUG-001: within-file near-duplicates use a lower Jaccard threshold because
+                // a repeated (possibly condensed) section in the same file is almost certainly
+                // an accidental duplicate, not intentional.
+                const jaccardThreshold = sameFile
+                    ? WITHIN_FILE_JACCARD_THRESHOLD
+                    : CROSS_FILE_JACCARD_THRESHOLD;
+                const sim = jaccardSimilarity(tokenize(normA), tokenize(normB));
+                if (sim >= jaccardThreshold) {
+                    severity = 'warning';
+                    confidence = sameFile ? 0.8 : 0.75;
+                }
+                else if (!sameFile && sim >= CROSS_FILE_JACCARD_THRESHOLD_INFO) {
+                    // BUG-003: Borderline near-duplicate — same topic, moderate text overlap (65–79%).
+                    // Flag at info severity with lower confidence rather than silently ignoring.
+                    severity = 'info';
+                    confidence = 0.5;
+                }
+            }
+            if (severity === null)
+                continue;
+            sectionByKey.set(keyA, a);
+            sectionByKey.set(keyB, b);
+            union(parent, keyA, keyB);
+            edges.push({ keyA, keyB, severity, confidence });
+        }
+    }
+    // Group section keys by cluster root — all unions are complete by this
+    // point, so every `find()` call here returns the TRUE final root.
+    const clusters = new Map();
+    for (const key of sectionByKey.keys()) {
+        const root = find(parent, key);
+        if (!clusters.has(root))
+            clusters.set(root, []);
+        clusters.get(root).push(key);
+    }
+    // DU1: attribute each recorded edge's severity to its FINAL root (re-computed
+    // now, after every union has already happened) and keep the highest-ranked
+    // one per cluster. This is what makes the fix immune to re-rooting — an
+    // edge processed early (e.g. the exact-duplicate A==B pair) is looked up
+    // under the SAME final root as a later edge that merged its cluster into a
+    // bigger one (e.g. A~C), so the strongest severity in the whole cluster
+    // always wins regardless of processing order.
+    const SEVERITY_RANK = {
+        info: 0, warning: 1, high: 2, critical: 3,
+    };
+    const clusterSeverity = new Map();
+    const clusterConfidence = new Map();
+    for (const edge of edges) {
+        const root = find(parent, edge.keyA); // same final root as edge.keyB
+        const prev = clusterSeverity.get(root);
+        if (!prev || SEVERITY_RANK[edge.severity] > SEVERITY_RANK[prev]) {
+            clusterSeverity.set(root, edge.severity);
+            clusterConfidence.set(root, edge.confidence);
+        }
+    }
+    // Emit one issue per cluster
+    const issues = [];
+    for (const [root, keys] of clusters) {
+        if (keys.length < 2)
+            continue;
+        const sections = keys.map((k) => sectionByKey.get(k));
+        const severity = clusterSeverity.get(root) ?? 'warning';
+        const confidence = clusterConfidence.get(root) ?? 0.75;
+        // Deduplicate file paths while preserving order
+        const filePaths = [...new Set(sections.map((s) => s.filePath))];
+        // Build a concise heading label
+        const uniqueHeadings = [...new Set(sections.map((s) => s.heading ?? '(untitled)'))];
+        const headingLabel = uniqueHeadings.length === 1
+            ? uniqueHeadings[0]
+            : uniqueHeadings.slice(0, 2).join(' / ');
+        const fileCount = filePaths.length;
+        const title = fileCount > 2
+            ? `Possible duplicate: ${headingLabel} (${fileCount} files)`
+            : `Possible duplicate: ${headingLabel}`;
+        const duplicateTokens = sections.slice(1).reduce((sum, s) => sum + Math.round(s.text.length / 4), 0);
+        const summary = fileCount > 2
+            ? `This section appears highly similar in ${fileCount} files. Consider consolidating into one canonical location.`
+            : 'These sections appear highly similar. Consider consolidating them into one canonical location.';
+        issues.push({
+            id: clusterIssueId(keys),
+            severity,
+            category: 'duplicate',
+            title,
+            summary,
+            filePaths,
+            locations: sections.map((s) => ({
+                filePath: s.filePath,
+                startLine: s.startLine,
+                endLine: s.endLine,
+            })),
+            evidence: [
+                snippet(sections[0].normalizedText),
+                `Duplicated size: ~${duplicateTokens} tokens`,
+            ],
+            recommendation: `Consolidate these sections into one canonical location (e.g. AGENTS.md) and use forwarding pointers to save ~${duplicateTokens} tokens per session. If both are intentional, add a comment clarifying the distinction.`,
+            confidence,
+        });
+    }
+    return issues;
+}
+// ── BUG-004: Same-heading duplicate within a single file ─────────────────────
+/**
+ * Detect when the same section heading appears more than once in a single
+ * instruction file. This is almost always a structural mistake — accidental
+ * copy/paste, merged conflicts, or two incremental additions that were never
+ * consolidated.
+ *
+ * Unlike the Jaccard-based detector above, this fires on heading identity alone
+ * (case-insensitive, markdown stripped) regardless of content similarity.
+ *
+ * Severity: warning, confidence 0.85.
+ */
+export function detectDuplicateHeadings(files) {
+    const issues = [];
+    for (const file of files) {
+        // heading (normalised) → sections that carry it
+        const headingMap = new Map();
+        for (const section of file.sections) {
+            if (!section.heading)
+                continue;
+            if (isBoilerplateHeading(section.heading))
+                continue;
+            const key = section.heading
+                .toLowerCase()
+                .replace(/^#+\s*/, '')
+                .replace(/[^\w\s]/g, '')
+                .replace(/\s+/g, ' ')
+                .trim();
+            if (key.length < 3)
+                continue;
+            if (!headingMap.has(key))
+                headingMap.set(key, []);
+            headingMap.get(key).push(section);
+        }
+        for (const [, sections] of headingMap) {
+            if (sections.length < 2)
+                continue;
+            // Don't flag headings that appear at different nesting levels (e.g. "## Troubleshooting"
+            // and "### Troubleshooting" in the same file are in distinct structural contexts).
+            const levels = new Set(sections.map((s) => {
+                const m = /^(#{1,6})\s/.exec(s.text);
+                return m ? m[1].length : 0;
+            }));
+            if (levels.size > 1)
+                continue;
+            const keys = sections.map((s) => `${file.path}:${s.startLine}`);
+            const id = clusterIssueId(keys);
+            const headingLabel = sections[0].heading ?? '(untitled)';
+            issues.push({
+                id,
+                severity: 'warning',
+                category: 'duplicate',
+                title: `Duplicate section heading in one file: "${headingLabel}"`,
+                summary: `The heading "${headingLabel}" appears ${sections.length} times in this file. ` +
+                    `This is likely an accidental duplicate — consider consolidating into one section.`,
+                filePaths: [file.path],
+                locations: sections.map((s) => ({ filePath: file.path, startLine: s.startLine, endLine: s.endLine })),
+                evidence: [`Heading "${headingLabel}" found at lines: ${sections.map((s) => s.startLine).join(', ')}`],
+                recommendation: 'Merge the duplicate sections into one, or rename one if the distinction is intentional.',
+                confidence: 0.85,
+            });
+        }
+        // BUG-006: Also check for headings where one is a prefix of another within
+        // the same file (e.g. "Accessibility" and "Accessibility Standards").
+        // These are almost always overlapping sections that should be merged.
+        const headingKeys = [...headingMap.keys()];
+        const prefixReported = new Set();
+        for (let i = 0; i < headingKeys.length; i++) {
+            for (let j = i + 1; j < headingKeys.length; j++) {
+                const keyA = headingKeys[i];
+                const keyB = headingKeys[j];
+                // One must be a strict prefix of the other, and both must be meaningful
+                const shorter = keyA.length <= keyB.length ? keyA : keyB;
+                const longer = keyA.length <= keyB.length ? keyB : keyA;
+                if (shorter.length < 4)
+                    continue;
+                if (!longer.startsWith(shorter))
+                    continue;
+                // DU2: the longer heading must have at least one extra WORD after the
+                // prefix, not just a mid-word continuation. The old check called
+                // `.trimStart()` before testing anything, which threw away the one
+                // signal it needed — whether a space actually followed the shared
+                // prefix — so "Lint" → "Linting" (extra = "ing", no space) passed the
+                // same `/^\w/` test as "accessibility" → "accessibility standards"
+                // (extra = " standards", a real space). Test the RAW (untrimmed)
+                // remainder for a leading space first; only trim after that check.
+                const extraRaw = longer.slice(shorter.length);
+                if (!/^\s/.test(extraRaw))
+                    continue; // mid-word continuation — skip
+                const extra = extraRaw.trimStart();
+                if (!extra)
+                    continue; // trailing whitespace only, nothing real followed
+                const pairKey = [keyA, keyB].sort().join('|');
+                if (prefixReported.has(pairKey))
+                    continue;
+                prefixReported.add(pairKey);
+                const secA = headingMap.get(keyA);
+                const secB = headingMap.get(keyB);
+                const allSections = [...secA, ...secB].sort((a, b) => a.startLine - b.startLine);
+                const allKeys = allSections.map((s) => `${file.path}:${s.startLine}`);
+                issues.push({
+                    id: clusterIssueId(allKeys),
+                    severity: 'warning',
+                    category: 'duplicate',
+                    title: `Overlapping section headings in one file: "${secA[0].heading}" / "${secB[0].heading}"`,
+                    summary: `These section headings appear to cover the same topic — one is a prefix/subset of the other. ` +
+                        `This is likely an accidental split. Consider merging into one canonical section.`,
+                    filePaths: [file.path],
+                    locations: allSections.map((s) => ({ filePath: file.path, startLine: s.startLine, endLine: s.endLine })),
+                    evidence: [
+                        `"${secA[0].heading}" at line ${secA[0].startLine}`,
+                        `"${secB[0].heading}" at line ${secB[0].startLine}`,
+                    ],
+                    recommendation: 'Consolidate these sections into one. If the distinction is intentional, rename one to make the difference clear.',
+                    confidence: 0.75,
+                });
+            }
+        }
+    }
+    return issues;
+}
+//# sourceMappingURL=duplicates.js.map