vigiles 16.1.0 → 16.1.2

package/dist/plugin-loader.js

@@ -38,6 +38,7 @@ const node_path_1 = require("node:path");
 const toml_1 = require("@iarna/toml");
 const hash_js_1 = require("./core/hash.js");
 const fs_walk_js_1 = require("./fs-walk.js");
+const source_refs_js_1 = require("./core/source-refs.js");
 const MAX_SKILL_FILE_BYTES = 256 * 1024;
 /** Parse a JSON file, or null on any error (missing / malformed). */
 function safeReadJson(path) {
@@ -319,9 +320,11 @@ function hasMcp(root, layout) {
 }
 // A plugin-relative path reference to a file under a standard surface dir, with a
 // known extension — e.g. a hook script that `cat`s `skills/using-superpowers/SKILL.md`.
-const INTRA_REF_EXTS = "md|sh|cmd|mjs|cjs|js|ts|py|rb|txt|json";
+// The extension vocabulary and BOTH token boundaries live in core/source-refs.ts,
+// so this and its browser twin (scan-files.ts) cannot disagree on them and
+// neither can omit one. See that module for the two boundary defects.
 function intraRefRe(layout) {
-    return new RegExp(`(?:${layout.intraRefDirs.join("|")})/[A-Za-z0-9._/-]+\\.(?:${INTRA_REF_EXTS})`, "g");
+    return (0, source_refs_js_1.intraRefPattern)(layout.intraRefDirs);
 }
 // Shell vars that root a path OUTSIDE the plugin (the user's project / home), so
 // a `surface/…` after one is NOT a plugin-root ref. Anything else ($ROOT,
@@ -340,10 +343,21 @@ const NON_PLUGIN_VARS = new Set([
  * gmickel/flow-next false positive) or a project var (`$CLAUDE_PROJECT_DIR/…`)
  * is NOT a plugin ref. A bare ref (`cat skills/…`) or one after a plugin-root
  * var (`${PLUGIN_ROOT}/skills/…`, obra/superpowers) IS.
+ *
+ * 🔴 THE FIRST QUESTION IS WHETHER THE MATCH STARTS AT A PATH BOUNDARY AT ALL.
+ * "Not preceded by a slash" used to be read as "bare reference", which made
+ * `claude-agents/fable-advisor.md` a bare reference to `agents/fable-advisor.md`
+ * — a resolving path reported broken (`fcakyon/claude-codex-settings`,
+ * 2026-08-17). A preceding path-segment character means the match landed inside
+ * a longer name, which is not a reference to anything.
  */
 function isPluginRooted(content, idx) {
-    if (idx === 0 || content[idx - 1] !== "/")
-        return true; // bare / after quote-space
+    // No `idx === 0` case: start-of-content IS a boundary, and that rule belongs
+    // to `startsAtSeparator` (`idx <= 0 → true`), which the next line reaches with
+    // `content[-1] === undefined`. Restating it here would be a second copy of a
+    // boundary this module deliberately does not own.
+    if (content[idx - 1] !== "/")
+        return (0, source_refs_js_1.startsAtSeparator)(content, idx);
     // The path component immediately before the separating slash.
     const seg = /([^\s"'`(=:/]*)$/.exec(content.slice(0, idx - 1))?.[1] ?? "";
     const varName = /^\$\{?(\w+)\}?$/.exec(seg)?.[1];
@@ -359,27 +373,6 @@ function isPluginRooted(content, idx) {
 // A path in an executable hook/helper script (incl. extensionless ones like
 // obra/superpowers' `hooks/session-start`) IS a real file op — those we scan.
 const DOC_SOURCE_RE = /\.(?:md|markdown|mdx|txt|rst)$/i;
-// A `.sh`/`.bash`/`.cmd` SCRIPT's own `#`-led comments are prose, not code — a
-// usage comment (`# bash skills/<plugin>/hooks/setup.sh`, written as it would be
-// invoked from the REPO CHECKOUT root) is not a real file operation any more than
-// a path mentioned in a doc file is (issue #110). Narrowly scoped to the shell/cmd
-// shapes that conventionally use `#` for a comment (unlike e.g. `.mjs`/`.js`).
-const SCRIPT_COMMENT_RE = /\.(?:sh|bash|cmd)$/i;
-/**
- * Drop FULL-LINE `#` comments (including the shebang, which also starts with
- * `#`) from a `.sh`/`.bash`/`.cmd` script's content before it's scanned for
- * intra-plugin refs — a line whose first non-whitespace character is `#` is
- * prose, never a real command. Full-line only: a `#` inside a quoted string
- * mid-line is left alone, so a genuine ref on a real code line is never
- * dropped. Mirrors `hookBlockIssues`' `stripFullLineComments` discipline
- * (core/hook-block-ineffective.ts).
- */
-function stripShellComments(content) {
-    return content
-        .split("\n")
-        .filter((line) => !line.trimStart().startsWith("#"))
-        .join("\n");
-}
 /**
  * Intra-plugin file references that don't resolve — the partial-vendor / broken-
  * path class (e.g. obra/superpowers' `hooks/session-start` reads
@@ -438,9 +431,10 @@ function executableSources(root, layout) {
         for (const [path, content] of Object.entries(readTree(dir, root))) {
             if (DOC_SOURCE_RE.test(path))
                 continue; // skip prose
-            sources[path] = SCRIPT_COMMENT_RE.test(path)
-                ? stripShellComments(content)
-                : content;
+            // A full-line comment is prose in EVERY language, not only in shell —
+            // both remaining corpus false positives here came out of JSDoc. See
+            // core/source-refs.ts.
+            sources[path] = (0, source_refs_js_1.stripFullLineComments)(path, content);
         }
     }
     return sources;

package/dist/scan-core.js

@@ -45,18 +45,45 @@ const skill_description_budget_js_1 = require("./core/skill-description-budget.j
 const mcp_tool_js_1 = require("./core/mcp-tool.js");
 const lethal_trifecta_js_1 = require("./core/lethal-trifecta.js");
 const skill_resources_js_1 = require("./core/skill-resources.js");
+const bash_effects_js_1 = require("./core/bash-effects.js");
+const source_refs_js_1 = require("./core/source-refs.js");
 const skill_missing_fence_js_1 = require("./core/skill-missing-fence.js");
 const delegation_trifecta_js_1 = require("./core/delegation-trifecta.js");
 const effects_js_1 = require("./core/effects.js");
 const agent_tools_js_1 = require("./adapters/claude-code/agent-tools.js");
-// A script-path token inside a hook command. The token class is `\S` MINUS the
-// glob metacharacters `*` and `?` (dogfood D1): a real, resolvable hook path
-// never contains them, but a command that merely MENTIONS a glob — e.g.
+// A script-path token, matched against a WHOLE shell WORD. The token class is
+// `\S` MINUS the glob metacharacters `*` and `?` (dogfood D1): a real, resolvable
+// hook path never contains them, but a command that merely MENTIONS a glob — e.g.
 // `find . -name "*.js"` in a hook body — would otherwise have `"*.js"` grabbed as
 // a "script" and reported MISSING (a false positive). Shell vars / braces /
-// quotes / slashes ARE kept (`${CLAUDE_PLUGIN_ROOT}/hooks/x.sh`, `"$HOME"/y.sh`),
-// since resolveScript expands + strips those; only glob patterns are dropped.
-const SCRIPT_RE = /[^\s*?]+\.(?:sh|mjs|cjs|js|ts|py|rb)\b/g;
+// slashes ARE kept (`${CLAUDE_PLUGIN_ROOT}/hooks/x.sh`), since resolveScript
+// expands those. See core/source-refs.ts for the boundary rules.
+const SCRIPT_WORD_RE = (0, source_refs_js_1.scriptWordPattern)();
+/**
+ * The script-path operands a hook `command` names.
+ *
+ * 🔴 THE COMMAND IS SHELL, SO IT IS PARSED AS SHELL. This used to run
+ * `SCRIPT_RE` over the raw command string, which cannot tell an operand from
+ * the text of an inline program. Against the standard portable-plugin idiom
+ * `node -e "…await import(…join(root,'hooks','always-on.mjs'))…"` it produced
+ * the script name
+ * `import(require(node:url).pathToFileURL(require(node:path).join(root,hooks,always-on.mjs`
+ * and reported it MISSING, while `hooks/always-on.mjs` sat on disk. Nine such
+ * findings across the 32-repo dogfood corpus (2026-08-17), contributing to two
+ * `F/0` grades.
+ *
+ * `commandWords` returns the words a shell would resolve, with inline program
+ * text subtracted, so the report cannot name a fragment of a JavaScript
+ * expression. A command that does not parse as shell yields `null`, and the
+ * caller treats it as an inline one-liner rather than guessing — abstaining is
+ * the direction that cannot accuse.
+ */
+function scriptTokens(command) {
+    const words = (0, bash_effects_js_1.commandWords)(command);
+    if (words === null)
+        return null;
+    return words.filter((w) => SCRIPT_WORD_RE.test(w));
+}
 // The scalar fields scan reads from a skill/agent `---` block, via the shared
 // lenient reader (core/frontmatter-read.ts) — a real YAML parse with a regex
 // salvage on malformed input, so block scalars / multi-line quoted values parse
@@ -518,7 +545,7 @@ function preferCompiledHooksMessage(count) {
 function eventsByScript(regs) {
     const map = new Map();
     for (const reg of regs) {
-        for (const tok of reg.command.match(SCRIPT_RE) ?? []) {
+        for (const tok of scriptTokens(reg.command) ?? []) {
             if (!map.has(tok))
                 map.set(tok, reg.event);
         }
@@ -537,7 +564,7 @@ function scanHooks(regs, root, pluginRootToken, exists) {
     const byScript = new Map();
     let inline = 0;
     for (const cmd of commands) {
-        const found = cmd.match(SCRIPT_RE);
+        const found = scriptTokens(cmd);
         if (!found || found.length === 0) {
             inline++;
             continue;
@@ -798,13 +825,13 @@ function collectHookBlockEntries(regs, root, pluginRootToken, exists) {
         // A wrapper command runs MORE than one script (`node run.cjs guard.mjs`),
         // so resolve EVERY candidate and inspect each — reading only the first
         // (the wrapper) would miss the guard's block logic. Candidates: extensioned
-        // script tokens (SCRIPT_RE) PLUS path-like words with NO extension
+        // script-shaped words PLUS path-like words with NO extension
         // (`bash hooks/guard`, `${ROOT}/hooks/session-start`) that resolve to a file.
-        const candidates = new Set(cmd.match(SCRIPT_RE) ?? []);
-        for (const word of cmd.split(/\s+/)) {
-            const w = word.replace(/^["']+|["']+$/g, "");
-            if (w.startsWith("-"))
-                continue; // a flag, not a path
+        // Words the SHELL would resolve — not a split on whitespace, which cannot
+        // see quoting and cannot tell `node -e '<program>'` from an operand.
+        const words = (0, bash_effects_js_1.commandWords)(cmd) ?? [];
+        const candidates = new Set(words.filter((w) => SCRIPT_WORD_RE.test(w)));
+        for (const w of words) {
             if (w.includes("/") || w.includes(pluginRootToken))
                 candidates.add(w);
         }

package/dist/scan-files.js

@@ -52,6 +52,7 @@ const hook_block_ineffective_js_1 = require("./core/hook-block-ineffective.js");
 const hook_matcher_js_1 = require("./core/hook-matcher.js");
 const test_coverage_files_js_1 = require("./test-coverage-files.js");
 const coverage_evidence_js_1 = require("./coverage-evidence.js");
+const source_refs_js_1 = require("./core/source-refs.js");
 const scan_core_js_1 = require("./scan-core.js");
 // Zero imports of its own — pure string work, safe in the browser engine.
 const skill_refs_js_1 = require("./skill-refs.js");
@@ -284,9 +285,10 @@ function materializeSurfaces(files, layout, acc, repoName) {
 // ---------------------------------------------------------------------------
 // Dangling intra-plugin refs (mirrors plugin-loader.ts danglingRefs)
 // ---------------------------------------------------------------------------
-const INTRA_REF_EXTS = "md|sh|cmd|mjs|cjs|js|ts|py|rb|txt|json";
+// Extensions + BOTH token boundaries live in core/source-refs.ts, so this and
+// its disk twin (plugin-loader.ts) cannot disagree and neither can omit one.
 function intraRefRe(layout) {
-    return new RegExp(`(?:${layout.intraRefDirs.join("|")})/[A-Za-z0-9._/-]+\\.(?:${INTRA_REF_EXTS})`, "g");
+    return (0, source_refs_js_1.intraRefPattern)(layout.intraRefDirs);
 }
 const NON_PLUGIN_VARS = new Set([
     "CLAUDE_PROJECT_DIR",
@@ -295,10 +297,14 @@ const NON_PLUGIN_VARS = new Set([
     "PWD",
     "OLDPWD",
 ]);
-/** Mirror of plugin-loader.ts `isPluginRooted`. */
+/** Mirror of plugin-loader.ts `isPluginRooted`, including its boundary test:
+ *  a match preceded by a path-segment character landed INSIDE a longer name
+ *  (`claude-agents/`) and refers to nothing. */
 function isPluginRooted(content, idx) {
-    if (idx === 0 || content[idx - 1] !== "/")
-        return true;
+    // Start-of-content is handled by `startsAtSeparator` itself (`idx <= 0`), not
+    // by a guard here — see the twin in plugin-loader.ts.
+    if (content[idx - 1] !== "/")
+        return (0, source_refs_js_1.startsAtSeparator)(content, idx);
     const seg = /([^\s"'`(=:/]*)$/.exec(content.slice(0, idx - 1))?.[1] ?? "";
     const varName = /^\$\{?(\w+)\}?$/.exec(seg)?.[1];
     if (varName !== undefined)
@@ -306,19 +312,6 @@ function isPluginRooted(content, idx) {
     return false;
 }
 const DOC_SOURCE_RE = /\.(?:md|markdown|mdx|txt|rst)$/i;
-// A `.sh`/`.bash`/`.cmd` SCRIPT's own `#`-led comments are prose, not code — a
-// usage comment (`# bash skills/<plugin>/hooks/setup.sh`, written as it would be
-// invoked from the REPO CHECKOUT root) is not a real file operation any more than
-// a path mentioned in a doc file is (issue #110). Mirror of plugin-loader.ts
-// `SCRIPT_COMMENT_RE`.
-const SCRIPT_COMMENT_RE = /\.(?:sh|bash|cmd)$/i;
-/** Mirror of plugin-loader.ts `stripShellComments`. */
-function stripShellComments(content) {
-    return content
-        .split("\n")
-        .filter((line) => !line.trimStart().startsWith("#"))
-        .join("\n");
-}
 /** The plugin's executable (non-prose) source-file CONTENTS under the surface dirs. */
 function executableContents(files, layout) {
     const out = [];
@@ -332,7 +325,8 @@ function executableContents(files, layout) {
                 continue;
             if (byteLen(content) > MAX_SKILL_FILE_BYTES)
                 continue;
-            out.push(SCRIPT_COMMENT_RE.test(k) ? stripShellComments(content) : content);
+            // A full-line comment is prose in EVERY language, not only in shell.
+            out.push((0, source_refs_js_1.stripFullLineComments)(k, content));
         }
     }
     return out;

package/dist/test-coverage-files.js

@@ -184,11 +184,17 @@ function discoverTests(files) {
     }
     return out;
 }
-/** Mirror of test-coverage.ts `isColocated` — named after the surface, beside it. */
+/**
+ * Named after the surface, beside it — the SHARED rule, no longer a copy of it.
+ *
+ * 🔴 THIS WAS A MIRROR, and its own docstring said so. Two bodies, one promise
+ * that they stay equal, kept by whoever remembers — and this file's header
+ * already records the last time a coverage change landed in one engine and not
+ * the other. It now calls `isColocatedTest`, which the disk detector and the
+ * run-record builder call too.
+ */
 function isColocated(surface, testPath) {
-    if (!(0, posix_path_js_1.basename)(testPath).startsWith(`${surface.name}.`))
-        return false;
-    return (0, posix_path_js_1.dirname)(testPath) === (0, posix_path_js_1.dirname)(surface.path);
+    return (0, coverage_evidence_js_1.isColocatedTest)(surface, testPath);
 }
 /** Mirror of test-coverage.ts `coverageOf` — strongest evidence across tests. */
 function coverageOf(surface, tests) {

package/dist/test-coverage.js

@@ -287,12 +287,7 @@ function discoverTests(basePath, globs, ignore) {
  * to remove.
  */
 function isColocated(surface, testPath) {
-    if (!(0, node_path_1.basename)(testPath).startsWith(`${surface.name}.`))
-        return false;
-    // A root `SKILL.md` (single-skill-dir target) lives at ".", and globSync returns
-    // top-level files without a "./" prefix — so `dirname` is "." on both sides and
-    // the comparison holds without a special case.
-    return (0, node_path_1.dirname)(testPath) === (0, node_path_1.dirname)(surface.path);
+    return (0, coverage_evidence_js_1.isColocatedTest)(surface, testPath);
 }
 /**
  * The STRONGEST evidence any discovered test provides for this surface, or null.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vigiles",
-  "version": "16.1.0",
+  "version": "16.1.2",
   "description": "Audit, test and measure the harness your AI agent runs on — grade your CLAUDE.md / AGENTS.md, skills, subagents and hooks, run them against a scripted model, and measure whether they actually fire.",
   "keywords": [
     "claude-code",