vigiles 16.1.0 → 16.1.2

package/dist/core/bash-effects.d.ts

@@ -192,4 +192,61 @@ export declare function leafCommandsNormalized(command: string): NormalizedLeaf[
  * Parse failure → `[]`.
  */
 export declare function leafArgvSource(command: string): string[][];
+/**
+ * Every word of every simple command in `command` that could name a FILE, with
+ * inline PROGRAM TEXT removed — the primitive behind "does this hook's script
+ * exist?".
+ *
+ * 🔴 WHY A FOURTH EXTRACTOR, stated against the three that already exist,
+ * because "there is already one that returns words" is exactly the reasoning
+ * that produced the bug this replaces.
+ *
+ *  - `leafCommands` drops every word it cannot reduce to a LITERAL, so
+ *    `${CLAUDE_PLUGIN_ROOT}/hooks/x.sh` — the standard spelling of a hook path —
+ *    disappears entirely. Unusable for a file question.
+ *  - `leafCommandsNormalized` basenames the head, so `./hooks/x.sh` becomes
+ *    `x.sh` and no resolver can find it.
+ *  - `leafArgvSource` keeps the spelling but answers a DIFFERENT question:
+ *    "which leaves unconditionally RUN". It drops the right-hand side of `&&`
+ *    by design, so `cd "$ROOT" && node hooks/x.mjs` yields no script. For
+ *    coverage attribution that abstention is correct; for "must this file
+ *    exist?" it is a miss, because a conditionally-run script still has to be
+ *    on disk.
+ *
+ * So this walks EVERY simple command, keeps every word at source level, and
+ * subtracts only the words that are provably not paths.
+ *
+ * 🔴 WHAT IT SUBTRACTS, and the defect that motivated it. The hook scanner used
+ * to run a regex over the raw command STRING. Against the standard portable
+ * plugin idiom —
+ *
+ *     node -e "(async()=>{…await import(…join(root,'hooks','always-on.mjs'))…})()"
+ *
+ * — it grabbed a character run ending at `.mjs` and reported the hook's script
+ * as `import(require(node:url).pathToFileURL(require(node:path).join(root,hooks,always-on.mjs`,
+ * MISSING. `hooks/always-on.mjs` was 1,766 bytes on disk. Nine such findings
+ * across the 32-repo corpus, contributing to two `F/0` grades. Inside a shell
+ * parse the argument of `-e` is not a word the shell will ever resolve to a
+ * file, so it is not returned.
+ *
+ * ⚠️ HOW MUCH OF THAT THE FLAG TABLE ACTUALLY DID, measured rather than
+ * assumed: none of it, on that corpus. Mutating the `-e`/`-c` subtraction OFF
+ * and re-auditing all three affected repos still yields ZERO false hook-script
+ * findings, because both real payloads are single words that either contain
+ * whitespace or do not end in a script extension, and the caller anchors its
+ * match to a whole word. The table is kept because it is the difference
+ * between a function whose contract ("words that could name a file") is true
+ * and one whose contract is merely true-so-far: without it a JavaScript
+ * program is handed to every caller as a candidate filename, and the next
+ * caller inherits the bug. Recorded here so nobody reads a corpus number back
+ * onto the wrong mechanism.
+ *
+ * Words beginning with `-` are dropped as flags: a flag is not a path, and the
+ * one caller anchors its match to a whole word anyway.
+ *
+ * Returns `null` — not `[]` — when the text does not parse as shell, so a
+ * caller can tell "no file operands" from "no analysis", and cannot silently
+ * treat the second as the first.
+ */
+export declare function commandWords(command: string): string[] | null;
 //# sourceMappingURL=bash-effects.d.ts.map

package/dist/core/bash-effects.js

@@ -29,6 +29,7 @@ exports.isReadOnlyBash = isReadOnlyBash;
 exports.leafCommands = leafCommands;
 exports.leafCommandsNormalized = leafCommandsNormalized;
 exports.leafArgvSource = leafArgvSource;
+exports.commandWords = commandWords;
 // mvdan-sh is a CJS package (GopherJS build) with no bundled TypeScript types.
 // The project compiles to CommonJS (Node16, no "type":"module"), so plain
 // require() works and is the idiomatic pattern here (see linters.ts).
@@ -1098,4 +1099,150 @@ function normalizeCallExpr(node, redirs) {
         chdir: stripped.chdir,
     };
 }
+// ===========================================================================
+// FILE-OPERAND extraction (the reference question, not the effect question)
+// ===========================================================================
+/**
+ * Interpreters, and the flags after which the NEXT word is a PROGRAM rather
+ * than a path. `node -e "<js>"`, `python -c "<py>"`, `perl -E "<pl>"`.
+ *
+ * Keyed by the head's basename, so `/usr/local/bin/node` and `node` behave the
+ * same.
+ */
+const INLINE_PROGRAM_FLAGS = new Map([
+    ["node", ["-e", "--eval", "-p", "--print"]],
+    ["nodejs", ["-e", "--eval", "-p", "--print"]],
+    ["bun", ["-e", "--eval", "-p", "--print"]],
+    ["deno", ["-e", "--eval", "-p", "--print"]],
+    ["python", ["-c"]],
+    ["python2", ["-c"]],
+    ["python3", ["-c"]],
+    ["ruby", ["-e"]],
+    ["perl", ["-e", "-E"]],
+    ["php", ["-r"]],
+]);
+/**
+ * Shells, whose `-c` argument is a nested SHELL program. Not program text to be
+ * discarded — program text to be PARSED, so `bash -c 'exec "$ROOT/hooks/x.sh"'`
+ * still yields its script.
+ */
+const SHELL_HEADS = new Set([
+    "sh",
+    "bash",
+    "zsh",
+    "dash",
+    "ksh",
+    "ash",
+    "busybox",
+]);
+/** Guard against a pathological `sh -c 'sh -c "sh -c …"'` nest. */
+const MAX_SHELL_NESTING = 3;
+/**
+ * Every word of every simple command in `command` that could name a FILE, with
+ * inline PROGRAM TEXT removed — the primitive behind "does this hook's script
+ * exist?".
+ *
+ * 🔴 WHY A FOURTH EXTRACTOR, stated against the three that already exist,
+ * because "there is already one that returns words" is exactly the reasoning
+ * that produced the bug this replaces.
+ *
+ *  - `leafCommands` drops every word it cannot reduce to a LITERAL, so
+ *    `${CLAUDE_PLUGIN_ROOT}/hooks/x.sh` — the standard spelling of a hook path —
+ *    disappears entirely. Unusable for a file question.
+ *  - `leafCommandsNormalized` basenames the head, so `./hooks/x.sh` becomes
+ *    `x.sh` and no resolver can find it.
+ *  - `leafArgvSource` keeps the spelling but answers a DIFFERENT question:
+ *    "which leaves unconditionally RUN". It drops the right-hand side of `&&`
+ *    by design, so `cd "$ROOT" && node hooks/x.mjs` yields no script. For
+ *    coverage attribution that abstention is correct; for "must this file
+ *    exist?" it is a miss, because a conditionally-run script still has to be
+ *    on disk.
+ *
+ * So this walks EVERY simple command, keeps every word at source level, and
+ * subtracts only the words that are provably not paths.
+ *
+ * 🔴 WHAT IT SUBTRACTS, and the defect that motivated it. The hook scanner used
+ * to run a regex over the raw command STRING. Against the standard portable
+ * plugin idiom —
+ *
+ *     node -e "(async()=>{…await import(…join(root,'hooks','always-on.mjs'))…})()"
+ *
+ * — it grabbed a character run ending at `.mjs` and reported the hook's script
+ * as `import(require(node:url).pathToFileURL(require(node:path).join(root,hooks,always-on.mjs`,
+ * MISSING. `hooks/always-on.mjs` was 1,766 bytes on disk. Nine such findings
+ * across the 32-repo corpus, contributing to two `F/0` grades. Inside a shell
+ * parse the argument of `-e` is not a word the shell will ever resolve to a
+ * file, so it is not returned.
+ *
+ * ⚠️ HOW MUCH OF THAT THE FLAG TABLE ACTUALLY DID, measured rather than
+ * assumed: none of it, on that corpus. Mutating the `-e`/`-c` subtraction OFF
+ * and re-auditing all three affected repos still yields ZERO false hook-script
+ * findings, because both real payloads are single words that either contain
+ * whitespace or do not end in a script extension, and the caller anchors its
+ * match to a whole word. The table is kept because it is the difference
+ * between a function whose contract ("words that could name a file") is true
+ * and one whose contract is merely true-so-far: without it a JavaScript
+ * program is handed to every caller as a candidate filename, and the next
+ * caller inherits the bug. Recorded here so nobody reads a corpus number back
+ * onto the wrong mechanism.
+ *
+ * Words beginning with `-` are dropped as flags: a flag is not a path, and the
+ * one caller anchors its match to a whole word anyway.
+ *
+ * Returns `null` — not `[]` — when the text does not parse as shell, so a
+ * caller can tell "no file operands" from "no analysis", and cannot silently
+ * treat the second as the first.
+ */
+function commandWords(command) {
+    return commandWordsAt(command, 0);
+}
+function commandWordsAt(command, depth) {
+    let file;
+    try {
+        file = sh.syntax.NewParser().Parse(command, "cmd.sh");
+    }
+    catch {
+        return null;
+    }
+    const out = [];
+    sh.syntax.Walk(file, (node) => {
+        if (sh.syntax.NodeType(node) === "CallExpr" && node.Args?.length)
+            fileOperandsOf(node.Args, depth, out);
+        return true;
+    });
+    return out;
+}
+/**
+ * The file-operand words of ONE simple command, appended to `out`.
+ *
+ * Wrappers are resolved through with the same table `leafArgvSource` uses (it
+ * keys on the BASENAME head, and wrappers only ever drop words off the FRONT,
+ * so a count maps the result back onto the original spellings — not a second
+ * copy of the rule). Flags never name a file, so they are dropped; the word
+ * AFTER an inline-program flag is dropped with them, and the word after a
+ * shell's `-c` is parsed as shell instead.
+ */
+function fileOperandsOf(args, depth, out) {
+    const raw = args.map((w) => sourceParts(w.Parts) ?? "");
+    const probe = [normalizeHead(raw[0] ?? ""), ...raw.slice(1)];
+    const argv = raw.slice(probe.length - stripWrappers(probe).argv.length);
+    const head = normalizeHead(argv[0] ?? "");
+    const programFlags = INLINE_PROGRAM_FLAGS.get(head);
+    const nestsShell = SHELL_HEADS.has(head) && depth < MAX_SHELL_NESTING;
+    for (let i = 0; i < argv.length; i++) {
+        const w = argv[i] ?? "";
+        if (w === "")
+            continue;
+        if (!w.startsWith("-")) {
+            out.push(w);
+            continue;
+        }
+        if (nestsShell && w === "-c") {
+            out.push(...(commandWordsAt(argv[++i] ?? "", depth + 1) ?? []));
+        }
+        else if (programFlags?.includes(w)) {
+            i++; // the program text — not a word any shell resolves to a file
+        }
+    }
+}
 //# sourceMappingURL=bash-effects.js.map

package/dist/core/markdown.d.ts

@@ -42,4 +42,57 @@ export interface FencedBlock {
  * so a caller's message points at the real line.
  */
 export declare function fencedCodeBlocks(src: string): FencedBlock[];
+/**
+ * How a reference appeared in the markdown.
+ *
+ * `link` is a DESTINATION — the thing the reader follows: an inline link's
+ * target, or an image's `src`. `code` is a bare backtick span standing on its
+ * own in prose.
+ */
+export type MarkdownRefKind = "link" | "code";
+/** One reference recovered from markdown STRUCTURE. */
+export interface MarkdownRef {
+    readonly kind: MarkdownRefKind;
+    /**
+     * For `link`, the destination exactly as written. For `code`, the span's
+     * content. Never the display text of a link — see {@link markdownRefs}.
+     */
+    readonly value: string;
+    /** 1-based source line the reference sits on. */
+    readonly line: number;
+}
+/**
+ * Every reference a markdown body makes, taken from the PARSE rather than from
+ * the characters.
+ *
+ * 🔴 WHY THIS EXISTS: A LINK'S TEXT IS NOT A REFERENCE. The detector this
+ * replaces ran two regexes over each line — one for `[..](..)`, one for
+ * `` `..` `` — and the second one could not see that it was standing inside the
+ * first. Measured 2026-08-17 on `microsoft/power-platform-skills`:
+ *
+ *     See [`references/dataverse-reference.md` § Setting Lookups](../add-dataverse/references/dataverse-reference.md#setting-lookups)
+ *
+ * The DESTINATION resolves — the file is 23KB and present. The backtick span in
+ * the link's TEXT is a human-readable label for it. vigiles reported the label
+ * as a missing bundled resource, i.e. it accused a correct link of being broken
+ * by reading the half of it that is display. The same shape cost
+ * `rohitg00/pro-workflow` a second false accusation.
+ *
+ * So a code span nested inside a link's (or an image's) text is NOT emitted.
+ * The destination is right there, it is what the agent follows, and it is
+ * returned instead. The bug is not fixed here so much as made unsayable: a
+ * caller of this function is never handed link text at all.
+ *
+ * Fenced and indented code blocks contribute nothing ({@link fencedLineFlags}
+ * decides which lines those are, so no caller re-derives it).
+ *
+ * ⚠️ ONE LINE AT A TIME, and the reason is the line number. Callers report a
+ * reference by source line, and markdown-it's inline tokens carry no line
+ * information — only the enclosing block does — so a paragraph-wide parse would
+ * point every reference in a paragraph at the paragraph's first line. Parsing
+ * each line's inline content keeps the number exact. The cost is a construct
+ * split across two source lines (a link whose `](` sits on the next line),
+ * which is not recovered — the regexes this replaces did not recover it either.
+ */
+export declare function markdownRefs(src: string): MarkdownRef[];
 //# sourceMappingURL=markdown.d.ts.map

package/dist/core/markdown.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fencedLineFlags = fencedLineFlags;
 exports.fencedCodeBlocks = fencedCodeBlocks;
+exports.markdownRefs = markdownRefs;
 /**
  * vigiles — the ONE markdown-structure helper.
  *
@@ -25,6 +26,23 @@ exports.fencedCodeBlocks = fencedCodeBlocks;
 const markdown_it_1 = __importDefault(require("markdown-it"));
 // One reusable parser; parse() is stateless across calls.
 const md = new markdown_it_1.default();
+/**
+ * A SECOND parser, used only by {@link markdownRefs}, with link handling turned
+ * down to "report exactly what the author wrote":
+ *
+ * - `normalizeLink` is neutered because the default percent-ENCODES the
+ *   destination. A detector downstream reads `%NN` as the signature of a URL or
+ *   of a documentation example about escaping spaces, and skips it; letting
+ *   markdown-it encode on the way in would manufacture that signature for any
+ *   destination holding a space or a non-ASCII character.
+ * - `validateLink` is opened because the default silently REFUSES to build a
+ *   link token for schemes it distrusts (`javascript:`, `data:`), which would
+ *   turn "a destination this tool declines to resolve" into "no destination at
+ *   all". Skipping by scheme is the caller's job and it already does it.
+ */
+const mdRefs = new markdown_it_1.default();
+mdRefs.normalizeLink = (url) => url;
+mdRefs.validateLink = () => true;
 /**
  * A boolean per source line (0-based): `true` when the line lies inside a fenced
  * code block (` ``` ` or `~~~`), the delimiter lines included — matching the
@@ -85,4 +103,85 @@ function fencedCodeBlocks(src) {
     }
     return out;
 }
+/**
+ * Every reference a markdown body makes, taken from the PARSE rather than from
+ * the characters.
+ *
+ * 🔴 WHY THIS EXISTS: A LINK'S TEXT IS NOT A REFERENCE. The detector this
+ * replaces ran two regexes over each line — one for `[..](..)`, one for
+ * `` `..` `` — and the second one could not see that it was standing inside the
+ * first. Measured 2026-08-17 on `microsoft/power-platform-skills`:
+ *
+ *     See [`references/dataverse-reference.md` § Setting Lookups](../add-dataverse/references/dataverse-reference.md#setting-lookups)
+ *
+ * The DESTINATION resolves — the file is 23KB and present. The backtick span in
+ * the link's TEXT is a human-readable label for it. vigiles reported the label
+ * as a missing bundled resource, i.e. it accused a correct link of being broken
+ * by reading the half of it that is display. The same shape cost
+ * `rohitg00/pro-workflow` a second false accusation.
+ *
+ * So a code span nested inside a link's (or an image's) text is NOT emitted.
+ * The destination is right there, it is what the agent follows, and it is
+ * returned instead. The bug is not fixed here so much as made unsayable: a
+ * caller of this function is never handed link text at all.
+ *
+ * Fenced and indented code blocks contribute nothing ({@link fencedLineFlags}
+ * decides which lines those are, so no caller re-derives it).
+ *
+ * ⚠️ ONE LINE AT A TIME, and the reason is the line number. Callers report a
+ * reference by source line, and markdown-it's inline tokens carry no line
+ * information — only the enclosing block does — so a paragraph-wide parse would
+ * point every reference in a paragraph at the paragraph's first line. Parsing
+ * each line's inline content keeps the number exact. The cost is a construct
+ * split across two source lines (a link whose `](` sits on the next line),
+ * which is not recovered — the regexes this replaces did not recover it either.
+ */
+function markdownRefs(src) {
+    const lines = src.split("\n");
+    const fenced = fencedLineFlags(src);
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        // Cheap reject: no link syntax and no backtick means no reference, and most
+        // lines of a real corpus are that.
+        if (fenced[i] || (!line.includes("`") && !line.includes("](")))
+            continue;
+        for (const tok of mdRefs.parseInline(line, {})) {
+            refsInInline(tok.children ?? [], i + 1, out);
+        }
+    }
+    return out;
+}
+/** Which attribute carries the DESTINATION, per inline token type. */
+const DESTINATION_ATTR = {
+    link_open: "href",
+    image: "src",
+};
+/**
+ * Walk ONE line's inline token stream, appending its references.
+ *
+ * `linkDepth` is the whole point: markdown-it emits `link_open` … `link_close`
+ * around the link's TEXT, so a `code_inline` seen while the depth is non-zero
+ * is display, and its destination has already been recorded.
+ */
+function refsInInline(children, line, out) {
+    let linkDepth = 0;
+    for (const child of children) {
+        if (child.type === "link_close") {
+            linkDepth--;
+            continue;
+        }
+        if (child.type === "link_open")
+            linkDepth++;
+        // An image's alt text is a nested inline stream markdown-it keeps in
+        // `children`; it is display, exactly like link text, so only the `src` is
+        // taken and the alt is not descended into.
+        const destAttr = DESTINATION_ATTR[child.type];
+        const dest = destAttr === undefined ? null : child.attrGet(destAttr);
+        if (dest)
+            out.push({ kind: "link", value: dest, line });
+        else if (child.type === "code_inline" && linkDepth === 0)
+            out.push({ kind: "code", value: child.content, line });
+    }
+}
 //# sourceMappingURL=markdown.js.map

package/dist/core/skill-resources.js

@@ -37,6 +37,15 @@ exports.skillResourceIssues = skillResourceIssues;
  * `MD_HEADING`) and carries no illustrative cue (example / e.g. / such as /
  * would be / template / →). See `inlinePathIsUsed`.
  *
+ * CANDIDATES COME FROM THE PARSE, THE GATE READS THE PROSE. Every candidate is
+ * a `MarkdownRef` from `core/markdown.ts` — a link's DESTINATION or a code span
+ * that is not inside a link's text. The line is then consulted only to decide
+ * whether the surrounding prose DIRECTS the agent at the file. Before that
+ * split, a second regex scanned each line for backtick spans without knowing it
+ * was standing inside a link, and reported the link's LABEL as a missing
+ * resource while its destination resolved (measured on
+ * `microsoft/power-platform-skills` and `rohitg00/pro-workflow`, 2026-08-17).
+ *
  * ESCAPE HATCH: a SKILL.md carrying `<!-- vigiles-disable skill-resource-resolves -->`
  * anywhere in its body opts OUT of this check entirely (mirrors `orphans.ts`'s
  * `vigiles-disable orphan-docs`) — for a skill whose body is inherently full of
@@ -57,13 +66,6 @@ const markdown_js_1 = require("./markdown.js");
 // these is unambiguously a local bundled resource, even without a `./`.
 const BUNDLE_DIRS = ["scripts", "references", "assets"];
 const BUNDLE_PREFIX = new RegExp(`^(?:${BUNDLE_DIRS.join("|")})/`);
-// A markdown inline link `[text](target)` — we read its target.
-const MD_LINK = /\[[^\]]*\]\(([^)\s]+)\)/g;
-// An inline-code path mention: a backtick span whose whole content is a single
-// path token. We only treat it as a ref when it is a bundle-dir-prefixed path
-// with an extension (the high-confidence shape); a bare `scripts` or a generic
-// `foo.ts` mention is NOT flagged.
-const INLINE_SPAN = /`([^`\n]+)`/g;
 // A path must carry a file extension to be a resource reference. A bare word or
 // a directory name (`scripts/lib`) is undecidable prose — skipped.
 const HAS_EXT = /\.[A-Za-z0-9]+$/;
@@ -224,39 +226,40 @@ function inlinePathIsUsed(line) {
         return false;
     return USE_DIRECTIVE.test(line) || MD_HEADING.test(line);
 }
-/** Collect candidate bundled-resource refs from one body line, skipping fences. */
-function candidatesInLine(line, lineNo) {
-    const out = [];
-    // A markdown link is EXPLICIT follow-me syntax (`[text](target)`) — the link IS
-    // the reference — so it's real UNLESS the line is an illustrative example.
-    // Suppress it ONLY on an illustrative cue; do NOT also require a use directive,
-    // or a plain `Resources: [API](references/api.md)` (no verb) goes unchecked
-    // (Codex review — that under-detection). A BARE inline backtick path is noisier
-    // (often just a mention), so it still needs BOTH a use directive AND no cue.
-    const illustrative = ILLUSTRATIVE_CUE.test(line);
-    // Markdown links: a relative path target that passes the local-resource gate.
-    if (!illustrative) {
-        for (const m of line.matchAll(MD_LINK)) {
-            const resolved = localResourceTarget(m[1]);
-            if (resolved !== null) {
-                out.push({ ref: m[1].trim(), resolved, kind: "link", line: lineNo });
-            }
-        }
-    }
-    // Inline-code path mentions: only the high-confidence bundle-dir-prefixed form,
-    // and only when the prose directs the agent to use it (the noisier shape).
-    if (inlinePathIsUsed(line)) {
-        for (const m of line.matchAll(INLINE_SPAN)) {
-            const token = m[1].trim();
-            if (!isInlineBundlePath(token))
-                continue;
-            const resolved = localResourceTarget(token);
-            if (resolved !== null) {
-                out.push({ ref: token, resolved, kind: "path", line: lineNo });
-            }
-        }
+/**
+ * Turn one structural markdown reference into a candidate, or `null`.
+ *
+ * `line` is the raw source line, used ONLY by the prose gate — the candidate
+ * itself comes from {@link markdownRefs}, never from the characters. That split
+ * is load-bearing: the gate reads prose because prose is what it judges, while
+ * a REFERENCE is a thing the parser found.
+ */
+function candidateFor(ref, line) {
+    if (ref.kind === "link") {
+        // A markdown link is EXPLICIT follow-me syntax — the DESTINATION is the
+        // reference — so it's real UNLESS the line is an illustrative example.
+        // Suppress it ONLY on an illustrative cue; do NOT also require a use
+        // directive, or a plain `Resources: [API](references/api.md)` (no verb)
+        // goes unchecked (Codex review — that under-detection).
+        if (ILLUSTRATIVE_CUE.test(line))
+            return null;
+        const resolved = localResourceTarget(ref.value);
+        if (resolved === null)
+            return null;
+        return { ref: ref.value.trim(), resolved, kind: "link", line: ref.line };
     }
-    return out;
+    // A bare inline backtick path is noisier (often just a mention), so it needs
+    // BOTH a use directive AND no cue, and only in the high-confidence
+    // bundle-dir-prefixed form.
+    if (!inlinePathIsUsed(line))
+        return null;
+    const token = ref.value.trim();
+    if (!isInlineBundlePath(token))
+        return null;
+    const resolved = localResourceTarget(token);
+    if (resolved === null)
+        return null;
+    return { ref: token, resolved, kind: "path", line: ref.line };
 }
 /**
  * A SKILL.md body carrying this marker opts OUT of skill-resource checking
@@ -293,25 +296,23 @@ function skillResourceIssues(skillBody, skillDir, opts) {
     const findings = [];
     const seen = new Set();
     const lines = skillBody.split("\n");
-    const fenced = (0, markdown_js_1.fencedLineFlags)(skillBody);
-    for (let i = 0; i < lines.length; i++) {
-        if (fenced[i])
+    for (const ref of (0, markdown_js_1.markdownRefs)(skillBody)) {
+        const c = candidateFor(ref, lines[ref.line - 1] ?? "");
+        if (c === null)
+            continue;
+        if (resolvesAnywhere(c.resolved))
+            continue;
+        // De-dupe the same missing file referenced several times in the body.
+        const key = `${c.kind}:${c.resolved}`;
+        if (seen.has(key))
             continue;
-        for (const c of candidatesInLine(lines[i], i + 1)) {
-            if (resolvesAnywhere(c.resolved))
-                continue;
-            // De-dupe the same missing file referenced several times in the body.
-            const key = `${c.kind}:${c.resolved}`;
-            if (seen.has(key))
-                continue;
-            seen.add(key);
-            findings.push({
-                ref: c.ref,
-                resolved: c.resolved,
-                kind: c.kind,
-                line: c.line,
-            });
-        }
+        seen.add(key);
+        findings.push({
+            ref: c.ref,
+            resolved: c.resolved,
+            kind: c.kind,
+            line: c.line,
+        });
     }
     return findings;
 }

package/dist/core/source-refs.d.ts

@@ -0,0 +1,118 @@
+/**
+ * vigiles — recovering a FILE REFERENCE from PLAIN SOURCE TEXT.
+ *
+ * The third of three reference grammars, and the only one with no parser behind
+ * it. A markdown body is read by markdown-it (`core/markdown.ts` →
+ * `markdownRefs`), a hook `command` is read by mvdan-sh (`core/bash-effects.ts`
+ * → `commandWords`), and what is left — the body of a hook script, a helper
+ * `.js` / `.py` / `.rb` — is scanned for path-shaped character runs, because a
+ * general-purpose "find every path this program touches" analysis is not a
+ * thing this tool can be.
+ *
+ * Since that scan IS a character run, the only thing standing between it and a
+ * false accusation is where the run may START and STOP. This module owns both
+ * boundaries and the extension vocabularies, so no caller can build a pattern
+ * without them.
+ *
+ * ## The two boundaries, and the two live defects that came from omitting them
+ *
+ * RIGHT — the extension must END the token. `INTRA_REF_EXTS` used to be a bare
+ * alternation with no trailing assertion, and `js` sits ahead of `json` in it,
+ * so `hooks/hooks.json` matched as `hooks/hooks.js`. Measured 2026-08-17 on
+ * `microsoft/power-platform-skills`: a `//` comment naming `hooks/hooks.json`,
+ * with that exact file sitting beside it on disk, was reported as
+ * "hooks/hooks.js (referenced but MISSING)" — a maintainer told a file they
+ * have is missing, under a name they never wrote.
+ *
+ * LEFT — the surface dir must START the token. `(?:agents|hooks|skills)/` with
+ * nothing before it also matches the tail of `claude-agents/`. Measured the
+ * same day on `fcakyon/claude-codex-settings`: a
+ * `new URL("../../../claude-agents/fable-advisor.md", …)` — a correct,
+ * resolving reference — was reported as a broken `agents/fable-advisor.md`.
+ * That boundary is a predicate ({@link startsAtSeparator}) rather than a regex
+ * lookbehind, because the browser twin (`scan-files.ts`) compiles this into the
+ * demo engine, and because the caller already inspects `m.index` for its
+ * plugin-rooted test.
+ *
+ * ## Comments are prose in every language, not only in shell
+ *
+ * `stripShellComments` had the right idea and too narrow a domain: a full-line
+ * `#` in a `.sh` file is prose, and so is a full-line `//` or a JSDoc `*` in a
+ * `.js` file. Both remaining corpus false accusations in this detector came out
+ * of JSDoc — `* It is deliberately not registered in hooks/hooks.json:` and
+ * "`git log --grep=.env -- hooks/x.mjs` is refused …". Neither is a file
+ * operation; both were reported as broken references.
+ *
+ * FULL-LINE ONLY, the same rule the shell version already held. A trailing
+ * comment on a real code line is left alone, so a genuine reference sharing a
+ * line with code is never dropped. The cost is stated rather than hidden: a
+ * path mentioned ONLY in a trailing comment still counts as a reference.
+ */
+/**
+ * Whether a match at `idx` begins at a path boundary rather than inside a
+ * longer name. Position 0 counts as a boundary.
+ *
+ * `/` is a boundary on purpose: `${CLAUDE_PLUGIN_ROOT}/hooks/x.sh` is the
+ * standard spelling, and the caller's plugin-rooted test decides whether the
+ * segment before that slash roots the path inside the plugin or outside it.
+ */
+export declare function startsAtSeparator(content: string, idx: number): boolean;
+/**
+ * Extensions an intra-plugin reference may carry — the file kinds a plugin's
+ * own hook / helper source legitimately points at.
+ */
+export declare const INTRA_REF_EXTENSIONS: readonly ["md", "sh", "cmd", "mjs", "cjs", "js", "ts", "py", "rb", "txt", "json"];
+/**
+ * Extensions a RUNNABLE script carries. Shared by the hook scanner and the
+ * coverage twins, which each declared their own copy before.
+ */
+export declare const SCRIPT_REF_EXTENSIONS: readonly ["sh", "mjs", "cjs", "js", "ts", "py", "rb"];
+/**
+ * A plugin-relative path under one of `dirs`, carrying a known extension — the
+ * pattern for scanning a plugin's own SOURCE TEXT.
+ *
+ * The left boundary is not baked into the returned regex (see
+ * {@link startsAtSeparator}): a caller scanning raw text must apply that
+ * predicate at `m.index`, which both the disk detector and its browser twin do
+ * inside their plugin-rooted test.
+ */
+export declare function intraRefPattern(dirs: readonly string[]): RegExp;
+/**
+ * A script path occupying a WHOLE shell WORD.
+ *
+ * ⚠️ ANCHORING IS NOT WHAT FIXES THE `node -e` DEFECT, and saying so would be
+ * wrong twice over — the payload
+ * `import(require(node:url).pathToFileURL(require(node:path).join(root,hooks,always-on.mjs`
+ * contains no whitespace and ends in `.mjs`, so it satisfies this pattern
+ * perfectly (asserted in source-refs.test.ts, so the claim cannot drift back).
+ * That defect is fixed one level up, by `commandWords` refusing to hand the
+ * argument of `-e` to anyone.
+ *
+ * What anchoring buys is narrower and worth stating exactly: the reported name
+ * is always a word a shell could hand to `execve`, never a fragment cut out of
+ * a longer one. `echo "see hooks/x.sh"` is one word containing a path; before,
+ * `hooks/x.sh` was lifted out of it and checked as though the hook ran it.
+ *
+ * The cost, stated rather than discovered later: a path bundled into a flag
+ * (`--require=hooks/x.js`) is no longer seen. Measured across the 32-repo
+ * dogfood corpus, that costs zero findings.
+ */
+export declare function scriptWordPattern(): RegExp;
+/**
+ * A script path appearing anywhere inside a string — for the one caller with no
+ * shell parse to hand (the coverage twins scan a serialized settings blob).
+ * Carries the right boundary; it cannot carry the left one, and its callers
+ * gate every hit on the file existing, so a stray match is dropped rather than
+ * reported.
+ */
+export declare function scriptRefPattern(): RegExp;
+/**
+ * Drop FULL-LINE comments (including a shebang, which also starts with `#`)
+ * from an executable source before it is scanned for path references.
+ *
+ * A file of unknown kind is returned unchanged: guessing a comment syntax is
+ * how a real reference gets deleted, and this detector's contract is that it
+ * under-reports rather than accuses.
+ */
+export declare function stripFullLineComments(path: string, content: string): string;
+//# sourceMappingURL=source-refs.d.ts.map