@promptci/core 0.1.0 → 0.2.1

package/dist/dead-references.js

@@ -7,16 +7,32 @@
  *   - Reference-style links: [text][ref] with a `[ref]: path` definition
  *   - @-file refs:     @AGENTS.md  |  @docs/guide.md
  *
+ *   - Directory / extension-less paths (pcic-2b6.8): links like
+ *     [api](./src/api/) and code spans like `apps/admin/` or `src/payments`
+ *
  * External URLs (http/https), anchor-only links (#section), and mailto:
- * are always skipped. Only paths with a recognisable file extension are
- * checked to avoid false-positiving on badge shields, npm package names, etc.
+ * are always skipped. File paths need a recognisable extension; a directory or
+ * extension-less path in a code span is only checked when its FIRST segment
+ * exists in the repository (so `owner/repo`, `origin/main`, `@scope/pkg` and
+ * paths describing some other project stay silent); one three or more levels
+ * below its first segment also needs its second segment to exist. A bare
+ * filename in a code span (`ci.yml`) resolves against any committed file of
+ * that name in the repository.
+ *
+ * Every lookup stays inside the scan root and matches names with exact case
+ * (pcic-xhzb, see RepoTree): references that leave the root are not checked,
+ * and a directory that cannot be listed leaves its references unchecked and
+ * named in one "check incomplete" warning instead of reported as broken.
  *
  * Findings are heuristic — wording is intentionally cautious.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
-import { fencedBlocks } from './markdown-fences.js';
+import fg from 'fast-glob';
+import { fencedBlocks, scanFencedLines } from './markdown-fences.js';
+import { createGitIgnoreChecker } from './gitignore.js';
+import { isWithinRoot, realPath } from './path-containment.js';
 // ── Patterns ──────────────────────────────────────────────────────────────────
 /** Matches markdown inline links: [label](target) — captures target (may include a title). */
 const MD_LINK_RE = /\[(?:[^\]]*)\]\(([^)]+)\)/g;
@@ -42,6 +58,37 @@ const AT_FILE_RE = /(?<!\w)@((?:\.{1,2}\/)?[\w./\\-]+\.(?:md|ts|js|mjs|cjs|tsx|j
  * after the extension but excluded from the captured path.
  */
 const BACKTICK_PATH_RE = /`([^\s`\n]+\.(?:md|sh|py|ts|js|tsx|jsx|mjs|cjs|json|yml|yaml|toml|cs|go|rs|txt|lock|env|png|jpg|jpeg|gif|svg|webp|pdf))(?::\d+(?::\d+)?)?`/g;
+/**
+ * pcic-2b6.8: code spans holding a directory or extension-less repo path —
+ * `src/payments/`, `apps/admin`, `./src/api/`. Path characters only (Next.js
+ * route segments like `(auth)` and `[id]` included); anything with a space,
+ * colon, `$`, `*`, `~` or `<…>` is a command, URL, variable, glob or
+ * placeholder and never matches. At least two segments are required: a lone
+ * `docs/` or `./scripts` names no location specific enough to call stale.
+ */
+const BACKTICK_DIR_RE = /`((?:\.\/)?[\w@.()[\]-]+(?:\/[\w@.()[\]-]+)+\/?)`/g;
+/**
+ * A line talking about git branches, HTTP routes or URLs: its slash-shaped
+ * code spans (`docs/update-readme`, `api/v1/users`) are names, not paths.
+ */
+const NON_PATH_CONTEXT_RE = /\b(?:branch(?:es)?|checkout|rebase|merge|cherry-pick|route[sd]?|routing|endpoints?|urls?|uris?|http\s+(?:get|post|put|patch|delete))\b/i;
+/**
+ * Conventional git branch prefixes. A span starting with one of these that has
+ * no trailing slash (`docs/update-readme`, `test/flaky-fix`) is more likely a
+ * branch than a directory, so only the explicit directory form (`docs/guides/`)
+ * is checked.
+ */
+const BRANCH_PREFIXES = new Set([
+    'feat', 'feature', 'features', 'fix', 'bugfix', 'hotfix', 'chore', 'docs', 'doc', 'refactor',
+    'test', 'tests', 'ci', 'perf', 'build', 'release', 'releases', 'style', 'wip', 'dependabot',
+]);
+/**
+ * Generated output and dependency directories: never committed, so a path
+ * under one says nothing about the repository's current layout.
+ */
+const OUTPUT_DIRS = new Set([
+    'dist', 'build', 'out', '.next', 'coverage', 'target', 'bin', 'obj', 'node_modules', '.turbo',
+]);
 /**
  * BUG-004: Bullet-list bare file paths in Repository Layout / Project Structure sections.
  * Catches lines like:
@@ -169,6 +216,10 @@ function isPlaceholderRef(ref) {
     // These are pattern descriptions, not real file paths.
     if (/\{[A-Za-z][A-Za-z0-9_-]*\}/.test(ref))
         return true;
+    // pcic-mh72: Brace alternation names several files at once, like a glob:
+    // `translations/{de,en,ru}.json`. It is a pattern, not a single path.
+    if (/\{[^{}/\\]*,[^{}/\\]*\}/.test(ref))
+        return true;
     // BUG-006 (eval): Ellipsis segments ("...") are glob placeholders, not real path components.
     // e.g. "src/test/java/.../unit/" is a structural description, not a literal path.
     if (ref.split('/').includes('...'))
@@ -232,22 +283,44 @@ function isGitignored(ref) {
     const normalised = ref.replace(/\\/g, '/');
     return GITIGNORED_CREDENTIAL_PATTERNS.some((re) => re.test(normalised));
 }
+/**
+ * pcic-2b6.12: Paths rooted in the reader's home or profile directory —
+ * `~/.config/x/settings.json`, `$HOME/.claude/settings.json`,
+ * `%USERPROFILE%\.claude.json`. They live outside the repository by definition,
+ * so their absence from the checkout says nothing about the reference.
+ */
+const HOME_ROOTED_RE = /^(?:~(?:[/\\]|$)|\$\{?(?:HOME|USERPROFILE|XDG_CONFIG_HOME|XDG_DATA_HOME)\}?(?:[/\\]|$)|\$env:(?:HOME|USERPROFILE|APPDATA|LOCALAPPDATA)(?:[/\\]|$)|%(?:USERPROFILE|HOMEPATH|APPDATA|LOCALAPPDATA)%(?:[/\\]|$))/i;
+export function isHomeRooted(ref) {
+    return HOME_ROOTED_RE.test(ref.trim());
+}
 function hasCheckableExtension(ref) {
     const ext = path.extname(ref.split('#')[0] ?? '').toLowerCase();
     return CHECKABLE_EXTENSIONS.has(ext);
 }
+/**
+ * pcic-2b6.8: a markdown link target naming a directory or an extension-less
+ * file (`./src/api/`, `docs/`, `LICENSE`). Site-absolute (`/pricing`) and
+ * scheme-qualified targets, and anything with characters a repo path would not
+ * carry, are left alone.
+ */
+function isExtensionlessPathRef(ref) {
+    if (!ref || /^[a-z][a-z0-9+.-]*:/i.test(ref) || ref.startsWith('/'))
+        return false;
+    if (/[\s*?$%<>{}|"'`~\\]/.test(ref))
+        return false;
+    if (!/[A-Za-z]/.test(ref))
+        return false; // `./`, `../`, `..`
+    // Path-shaped only: a separator or a leading dot (`./x`, `.github`). A bare
+    // word (`[WARNING]: Never …`, `[x](payload)`) is too ambiguous to judge.
+    if (!ref.includes('/') && !ref.startsWith('.'))
+        return false;
+    const last = ref.replace(/\/+$/, '').split('/').pop() ?? '';
+    return ref.endsWith('/') || path.extname(last) === '';
+}
 /** Strip query strings and anchor fragments from a path reference. */
 function stripFragment(ref) {
     return ref.split('#')[0].split('?')[0].trim();
 }
-function fileExists(p) {
-    try {
-        return fs.existsSync(p);
-    }
-    catch {
-        return false;
-    }
-}
 /**
  * BUG-C1: Source-code file extensions. When a path has one of these extensions
  * and its parent directory exists (but the file itself doesn't), the reference
@@ -258,14 +331,16 @@ const SOURCE_CODE_EXTENSIONS = new Set([
     '.py', '.rs', '.sh', '.java', '.kt', '.swift',
 ]);
 /**
- * BUG-002: Compiled/native source extensions that, when encountered as backtick
- * inline spans (NOT markdown links or @-refs) in any instruction file type,
- * should be skipped. These are almost always architecture documentation, not real
- * file references — e.g. `internal/client/errors.go`, `src/components/Button.tsx`,
- * `pkg/registry/`, `PlayerController.cs`.
+ * BUG-002 / pcic-2b6.8: Compiled/native source extensions that, as backtick
+ * inline spans (NOT markdown links or @-refs), are often architecture
+ * documentation — `internal/client/errors.go`, `PlayerController.cs` — or
+ * examples from some other project. They are no longer skipped outright: a
+ * missing one is reported (at reduced confidence) only when its first path
+ * segment exists in this repository, i.e. it names a real part of THIS tree.
  *
  * NOTE: .sh, .py, .js are intentionally excluded — shell/Python/JS scripts are often
- * legitimately referenced by name in instruction files (e.g. `scripts/setup-dev.sh`).
+ * legitimately referenced by name in instruction files (e.g. `scripts/setup-dev.sh`)
+ * and are checked like any other file.
  */
 const BACKTICK_SKIP_SOURCE_EXTENSIONS = new Set([
     '.go', '.rs', '.cs', '.java', '.kt', '.swift',
@@ -278,30 +353,24 @@ const BACKTICK_SKIP_SOURCE_EXTENSIONS = new Set([
  */
 const STALE_SOURCE_REF_RE = /(?:^|[/\\])(?:legacy|old|deprecated|archive|archived)(?:[/\\]|[-_.])/i;
 /**
- * File types for which backtick-enclosed compiled/native source paths should be
- * skipped. All instruction file types are included because architecture
- * descriptions appear in all of them.
+ * File types whose backtick-enclosed compiled/native source paths and
+ * directory paths get the first-segment rule above. All instruction file types
+ * are included because architecture descriptions appear in all of them.
  *
  * BUG-002: Expanded from readme-only to all instruction file types.
- *
- * NOTE: this covers every FileType value, which also means backtick-quoted bare
- * *directory* paths (no extension, e.g. `pkg/registry/`) are always treated as
- * architecture descriptions rather than checked — that is intentional per
- * BUG-002, not an oversight.
  */
 const SKIP_SOURCE_BACKTICK_FILE_TYPES = new Set([
-    'readme', 'claude', 'agents', 'cursor', 'windsurf', 'copilot', 'docs', 'prompt', 'unknown',
+    'readme', 'claude', 'agents', 'cursor', 'windsurf', 'copilot', 'gemini', 'cline', 'persona',
+    'docs', 'prompt', 'unknown',
 ]);
+/**
+ * pcic-mh72: how many missing levels a code-span path may have below a first
+ * segment that is the only part of it present in this repository. Deeper than
+ * this, the first segment alone does not show the path belongs to this tree.
+ */
+const MAX_UNANCHORED_DEPTH = 2;
 /** Minimum confidence to emit a dead-reference issue. Below this the signal is too noisy. */
 const MIN_CONFIDENCE = 0.45;
-function parentDirExists(p) {
-    try {
-        return fs.existsSync(path.dirname(p));
-    }
-    catch {
-        return false;
-    }
-}
 function issueId(normRef) {
     const key = `dead-ref:${normRef}`;
     const hash = crypto.createHash('sha1').update(key).digest('hex').slice(0, 12);
@@ -414,6 +483,26 @@ function extractLayoutTreePaths(content, lineOffsets) {
 function collectRefs(content, opts = {}) {
     const found = [];
     const lineOffsets = buildLineOffsets(content);
+    const fenceLines = scanFencedLines(content);
+    // `handlers[type](payload)` in a code fence or `a[i](b)` in a code span has
+    // the shape of a link without being one. Checkable-extension targets keep
+    // their historical behavior; the extension-less check only reads real prose.
+    const inCode = (index) => {
+        const line = lineForOffset(lineOffsets, index);
+        if (fenceLines[line - 1]?.inFence)
+            return true;
+        const before = content.slice(lineOffsets[line - 1] ?? 0, index);
+        return (before.match(/`/g)?.length ?? 0) % 2 === 1;
+    };
+    const pushLink = (ref, evidence, index) => {
+        if (!ref || isExternalRef(ref))
+            return;
+        const line = lineForOffset(lineOffsets, index);
+        if (hasCheckableExtension(ref))
+            found.push({ ref, evidence, line, kind: 'file' });
+        else if (isExtensionlessPathRef(ref) && !inCode(index))
+            found.push({ ref, evidence, line, kind: 'linkPath' });
+    };
     // Markdown links: [label](target) or [label](target "Title")
     let m;
     const linkRe = new RegExp(MD_LINK_RE.source, MD_LINK_RE.flags);
@@ -421,10 +510,7 @@ function collectRefs(content, opts = {}) {
         if (m.index >= 2 && content[m.index - 2] === '[' && content[m.index - 1] === '!')
             continue;
         const raw = m[1] ?? '';
-        const ref = stripFragment(stripLinkTitle(raw));
-        if (ref && !isExternalRef(ref) && hasCheckableExtension(ref)) {
-            found.push({ ref, evidence: `[...](${raw})`, line: lineForOffset(lineOffsets, m.index) });
-        }
+        pushLink(stripFragment(stripLinkTitle(raw)), `[...](${raw})`, m.index);
     }
     const nestedLinkRe = new RegExp(NESTED_MD_LINK_RE.source, NESTED_MD_LINK_RE.flags);
     while ((m = nestedLinkRe.exec(content)) !== null) {
@@ -432,47 +518,62 @@ function collectRefs(content, opts = {}) {
         if (!labelPart.includes(']('))
             continue;
         const raw = m[1] ?? '';
-        const ref = stripFragment(stripLinkTitle(raw));
-        if (ref && !isExternalRef(ref) && hasCheckableExtension(ref)) {
-            found.push({ ref, evidence: `[...](${raw})`, line: lineForOffset(lineOffsets, m.index) });
-        }
+        pushLink(stripFragment(stripLinkTitle(raw)), `[...](${raw})`, m.index);
     }
     // Reference-style link definitions: [ref]: docs/missing.md "Title"
     const linkDefRe = new RegExp(LINK_REF_DEF_RE.source, LINK_REF_DEF_RE.flags);
     while ((m = linkDefRe.exec(content)) !== null) {
         const raw = m[1] ?? '';
-        const ref = stripFragment(raw);
-        if (ref && !isExternalRef(ref) && hasCheckableExtension(ref)) {
-            found.push({ ref, evidence: m[0].trim(), line: lineForOffset(lineOffsets, m.index) });
-        }
+        // `[^1]: Footnote text` is a footnote, not a link definition.
+        if (/^[ \t]*\[\^/.test(m[0]))
+            continue;
+        pushLink(stripFragment(raw), m[0].trim(), m.index);
     }
     // @-file refs
     const atRe = new RegExp(AT_FILE_RE.source, AT_FILE_RE.flags);
     while ((m = atRe.exec(content)) !== null) {
         const ref = m[1] ?? '';
         if (ref && !isExternalRef(ref)) {
-            found.push({ ref, evidence: `@${ref}`, line: lineForOffset(lineOffsets, m.index) });
+            found.push({ ref, evidence: `@${ref}`, line: lineForOffset(lineOffsets, m.index), kind: 'file' });
         }
     }
     // Backtick file paths: `scripts/setup-dev.sh`, `Assets/Scripts/Foo.cs`
     // No spaces = file path not a command; must have a recognisable extension.
     // Skip glob patterns (contain * or ?) — those are pattern documentation, not file refs.
-    // BUG-002: In all instruction file types (CLAUDE.md, AGENTS.md, .cursorrules, copilot, etc.)
-    // skip backtick-quoted compiled/native source files — they are almost always architecture
-    // descriptions (e.g. `internal/client/errors.go`), not references to committed files.
-    // Shell (.sh), Python (.py), and JS files are kept because they CAN be real script refs.
+    // BUG-002 / pcic-2b6.8: In all instruction file types (CLAUDE.md, AGENTS.md, .cursorrules,
+    // copilot, etc.) backtick-quoted compiled/native source files are often architecture
+    // descriptions or examples from another project, so they are checked under the
+    // first-segment rule (`rootedSource`). Shell (.sh), Python (.py), and JS files are
+    // checked like any other file because they are usually real script refs.
     const btRe = new RegExp(BACKTICK_PATH_RE.source, BACKTICK_PATH_RE.flags);
     while ((m = btRe.exec(content)) !== null) {
         const ref = m[1] ?? '';
         if (ref && !isExternalRef(ref) && !ref.includes('*') && !ref.includes('?')) {
-            if (opts.skipSourceBackticks) {
-                const ext = path.extname(ref).toLowerCase();
-                if (BACKTICK_SKIP_SOURCE_EXTENSIONS.has(ext) && !STALE_SOURCE_REF_RE.test(ref))
-                    continue;
-            }
-            found.push({ ref, evidence: `\`${ref}\``, line: lineForOffset(lineOffsets, m.index) });
+            const ext = path.extname(ref).toLowerCase();
+            const rooted = opts.skipSourceBackticks && BACKTICK_SKIP_SOURCE_EXTENSIONS.has(ext) && !STALE_SOURCE_REF_RE.test(ref);
+            found.push({
+                ref,
+                evidence: `\`${ref}\``,
+                line: lineForOffset(lineOffsets, m.index),
+                kind: rooted ? 'rootedSource' : 'file',
+                codeSpan: true,
+            });
         }
     }
+    // pcic-2b6.8: backtick directory / extension-less paths: `src/payments/`, `apps/admin`.
+    const btDirRe = new RegExp(BACKTICK_DIR_RE.source, BACKTICK_DIR_RE.flags);
+    while ((m = btDirRe.exec(content)) !== null) {
+        const ref = m[1] ?? '';
+        const last = ref.replace(/\/+$/, '').split('/').pop() ?? '';
+        if (!ref.endsWith('/') && path.extname(last) !== '')
+            continue; // a file: BACKTICK_PATH_RE's job
+        // Slash-shaped names that are not paths: git branches, HTTP routes, URLs.
+        const lineNo = lineForOffset(lineOffsets, m.index);
+        const lineText = content.slice(lineOffsets[lineNo - 1] ?? 0, lineOffsets[lineNo] ?? content.length);
+        if (NON_PATH_CONTEXT_RE.test(lineText))
+            continue;
+        found.push({ ref, evidence: `\`${ref}\``, line: lineForOffset(lineOffsets, m.index), kind: 'rootedPath' });
+    }
     // BUG-004: Bare paths in Repository Layout / Project Structure sections.
     // These appear as bullet list items or ASCII tree lines without backticks.
     if (LAYOUT_SECTION_HEADING_RE.test(content)) {
@@ -480,14 +581,16 @@ function collectRefs(content, opts = {}) {
         while ((m = bulletRe.exec(content)) !== null) {
             const ref = m[1] ?? '';
             if (ref && !isExternalRef(ref)) {
-                found.push({ ref, evidence: m[0].trim(), line: lineForOffset(lineOffsets, m.index) });
+                found.push({ ref, evidence: m[0].trim(), line: lineForOffset(lineOffsets, m.index), kind: 'file' });
             }
         }
-        found.push(...extractLayoutTreePaths(content, lineOffsets));
+        for (const item of extractLayoutTreePaths(content, lineOffsets)) {
+            found.push({ ...item, kind: 'file' });
+        }
         // BUG-002 (eval): Fenced code blocks in layout sections may list documentation
         // files as indented children under a parent directory line ("docs/\n  runbook.md").
         for (const item of extractCodeBlockLayoutPaths(content, lineOffsets)) {
-            found.push(item);
+            found.push({ ...item, kind: 'file' });
         }
     }
     // BUG-D1: Drop only the reference the line instructs the reader to CREATE
@@ -510,6 +613,391 @@ function collectRefs(content, opts = {}) {
         return !isTarget;
     });
 }
+// ── Resolution ───────────────────────────────────────────────────────────────
+/** Path segments of a reference, without `.` / empty segments. */
+function segmentsOf(ref) {
+    return stripFragment(ref).replace(/\\/g, '/').split('/').filter((s) => s !== '' && s !== '.');
+}
+function underOutputDir(ref) {
+    return segmentsOf(ref).some((s) => OUTPUT_DIRS.has(s.toLowerCase()));
+}
+/** The `code` of a filesystem error (`EACCES`, `ENOENT`, …), when it has one. */
+function errorCode(err) {
+    const code = err?.code;
+    return typeof code === 'string' ? code : undefined;
+}
+/** Links followed for one lookup before it gives up (a cycle, or a chain no real tree has). */
+const MAX_LINK_HOPS = 40;
+/**
+ * pcic-xhzb: the only way the detector asks the filesystem about a reference.
+ *
+ * - Contained. A path is looked up by listing the directories from the scan
+ *   root down to it, so nothing outside the root is ever listed, stat'ed or
+ *   opened. A committed link is read (`readlink`, a property of the link,
+ *   which lives in the tree) and followed only while its target stays inside
+ *   the root; a link out of the tree makes the lookup `outside` without
+ *   touching what it points at. A hosted scan runs against a server temp
+ *   directory, and an existence check outside it would tell whoever wrote the
+ *   scanned repository whether a server path exists.
+ * - Exact case. A segment matches a directory entry of exactly that name, so
+ *   `Deploy_PR.yml` does not resolve to `deploy_pr.yml` on a case-insensitive
+ *   filesystem (Windows, macOS). The result is the same on every platform, and
+ *   the same as on Linux and GitHub, where the reference is broken.
+ * - Honest about failure. A directory that cannot be listed makes the lookup
+ *   `unreadable`, never `missing`, and is recorded so the scan can say so.
+ *
+ * Listings are cached for the scan, so each directory is read at most once.
+ */
+class RepoTree {
+    root;
+    /** The root's real path, when it differs (a root under a symlink, like macOS `/var`). */
+    realRoot;
+    listings = new Map();
+    /** What could not be read, as shown in the report (`dir/` or a link's path) → why. */
+    unreadable = new Map();
+    constructor(repoRoot) {
+        this.root = path.resolve(repoRoot);
+        const real = realPath(this.root);
+        this.realRoot = real !== null && real !== this.root ? real : undefined;
+    }
+    /** Forward-slash path relative to the root (`.` for the root itself); never absolute. */
+    relative(abs) {
+        return path.relative(this.root, abs).split(path.sep).join('/') || '.';
+    }
+    /** Record what could not be read: a directory (shown as `dir/`) or a link (shown as its path). */
+    noteUnreadable(p, reason, kind = 'dir') {
+        const abs = path.resolve(this.root, p);
+        // Only in-root names are ever recorded: the report must not carry a server path.
+        if (!isWithinRoot(this.root, abs))
+            return;
+        const rel = this.relative(abs);
+        const shown = kind === 'link' ? rel : rel === '.' ? './' : `${rel}/`;
+        if (!this.unreadable.has(shown))
+            this.unreadable.set(shown, reason);
+    }
+    /** The entries of an in-root directory, by exact name. */
+    list(dir) {
+        let listing = this.listings.get(dir);
+        if (listing === undefined) {
+            try {
+                listing = new Map(fs.readdirSync(dir, { withFileTypes: true }).map((d) => [d.name, d]));
+            }
+            catch (err) {
+                const code = errorCode(err);
+                if (code === 'ENOENT' || code === 'ENOTDIR') {
+                    listing = 'missing';
+                }
+                else {
+                    listing = 'unreadable';
+                    this.noteUnreadable(dir, code ?? 'error');
+                }
+            }
+            this.listings.set(dir, listing);
+        }
+        return listing;
+    }
+    /** In-root equivalent of a link target written against the root's real path. */
+    fromRealRoot(p) {
+        if (this.realRoot === undefined || isWithinRoot(this.root, p) || !isWithinRoot(this.realRoot, p))
+            return p;
+        return path.join(this.root, path.relative(this.realRoot, p));
+    }
+    lookup(candidate) {
+        let target = path.resolve(this.root, candidate);
+        let lastLink = '';
+        for (let hop = 0; hop <= MAX_LINK_HOPS; hop++) {
+            // Lexical containment first: `..`, absolute, other-drive and UNC paths stop here.
+            if (!isWithinRoot(this.root, target))
+                return { state: 'outside' };
+            const parts = path.relative(this.root, target).split(path.sep).filter(Boolean);
+            let dir = this.root;
+            let isDir = true;
+            let next;
+            for (let i = 0; i < parts.length; i++) {
+                if (!isDir)
+                    return { state: 'missing' }; // a file in the middle of a path
+                const listing = this.list(dir);
+                if (listing === 'missing')
+                    return { state: 'missing' };
+                if (listing === 'unreadable')
+                    return { state: 'unreadable' };
+                const name = parts[i];
+                const entry = listing.get(name);
+                if (!entry)
+                    return { state: 'missing' };
+                const entryPath = path.join(dir, name);
+                if (entry.isSymbolicLink()) {
+                    let link;
+                    try {
+                        link = fs.readlinkSync(entryPath);
+                    }
+                    catch (err) {
+                        this.noteUnreadable(entryPath, errorCode(err) ?? 'unreadable link', 'link');
+                        return { state: 'unreadable' };
+                    }
+                    lastLink = entryPath;
+                    // Resolved lexically against the link's own directory, then re-walked
+                    // from the root: the containment check above runs before anything
+                    // under the target is touched.
+                    next = path.join(this.fromRealRoot(path.resolve(dir, link)), ...parts.slice(i + 1));
+                    break;
+                }
+                isDir = entry.isDirectory();
+                dir = entryPath;
+            }
+            if (next === undefined)
+                return { state: 'found', path: dir, isDir };
+            target = next;
+        }
+        // More links than the kernel itself follows (Linux MAXSYMLINKS): a cycle.
+        this.noteUnreadable(lastLink, 'symlink loop', 'link');
+        return { state: 'unreadable' };
+    }
+    isDir(candidate) {
+        const found = this.lookup(candidate);
+        return found.state === 'found' && found.isDir;
+    }
+    /**
+     * An extension-less module path names the file that carries the extension:
+     * `src/lib/db` is `src/lib/db.ts`. True when the directory holds `<name>.*`.
+     */
+    hasStemSibling(candidate) {
+        const dir = this.lookup(path.dirname(candidate));
+        if (dir.state !== 'found' || !dir.isDir)
+            return false;
+        const listing = this.list(dir.path);
+        if (typeof listing === 'string')
+            return false;
+        const prefix = `${path.basename(candidate)}.`;
+        for (const name of listing.keys())
+            if (name.startsWith(prefix))
+                return true;
+        return false;
+    }
+    /**
+     * fast-glob's directory reads, routed through node:fs here so a directory the
+     * walk cannot list is recorded instead of silently dropping out of the result.
+     * The walk itself (`cwd` = root, links not followed) never leaves the root.
+     */
+    walkFs(onError) {
+        const readdirSync = (dir, options) => {
+            try {
+                return options ? fs.readdirSync(dir, options) : fs.readdirSync(dir);
+            }
+            catch (err) {
+                const code = errorCode(err);
+                // A directory deleted mid-walk has nothing left to miss.
+                if (code !== 'ENOENT') {
+                    this.noteUnreadable(dir, code ?? 'error');
+                    onError();
+                }
+                throw err;
+            }
+        };
+        return { readdirSync: readdirSync };
+    }
+}
+/** Trees never searched for an abbreviated path (dependencies, VCS, worktrees, engine caches). */
+const SUFFIX_SEARCH_IGNORE = [
+    ...[
+        ...OUTPUT_DIRS, '.git', 'worktrees', '.worktrees', 'Library', 'Temp', 'Logs', 'vendor',
+        '.venv', 'venv', '__pycache__', 'Pods', '.gradle', '.cache', '.idea',
+    ].map((d) => `**/${d}/**`),
+];
+/**
+ * Runs one repository walk. `complete` is false when any directory could not
+ * be listed: what the walk did not find may still exist (pcic-xhzb).
+ */
+function walk(tree, patterns, onlyFiles) {
+    let complete = true;
+    let entries = [];
+    try {
+        entries = fg.sync(patterns, {
+            cwd: tree.root,
+            dot: true,
+            onlyFiles,
+            followSymbolicLinks: false,
+            // Errors are recorded by walkFs and the walk goes on past them.
+            suppressErrors: true,
+            ignore: SUFFIX_SEARCH_IGNORE,
+            fs: tree.walkFs(() => { complete = false; }),
+        });
+    }
+    catch (err) {
+        tree.noteUnreadable('.', errorCode(err) ?? 'walk failed');
+        complete = false;
+    }
+    return { entries, complete };
+}
+/**
+ * True when the path exists somewhere below the repo root as a suffix — an
+ * abbreviated reference such as `Scripts/Interfaces/` for Unity's
+ * `Assets/Scripts/Interfaces/`, or a package-relative `src/lib/db.ts` in a
+ * monorepo's root instructions. Such a path is imprecise, not stale.
+ * `unknown` when it was not found but the walk could not list everything.
+ */
+function existsAsSuffix(tree, segments, moduleStyle, cache) {
+    const rel = segments.join('/');
+    const key = `${moduleStyle ? 'm' : 'x'}:${rel}`;
+    const cached = cache.get(key);
+    if (cached !== undefined)
+        return cached;
+    const escaped = fg.escapePath(rel);
+    const patterns = [`**/${escaped}`];
+    if (moduleStyle)
+        patterns.push(`**/${escaped}.*`);
+    const { entries, complete } = walk(tree, patterns, false);
+    const found = entries.length > 0 ? true : complete ? false : 'unknown';
+    cache.set(key, found);
+    return found;
+}
+function buildNameIndex(tree) {
+    const paths = new Map();
+    const { entries, complete } = walk(tree, ['**'], true);
+    for (const rel of entries) {
+        const name = rel.slice(rel.lastIndexOf('/') + 1);
+        const list = paths.get(name);
+        if (list)
+            list.push(rel);
+        else
+            paths.set(name, [rel]);
+    }
+    return { paths, complete };
+}
+/** Probe name used to ask the gitignore matcher whether a DIRECTORY is ignored. */
+const DIR_PROBE = '__promptci_dir_probe__';
+/**
+ * Returned when part of the tree the verdict depends on could not be read: the
+ * reference is neither resolved nor reported, and the scan says what it skipped.
+ */
+const UNJUDGED = 'unjudged';
+/**
+ * Confidence that `ref` is a dead reference; `null` when it resolves, is
+ * expected to be absent (gitignored, generated output), lies outside the scan
+ * root, or is not specific enough to judge; {@link UNJUDGED} when the answer
+ * depends on a directory that could not be listed.
+ */
+function judgeReference(ref, kind, codeSpan, fileDir, ctx) {
+    const { tree, isIgnored } = ctx;
+    // `.git/…` is a directory in one checkout and a file in a worktree.
+    if (segmentsOf(ref)[0] === '.git')
+        return null;
+    // pcic-2b6.8 kinds: generated output / dependency trees are never committed.
+    // (File references keep their historical behavior: a committed `bin/setup.sh`
+    // or `scripts/build/x.sh` is still checked.)
+    if (kind !== 'file' && underOutputDir(ref))
+        return null;
+    const pathLike = kind === 'rootedPath' || kind === 'linkPath';
+    const target = pathLike ? stripFragment(ref) : ref;
+    // pcic-xhzb: only candidates inside the scan root are looked up. One that
+    // leaves it — `../../etc/x.md`, `/etc/x.md`, `C:\x.md`, `\\host\share\x.md`,
+    // or a path through a committed link out of the tree — is dropped before
+    // any filesystem access, and a reference with no candidate left is not
+    // judged at all: not resolved, not reported. Reporting it would claim a
+    // file is missing without having looked; a monorepo package scanned on its
+    // own legitimately points at `../../AGENTS.md`. Skipping is also what the
+    // directory kinds below and home-rooted paths (`~/…`) already did.
+    // An absolute path is skipped even when it happens to point into the root:
+    // its verdict would depend on where the repository is checked out, and the
+    // same input must give the same report. Both platforms' forms count (`/x`,
+    // `C:\x`, `\\host\share\x`), so a Windows and a Linux scan agree, and a
+    // Windows scan never opens an SMB connection for `\\host\…`.
+    // A drive-relative `C:notes.md` is skipped too: Windows resolves it against
+    // that drive's working directory, Linux reads it as a file name.
+    if (path.posix.isAbsolute(target) || path.win32.isAbsolute(target) || /^[A-Za-z]:/.test(target))
+        return null;
+    const lookups = [];
+    for (const abs of new Set([path.resolve(fileDir, target), path.resolve(tree.root, target)])) {
+        if (!isWithinRoot(tree.root, abs))
+            continue;
+        const found = tree.lookup(abs);
+        if (found.state !== 'outside')
+            lookups.push({ abs, found });
+    }
+    if (lookups.length === 0)
+        return null;
+    // The repository's own ignore rules say the path is local state (pcic-2b6.8,
+    // same matcher the skills detector uses).
+    for (const { abs } of lookups) {
+        const rel = path.relative(tree.root, abs).replace(/\\/g, '/');
+        if (!rel)
+            continue;
+        if (isIgnored(rel) || (pathLike && isIgnored(`${rel}/${DIR_PROBE}`)))
+            return null;
+    }
+    const moduleStyle = pathLike && !target.endsWith('/');
+    if (lookups.some(({ abs, found }) => found.state === 'found' || (moduleStyle && tree.hasStemSibling(abs)))) {
+        return null;
+    }
+    if (lookups.some(({ found }) => found.state === 'unreadable'))
+        return UNJUDGED;
+    if (kind === 'file') {
+        // pcic-mh72: a bare filename in a code span (`deploy_pr.yml`,
+        // `verify-release.mjs`) names a file, not a location. Prose says "`ci.yml`
+        // runs the tests" about `.github/workflows/ci.yml`, so the name resolves
+        // wherever the repository commits a file by that exact name (case
+        // included, on every platform: pcic-xhzb). A name that exists nowhere, or
+        // only under a dependency or output tree or a gitignored path, is still
+        // reported. The trade-off: a bare name stays silent while ANY file carries
+        // it, so a stale `ci.yml` goes unreported if another `ci.yml` exists.
+        // Names too generic to judge (`index.ts`, `package.json`) were already
+        // skipped by isPlaceholderRef.
+        if (codeSpan && !/[/\\]/.test(target)) {
+            const index = ctx.nameIndex();
+            if (index.paths.get(target)?.some((rel) => !isIgnored(rel)))
+                return null;
+            // pcic-xhzb: a walk that could not list everything is no evidence of absence.
+            if (!index.complete)
+                return UNJUDGED;
+        }
+        // BUG-C1: Source-code paths whose parent directory exists → lower confidence
+        // (likely documentation references, not broken links).
+        const ext = path.extname(ref.split('#')[0] ?? '').toLowerCase();
+        const isSourceCodeRef = SOURCE_CODE_EXTENSIONS.has(ext);
+        const anyParentExists = lookups.some(({ abs }) => tree.isDir(path.dirname(abs)));
+        return isSourceCodeRef && anyParentExists ? 0.5 : 0.85;
+    }
+    if (kind === 'linkPath')
+        return 0.8;
+    // Code-span paths: report only when the path's FIRST segment exists here, so
+    // the reference demonstrably names part of THIS repository — `owner/repo`,
+    // `origin/main`, `@scope/pkg` and another project's `internal/x/y.go` stay silent.
+    // A `..` anywhere (`../shared/`, `src/../x/`) is not a path into this tree.
+    const segments = segmentsOf(ref);
+    if (segments.length < 2 || segments.includes('..'))
+        return null;
+    // The first segment must be a DIRECTORY here (`package.json/scripts` is not a path).
+    const anchorBases = [fileDir, tree.root].filter((base) => tree.isDir(path.join(base, segments[0])));
+    if (anchorBases.length === 0)
+        return null;
+    // pcic-mh72: a lone top-level match is a weak anchor. Almost every project has
+    // a `src/`, so `src/main/java/edu/harvard/iq/dataverse/api/` (another
+    // project's layout, described in prose) matches here on `src` alone. When the
+    // second segment is not a directory here and the path continues three or more
+    // levels below the first segment, it is treated as describing some other tree.
+    // A shorter tail (`src/payments/`, `src/services/billing.ts`) is still checked.
+    // The trade-off: a deep path under a removed intermediate directory
+    // (`src/features/auth/components/` with `src/features/` gone) is not reported.
+    if (segments.length - 1 > MAX_UNANCHORED_DEPTH &&
+        !anchorBases.some((base) => tree.isDir(path.join(base, segments[0], segments[1])))) {
+        return null;
+    }
+    if (kind === 'rootedPath') {
+        // `docs/update-readme`, `test/flaky-fix`: a branch name unless written as a directory.
+        if (BRANCH_PREFIXES.has(segments[0].toLowerCase()) && !target.endsWith('/'))
+            return null;
+        // `client/server`, `public/private`: alternatives when both halves exist side by side.
+        if (segments.length === 2 && anchorBases.some((base) => tree.lookup(path.join(base, segments[1])).state === 'found')) {
+            return null;
+        }
+    }
+    const suffix = existsAsSuffix(tree, segments, moduleStyle, ctx.suffixCache);
+    if (suffix === true)
+        return null;
+    if (suffix === 'unknown')
+        return UNJUDGED;
+    return 0.6;
+}
 // ── Detector ─────────────────────────────────────────────────────────────────
 /**
  * Detect broken file references across all instruction files.
@@ -529,37 +1017,54 @@ function collectRefs(content, opts = {}) {
 export function detectDeadReferences(files, repoRoot) {
     // normRef → { displayRef, filePaths, fileLines, evidenceLines, minConfidence }
     const byRef = new Map();
+    const tree = new RepoTree(repoRoot);
+    let ctx;
+    let nameIndexCache;
+    const nameIndex = () => (nameIndexCache ??= buildNameIndex(tree));
+    // pcic-xhzb: references left unjudged because part of the tree could not be listed.
+    const unjudged = new Map();
     for (const file of files) {
         const fileDir = path.dirname(file.path);
         const refs = collectRefs(file.content, {
             skipSourceBackticks: SKIP_SOURCE_BACKTICK_FILE_TYPES.has(file.fileType),
         });
-        for (const { ref, evidence, line } of refs) {
+        for (const { ref, evidence, line, kind, codeSpan } of refs) {
             // BUG-009: Skip obvious placeholder/example filenames (foo.ts, bar.go, etc.)
             if (isPlaceholderRef(ref))
                 continue;
             // BUG-008: Skip intentionally gitignored credential/config files.
             if (isGitignored(ref))
                 continue;
+            // pcic-2b6.12: Skip home-directory paths (`~/…`, `$HOME/…`, `%USERPROFILE%\…`).
+            if (isHomeRooted(ref))
+                continue;
             // Resolve relative to the instruction file first, then repo root.
-            const candidates = [
-                path.resolve(fileDir, ref),
-                path.resolve(repoRoot, ref),
-            ];
-            if (candidates.some(fileExists))
+            ctx ??= { tree, isIgnored: createGitIgnoreChecker(repoRoot), suffixCache: new Map(), nameIndex };
+            const confidence = judgeReference(ref, kind, codeSpan ?? false, fileDir, ctx);
+            if (confidence === null)
                 continue;
-            // BUG-C1: Source-code paths whose parent directory exists → lower confidence
-            // (likely documentation references, not broken links).
-            const ext = path.extname(ref.split('#')[0] ?? '').toLowerCase();
-            const isSourceCodeRef = SOURCE_CODE_EXTENSIONS.has(ext);
-            const anyParentExists = candidates.some(parentDirExists);
-            const confidence = isSourceCodeRef && anyParentExists ? 0.5 : 0.85;
-            // Normalise for deduplication (case-insensitive, forward slashes)
-            const normRef = ref.toLowerCase().replace(/\\/g, '/');
+            if (confidence === UNJUDGED) {
+                const evidenceText = `Not checked: ${evidence}`;
+                const entry = unjudged.get(evidenceText) ?? { filePaths: new Set(), fileLines: new Map(), evidence: evidenceText };
+                entry.filePaths.add(file.path);
+                const seen = entry.fileLines.get(file.path);
+                if (seen === undefined || line < seen)
+                    entry.fileLines.set(file.path, line);
+                unjudged.set(evidenceText, entry);
+                continue;
+            }
+            // Normalise for deduplication (case-insensitive, forward slashes). Directory
+            // forms also drop `./` and the trailing slash, so `src/api/`, `./src/api`
+            // and a link to `./src/api/` are one finding.
+            const normalized = ref.toLowerCase().replace(/\\/g, '/');
+            const normRef = kind === 'rootedPath' || kind === 'linkPath'
+                ? normalized.replace(/^\.\//, '').replace(/\/+$/, '')
+                : normalized;
             const evidenceLine = `Reference: ${evidence}`;
             if (!byRef.has(normRef)) {
                 byRef.set(normRef, {
                     displayRef: ref,
+                    kind,
                     filePaths: new Set(),
                     fileLines: new Map(),
                     evidenceLines: [],
@@ -580,19 +1085,23 @@ export function detectDeadReferences(files, repoRoot) {
     }
     const issues = [];
     const MIN_CONFIDENCE_THRESHOLD = MIN_CONFIDENCE;
-    for (const [normRef, { displayRef, filePaths, fileLines, evidenceLines, minConfidence }] of byRef) {
+    for (const [normRef, { displayRef, kind, filePaths, fileLines, evidenceLines, minConfidence }] of byRef) {
         // BUG-002: Skip findings below the minimum confidence threshold.
         // Low-confidence source-code path references are almost certainly architecture docs.
         if (minConfidence < MIN_CONFIDENCE_THRESHOLD)
             continue;
         const allFilePaths = [...filePaths];
+        const pathLike = kind === 'rootedPath' || kind === 'linkPath';
+        const isDir = pathLike && stripFragment(displayRef).endsWith('/');
+        const noun = isDir ? 'directory' : pathLike ? 'path' : 'file';
+        const name = path.basename(stripFragment(displayRef).replace(/\/+$/, ''));
         issues.push({
             id: issueId(normRef),
             severity: 'warning',
             category: 'structure',
-            title: `Broken file reference: ${path.basename(stripFragment(displayRef))}`,
+            title: `Broken ${noun} reference: ${name}${isDir ? '/' : ''}`,
             summary: `This instruction file references "${displayRef}" which does not appear to exist. ` +
-                `The file may have been renamed, moved, or deleted.`,
+                `The ${noun} may have been renamed, moved, or deleted.`,
             filePaths: allFilePaths,
             locations: allFilePaths.map((fp) => {
                 const startLine = fileLines.get(fp);
@@ -604,6 +1113,55 @@ export function detectDeadReferences(files, repoRoot) {
             confidence: minConfidence,
         });
     }
+    if (unjudged.size > 0)
+        issues.push(incompleteCheckIssue(tree, [...unjudged.values()]));
     return issues;
 }
+/** Evidence lines listed per kind before the rest is summarised. */
+const MAX_INCOMPLETE_EVIDENCE = 10;
+/**
+ * pcic-xhzb: a directory the scan could not list is named, never turned into
+ * findings. Without this, an unreadable directory emptied the name index (or
+ * part of it) and every bare name filed there was reported as broken, with no
+ * sign the scan had failed. The gap is a `warning`, the severity of the
+ * findings it stands in for, so a `--fail-on warning` gate that a broken
+ * reference would have tripped is not passed silently by a scan that could
+ * not look (the supply-chain scan's `unscanned-files` likewise warns about
+ * content it could not read). Paths are repo-relative, so a hosted scan never
+ * shows its temp dir.
+ */
+function incompleteCheckIssue(tree, refs) {
+    const capped = (lines, noun) => lines.length > MAX_INCOMPLETE_EVIDENCE
+        ? [...lines.slice(0, MAX_INCOMPLETE_EVIDENCE), `…and ${lines.length - MAX_INCOMPLETE_EVIDENCE} more ${noun}`]
+        : lines;
+    const dirs = [...tree.unreadable].sort(([a], [b]) => a.localeCompare(b));
+    const dirLines = dirs.map(([shown, reason]) => `Could not read: ${shown} (${reason})`);
+    const filePaths = [...new Set(refs.flatMap((r) => [...r.filePaths]))];
+    const firstLine = new Map();
+    for (const r of refs) {
+        for (const [fp, line] of r.fileLines) {
+            const seen = firstLine.get(fp);
+            if (seen === undefined || line < seen)
+                firstLine.set(fp, line);
+        }
+    }
+    return {
+        id: issueId('(dead-reference check incomplete)'),
+        severity: 'warning',
+        category: 'structure',
+        title: 'Dead-reference check incomplete: part of the repository could not be read',
+        summary: `${refs.length} reference(s) were not checked because part of the repository could not be read ` +
+            `(${dirs.length} location${dirs.length === 1 ? '' : 's'}). They may or may not exist; ` +
+            'no broken-reference finding was reported for them.',
+        filePaths,
+        locations: filePaths.map((fp) => {
+            const startLine = firstLine.get(fp);
+            return startLine !== undefined ? { filePath: fp, startLine } : { filePath: fp };
+        }),
+        evidence: [...capped(dirLines, 'locations'), ...capped(refs.map((r) => r.evidence), 'references')],
+        recommendation: 'Make the listed locations readable by the user running the scan (or fix the symlink), then scan again to ' +
+            'check these references.',
+        confidence: 0.8,
+    };
+}
 //# sourceMappingURL=dead-references.js.map