vigiles 32.1.1 → 33.1.0

package/dist/hook-install.js

@@ -3,6 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PROVIDERS_DIR = exports.HOOKS_DIR = void 0;
 exports.discoverHookFiles = discoverHookFiles;
 exports.discoverProviderFiles = discoverProviderFiles;
+exports.partitionHookArgs = partitionHookArgs;
+exports.invalidArgMessage = invalidArgMessage;
+exports.discoveredHookArgs = discoveredHookArgs;
+exports.renameCommand = renameCommand;
+exports.unclaimedReport = unclaimedReport;
+exports.unclaimedMessage = unclaimedMessage;
 exports.normalizeHookRef = normalizeHookRef;
 exports.hookRuntimeRef = hookRuntimeRef;
 exports.hookGateRef = hookGateRef;
@@ -17,7 +23,8 @@ exports.serializeConfig = serializeConfig;
  * The typed hook program is harness-NEUTRAL — it imports `vigiles/hook` and
  * compiles to whatever harness — so its SOURCE lives in the agnostic,
  * committed {@link HOOKS_DIR} (`.vigiles/hooks/`), never in a harness's own
- * `.claude/`. `compile` discovers each hook there, compiles it, and MERGES the
+ * `.claude/`. `compile` discovers each hook there — a hook is a `.hook.` file
+ * and nothing else, decided by `source-kinds.ts` — compiles it, and MERGES the
  * result into the active harness's native config (`.claude/settings.json` JSON
  * / `config.toml` TOML) — so the harness is actually wired, not handed a
  * paste-this block. The merge is idempotent: an entry is keyed by the runtime
@@ -29,6 +36,7 @@ exports.serializeConfig = serializeConfig;
  */
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const source_kinds_js_1 = require("./source-kinds.js");
 /**
  * Lazy for the same reason as in `core/hook-program.ts` — and this module is
  * reached from the hook runtime through `hook-state-store.ts` (`normalizeHookRef`),
@@ -40,25 +48,218 @@ const stringifyToml = (value) => require("@iarna/toml").stringify(value);
 exports.HOOKS_DIR = ".vigiles/hooks";
 /** The committed home for registered context-provider SOURCE (v2). */
 exports.PROVIDERS_DIR = ".vigiles/providers";
-/** A JS/TS hook source file (the `.json` stamp sidecar is never matched). */
-const HOOK_SOURCE_RE = /\.(?:mjs|cjs|js|mts|cts|ts)$/;
-/** List JS/TS source files under `dir` (relative to cwd), stamps excluded. */
-function discoverSources(cwd, dir) {
+/**
+ * The ONE place a directory's role meets {@link SourceKind}. The `switch` is
+ * exhaustive, so a kind added to the table in `source-kinds.ts` is a compile
+ * error here until someone decides what hooks and providers do with it.
+ *
+ * `leave` is for files that are in these directories on purpose and are none of
+ * `compile`'s business: tests, declarations, stamps, a README.
+ */
+function claimOf(role, found) {
+    switch (found.kind) {
+        case "hook":
+        case "provider":
+            // A provider in the hooks directory is as unclaimed as a stray helper:
+            // nothing here would ever load it, and saying so beats a silent miss.
+            return found.kind === role ? "claim" : "refuse";
+        case "unclaimed":
+            return "refuse";
+        case "vigiles-test":
+        case "declaration":
+        case "stamp":
+        case "non-source":
+            return "leave";
+    }
+}
+/** List the files under `dir` (relative to cwd), split by what `role` does with each. */
+function discoverSources(cwd, dir, role) {
     const abs = (0, node_path_1.join)(cwd, dir);
     if (!(0, node_fs_1.existsSync)(abs))
-        return [];
-    return (0, node_fs_1.readdirSync)(abs)
-        .filter((f) => HOOK_SOURCE_RE.test(f) && !f.endsWith(".d.ts"))
+        return { claimed: [], unclaimed: [] };
+    const verdicts = (0, node_fs_1.readdirSync)(abs)
         .sort()
-        .map((f) => (0, node_path_1.join)(dir, f));
+        .map((f) => ({
+        path: (0, node_path_1.join)(dir, f),
+        claim: claimOf(role, (0, source_kinds_js_1.classifySource)(f)),
+    }));
+    const pick = (want) => verdicts.filter((v) => v.claim === want).map((v) => v.path);
+    return { claimed: pick("claim"), unclaimed: pick("refuse") };
 }
-/** Discover hook source files under {@link HOOKS_DIR} (stamps excluded). */
+/** Discover hook sources under {@link HOOKS_DIR}: `.hook.` files, and the runnable files that are nobody's. */
 function discoverHookFiles(cwd) {
-    return discoverSources(cwd, exports.HOOKS_DIR);
+    return discoverSources(cwd, exports.HOOKS_DIR, "hook");
 }
-/** Discover registered-provider source files under {@link PROVIDERS_DIR}. */
+/** Discover registered-provider sources under {@link PROVIDERS_DIR}. */
 function discoverProviderFiles(cwd) {
-    return discoverSources(cwd, exports.PROVIDERS_DIR);
+    return discoverSources(cwd, exports.PROVIDERS_DIR, "provider");
+}
+const realProbe = (path) => {
+    const st = (0, node_fs_1.statSync)((0, node_path_1.resolve)(process.cwd(), path), { throwIfNoEntry: false });
+    if (st === undefined)
+        return "missing";
+    return st.isFile() ? "file" : st.isDirectory() ? "directory" : "other";
+};
+/** Is `path` directly inside `dir` (a repo-relative POSIX dir), either separator, any prefix? */
+function insideDir(path, dir) {
+    const parent = (0, source_kinds_js_1.dirName)(path)
+        .replace(/\\/g, "/")
+        .replace(/\/$/, "")
+        .replace(/^\.\//, "");
+    return parent === dir || parent.endsWith(`/${dir}`);
+}
+/**
+ * Sort explicit `compile` arguments by the same classifier discovery uses, so
+ * `compile guard.mjs` and a bare `compile` give the same answer about it — for a
+ * path ANYWHERE, not just under `.vigiles/hooks/`: `compile .claude/hooks/x.mjs`
+ * or a plugin's `hooks/guard.mjs` is refused unless it carries `.hook.`.
+ *
+ * A path that is missing, a directory or not a regular file is an error (it used
+ * to fail, and the first version of the marker rule turned it into a green run).
+ * The one lenient case exists for a shell glob (`compile .vigiles/hooks/*`): a
+ * test, declaration or stamp is reported as skipped, and so is a README or
+ * `.gitkeep` — but only inside the two vigiles source directories, where a glob
+ * would sweep one up. A `/etc/passwd` is not a README.
+ */
+function partitionHookArgs(args, probe = realProbe) {
+    const hooks = [];
+    const unclaimed = [];
+    const skipped = [];
+    const invalid = [];
+    for (const path of args) {
+        const what = probe(path);
+        if (what === "missing" || what === "directory") {
+            invalid.push({ path, reason: what });
+            continue;
+        }
+        if (what === "other") {
+            invalid.push({ path, reason: "not-a-source" });
+            continue;
+        }
+        const found = (0, source_kinds_js_1.classifySource)((0, source_kinds_js_1.baseName)(path));
+        switch (found.kind) {
+            case "hook":
+                hooks.push(path);
+                break;
+            case "unclaimed":
+                unclaimed.push(path);
+                break;
+            case "provider":
+                // Valid, and compile validates providers whenever it compiles a hook —
+                // except in the hooks directory, where nothing would ever load it.
+                if (insideDir(path, exports.HOOKS_DIR))
+                    unclaimed.push(path);
+                else
+                    skipped.push({ path, kind: found.kind });
+                break;
+            case "vigiles-test":
+            case "declaration":
+            case "stamp":
+                skipped.push({ path, kind: found.kind });
+                break;
+            case "non-source":
+                if (insideDir(path, exports.HOOKS_DIR) || insideDir(path, exports.PROVIDERS_DIR))
+                    skipped.push({ path, kind: found.kind });
+                else
+                    invalid.push({ path, reason: "not-a-source" });
+                break;
+        }
+    }
+    return { hooks, unclaimed, skipped, invalid };
+}
+/** The line `compile` prints for an argument it cannot treat as a hook source at all. */
+function invalidArgMessage(path, reason) {
+    switch (reason) {
+        case "missing":
+            return `${path} — no such file.`;
+        case "directory":
+            return `${path} — is a directory. Name hook files, or run \`vigiles compile\` with no arguments to discover them.`;
+        case "not-a-source":
+            return `${path} — not a hook source (a hook is a \`<name>.hook.<ext>\` file).`;
+    }
+}
+/**
+ * Discovery, shaped like {@link partitionHookArgs}'s answer, so `compile` handles
+ * "no arguments" and "these paths" through one code path afterwards.
+ */
+function discoveredHookArgs(cwd) {
+    const { claimed, unclaimed } = discoverHookFiles(cwd);
+    return { hooks: claimed, unclaimed, skipped: [], invalid: [] };
+}
+/** POSIX single-quote one word: safe for any file name, a newline and `$(…)` included. */
+const shq = (word) => `'${word.replace(/'/g, `'\\''`)}'`;
+/**
+ * The ONE shell command that renames an unclaimed file to its marked name and
+ * (for a hook) recompiles it. Every path is single-quoted: this is printed by a
+ * tool and pasted by a person, and a repository can plant a file name that is a
+ * command.
+ *
+ * 🔴 THE HOOK COMMAND COPIES FIRST AND DELETES LAST, and that order is the
+ * point. Already-wired hooks keep running after an upgrade: the runtime loads
+ * whatever path `settings.json` names, and never asks what a file is called. So
+ * the break is the NEXT compile, and a plain `mv` + `compile` has one bad
+ * moment — the old path is gone and the wiring still names it. For a gate
+ * wired `|| exit 2` that is a hook that cannot load, which blocks every Bash
+ * call (the repair is a file write, not a command). Compiling the renamed copy
+ * while the old file still exists, and deleting the old one only after that
+ * compile succeeded, has no such moment: if anything fails the old hook is
+ * still on disk and still wired. `compile` replaces the old wiring itself
+ * ({@link ownedRefs}), so nothing is left naming the deleted path.
+ *
+ * 🔴 `cp -n`, because the marked name may already exist: a plain `cp` replaced
+ * an edited `guard.hook.mjs` with the stale `guard.mjs`, and the weaker hook
+ * became the wired gate. {@link unclaimedMessage} checks first and prints no
+ * command at all in that case; `-n` is for the file that appears in between.
+ */
+function renameCommand(path, role) {
+    const target = (0, source_kinds_js_1.markedName)(path, role);
+    switch (role) {
+        case "hook":
+            return (`cp -n -- ${shq(path)} ${shq(target)} && ` +
+                `npx vigiles compile ${shq(target)} && ` +
+                `rm -f -- ${shq(path)} ${shq(`${exports.HOOKS_DIR}/${(0, node_path_1.basename)(path)}.json`)}`);
+        case "provider":
+            return `mv -n -- ${shq(path)} ${shq(target)}`;
+    }
+}
+/**
+ * {@link unclaimedMessage} with the one fact it cannot know, read off the disk:
+ * whether the marked name is already there.
+ */
+function unclaimedReport(path, role, cwd = process.cwd()) {
+    return unclaimedMessage(path, role, (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, (0, source_kinds_js_1.markedName)(path, role))));
+}
+/**
+ * The text `compile` prints for one file it will not compile, with the exact
+ * command to fix it. `targetExists` is whether the marked name is already on
+ * disk: then there is nothing safe to copy, and the message says to merge by
+ * hand instead.
+ */
+function unclaimedMessage(path, role, targetExists = false) {
+    const dir = (0, source_kinds_js_1.dirName)(path);
+    const target = (0, source_kinds_js_1.markedName)(path, role);
+    const found = (0, source_kinds_js_1.classifySource)((0, source_kinds_js_1.baseName)(path)).kind;
+    const head = `${path} — not compiled: a ${role} source must carry \`.${role}.\` before its extension (${(0, source_kinds_js_1.baseName)(target)}), and this name carries no marker vigiles knows.`;
+    const misplaced = found === "provider" || found === "hook"
+        ? `  It is marked as a ${found}, which belongs in ${found === "hook" ? exports.HOOKS_DIR : exports.PROVIDERS_DIR}/ — move it there.`
+        : undefined;
+    const notIt = `  If it is not a ${role}, move it out of ${dir || "this directory"} — a test belongs in a \`.harness.\` or \`.eval.\` file.`;
+    if (misplaced !== undefined)
+        return [head, misplaced].join("\n");
+    if (targetExists)
+        return [
+            head,
+            `  ${target} already exists beside it, so nothing is printed that could overwrite it. If ${path} is the ${role}, compare the two by hand, keep the content you want in ${target}, delete ${path}${role === "hook" ? ` and its stamp, and run \`npx vigiles compile ${target}\`` : ""}.`,
+            notIt,
+        ].join("\n");
+    return [
+        head,
+        role === "hook"
+            ? `  If it is a hook, rename it. Copy first and delete last, so a failure leaves the old hook in place and wired:`
+            : `  If it is a provider, rename it (providers are found by directory, never wired by path):`,
+        `    ${renameCommand(path, role)}`,
+        notIt,
+    ].join("\n");
 }
 /**
  * The CANONICAL form of a hook-source reference — how the path is written into
@@ -126,7 +327,25 @@ function hookGateRef(ref, projectRootTokens) {
     return token === undefined ? ref : `"${token}/${ref}"`;
 }
 /**
- * True when an entry's command routes through the runtime for `hookPath`.
+ * The wiring references a hook file owns: its own, and — for `x.hook.ts` — the
+ * one an older vigiles wrote when the file was still called `x.ts`.
+ *
+ * 🔴 WITHOUT THE SECOND, RENAMING A HOOK TO CARRY ITS MARKER LEAVES A DEAD ENTRY.
+ * Wiring is keyed by path, so compiling `guard.hook.mjs` appended a new entry and
+ * left the one for `guard.mjs` in `settings.json`, pointing at a file that is
+ * about to be deleted. That entry cannot load; wired as a gate it blocks every
+ * Bash call, the repair included (see {@link unclaimedMessage}). The marker rename
+ * is the one rename vigiles itself asks of every consumer, so it is the one the
+ * merge is told about: the renamed file takes over the old file's wiring.
+ */
+function ownedRefs(hookPath) {
+    const ref = normalizeHookRef(hookPath);
+    const before = (0, source_kinds_js_1.preMarkerName)(ref, "hook");
+    return before === undefined ? [ref] : [ref, before];
+}
+/**
+ * True when an entry's command routes through the runtime for `hookPath`
+ * (or for the name it had before it carried its marker, see {@link ownedRefs}).
  *
  * Compares CANONICALIZED path tokens rather than testing for a raw substring:
  * `./x.hook.ts` and `x.hook.ts` are the same file (so the entry is replaced,
@@ -134,10 +353,10 @@ function hookGateRef(ref, projectRootTokens) {
  * `x.hook.ts` and `my-x.hook.ts` are not (a substring test said they were).
  */
 function managesHook(entry, hookPath) {
-    const ref = normalizeHookRef(hookPath);
+    const refs = ownedRefs(hookPath);
     return entry.hooks.some((h) => h.command.split(/\s+/).some((token) => {
         const bare = bareToken(token);
-        return bare !== "" && normalizeHookRef(bare) === ref;
+        return bare !== "" && refs.includes(normalizeHookRef(bare));
     }));
 }
 /**

package/dist/hook-runtime.d.ts

@@ -44,7 +44,7 @@ import { loadHook } from "./load-hook.js";
  * loads in a test loads identically here (one loader, no drift).
  */
 export declare const loadHookProgram: typeof loadHook;
-/** Load a registered provider (`.vigiles/providers/<name>`) → its definition. */
+/** Load a registered provider (`.vigiles/providers/<name>.provider.<ext>`) → its definition. */
 export declare function loadProvider(file: string, root?: string): Promise<RegisteredProvider>;
 /** Path of the tamper-evident stamp sidecar for a hook file. */
 export declare function hookStampPath(file: string, root?: string): string;

package/dist/hook-runtime.js

@@ -75,7 +75,7 @@ function injectableEventsFor(root) {
  * loads in a test loads identically here (one loader, no drift).
  */
 exports.loadHookProgram = load_hook_js_1.loadHook;
-/** Load a registered provider (`.vigiles/providers/<name>`) → its definition. */
+/** Load a registered provider (`.vigiles/providers/<name>.provider.<ext>`) → its definition. */
 async function loadProvider(file, root = process.cwd()) {
     const abs = (0, node_path_1.resolve)(root, file);
     const { pathToFileURL } = require("node:url");
@@ -155,7 +155,13 @@ async function gatherHookContext(program, file, root) {
  */
 async function loadProviderRegistry(root) {
     const registry = {};
-    for (const file of (0, hook_install_js_1.discoverProviderFiles)(root)) {
+    // Tolerant on purpose, unlike `compile`: a provider file written before the
+    // `.provider.` marker existed is `unclaimed`, and a hook compiled yesterday
+    // still resolves `provider("x")` against it today. `compile` refuses such a
+    // file out loud; the runtime must not turn that into a silently empty value
+    // for a hook already wired. Tests and declarations are never loaded.
+    const { claimed, unclaimed } = (0, hook_install_js_1.discoverProviderFiles)(root);
+    for (const file of [...claimed, ...unclaimed]) {
         try {
             const def = await loadProvider(file, root);
             registry[def.name] = def;

package/dist/hook-state-store.d.ts

@@ -91,7 +91,7 @@ export interface HookStateHandle {
      * OLD fact, and "old" is not something a test can produce by waiting.
      *
      * ```js
-     * const st = experimental_hookState(".vigiles/hooks/nag.mjs", { cwd });
+     * const st = experimental_hookState(".vigiles/hooks/nag.hook.mjs", { cwd });
      * st.seed("retro.nagged", { ago: "4d" });   // → the hook speaks
      * st.seed("retro.nagged", { ago: "10m" });  // → the hook stays quiet
      * ```

package/dist/hook.js

@@ -143,7 +143,7 @@ Object.defineProperty(exports, "HookStateError", { enumerable: true, get: functi
 // and `pipesToShell()` match over, so a guard written against the closed
 // vocabulary sees the OPERATION rather than the literal tokens.
 //
-// It is exported because `examples/harness/safe-bash-guard-v2.mjs` needs it —
+// It is exported because `examples/harness/safe-bash-guard-v2.hook.mjs` needs it —
 // and that need is the finding, not the feature. v2 is an UNRUN experiment (no
 // test executes it) covering three things the vocabulary cannot yet express: a
 // flag with a value (`--index-url`), an env-assignment prefix, and a

package/dist/load-hook.d.ts

@@ -10,7 +10,7 @@ import { type AnyHook } from "./core/hook-program.js";
  * ```js
  * import { loadHook, assertHookDenies } from "vigiles";
  *
- * const guard = await loadHook(".vigiles/hooks/guard.mjs");
+ * const guard = await loadHook(".vigiles/hooks/guard.hook.mjs");
  * assertHookDenies(guard, {
  *   tool_name: "Bash",
  *   tool_input: { command: "git push --force" },

package/dist/load-hook.js

@@ -29,7 +29,7 @@ const hook_program_js_1 = require("./core/hook-program.js");
  * ```js
  * import { loadHook, assertHookDenies } from "vigiles";
  *
- * const guard = await loadHook(".vigiles/hooks/guard.mjs");
+ * const guard = await loadHook(".vigiles/hooks/guard.hook.mjs");
  * assertHookDenies(guard, {
  *   tool_name: "Bash",
  *   tool_input: { command: "git push --force" },

package/dist/source-kinds.d.ts

@@ -0,0 +1,128 @@
+/**
+ * What a file in a vigiles-owned source directory IS — decided in ONE place.
+ *
+ * `.vigiles/hooks/` and `.vigiles/providers/` hold several kinds of file side by
+ * side: the programs `vigiles compile` turns into wiring, the tests that exercise
+ * them, type declarations, and the `.json` stamp `compile` writes next to each
+ * hook. Discovery used to ask "does it end in a runnable extension?" and treat
+ * every yes as a hook (#278): a `task-list-nudge.harness.mjs` beside its
+ * `task-list-nudge.hook.ts` was compiled as a hook and failed the build. The
+ * obvious patch — subtract the names that bit (`.harness.`, `.test.`) — is a list
+ * of what a hook is NOT, and a list of that kind is open: the next helper file
+ * somebody colocates is the next report.
+ *
+ * So a hook is defined by what it IS. A file's kind comes from ONE marker, the
+ * LAST dot-separated segment before the extension (`guard.hook.mjs` → `hook`),
+ * looked up in ONE table ({@link MARKERS}). Because exactly one segment decides,
+ * a name has exactly one kind; because the table is closed, every consumer can
+ * `switch` over {@link SourceKind} exhaustively and the compiler names the next
+ * one that forgets a case. A runnable file whose marker is not in the table is
+ * `unclaimed` — a kind of its own, not an absence — so a renamed-away hook is a
+ * reported fact rather than a silent hole.
+ *
+ * The patterns test discovery uses (`vigiles test`, `vigiles eval`, the coverage
+ * defaults, the browser twin) are DERIVED from the same table. They used to be
+ * five hand-kept copies of one fact: `*.harness.*` and `*.eval.*` are tests.
+ *
+ * Pure and import-free on purpose. `hook-install.ts` imports this and is reached
+ * from the hook runtime, where every module is a per-call cost, and the browser
+ * twin of coverage detection needs it too — nothing here may touch `node:*`.
+ */
+/**
+ * Every extension Node executes directly. `.mts`/`.cts` are real (TS 4.7+) and
+ * Node 22 strips their types with no toolchain — measured, not assumed.
+ */
+export declare const RUNNABLE_EXTS: readonly ["mjs", "cjs", "js", "mts", "cts", "ts"];
+/** Which vigiles test runner takes a file: `vigiles test` or `vigiles eval`. */
+export type TestTier = "harness" | "eval";
+/**
+ * The closed union of what a file in a source directory can be. Exactly one per
+ * name; see {@link classifySource}.
+ */
+export type SourceKind = 
+/** A compiled-hook program: `guard.hook.mjs`. */
+{
+    readonly kind: "hook";
+}
+/** A registered context provider: `k8s.provider.mjs`. */
+ | {
+    readonly kind: "provider";
+}
+/** A vigiles test: `guard.harness.mjs` (`vigiles test`) or `guard.eval.mjs` (`vigiles eval`). */
+ | {
+    readonly kind: "vigiles-test";
+    readonly test: TestTier;
+}
+/** A type declaration: `x.d.ts`, `x.d.mts`, `x.d.cts`. */
+ | {
+    readonly kind: "declaration";
+}
+/** The `.json` sidecar `compile` writes beside a source: `guard.hook.mjs.json`. */
+ | {
+    readonly kind: "stamp";
+}
+/** Not a runnable source at all: `README.md`, `.gitkeep`, a stray `.json`. */
+ | {
+    readonly kind: "non-source";
+}
+/**
+ * A runnable file whose name carries no marker vigiles knows: `guard.mjs`
+ * (a hook from before the marker), `util.ts`, `guard.test.ts`. Nobody's — and
+ * therefore never compiled, and never silently ignored either.
+ */
+ | {
+    readonly kind: "unclaimed";
+};
+/** The markers that name a file a vigiles consumer COMPILES (as opposed to runs or ignores). */
+export type CompilableMarker = "hook" | "provider";
+/**
+ * The kind of a file, from its BASENAME. Total: every string has an answer, and
+ * the answer is one member of {@link SourceKind}.
+ *
+ * Order matters and is the whole algorithm: a declaration is a declaration even
+ * when its infix says `hook` (`x.hook.d.ts`); a `.json` beside a source is its
+ * stamp; then the last infix is looked up. Case-sensitive, like the file systems
+ * these names mostly live on.
+ */
+export declare function classifySource(filename: string): SourceKind;
+/**
+ * Is this basename an eval script — the PAID tier, the one that spends real
+ * model calls? It decides which of two runners owns a test file, and has been
+ * wrong in both directions:
+ *
+ * - As the full suffix `.eval.mjs`: `foo.eval.ts` fell into the free branch and
+ *   would have spent real model calls on every push.
+ * - As the bare INFIX `.eval.`: `parser.eval.test.ts`, an ordinary deterministic
+ *   test, was credited to the paid tier and dropped from the free one — though
+ *   `vigiles eval` cannot discover that name at all.
+ *
+ * The answer that is wrong in neither direction is the runner's own: `.eval.`
+ * followed by a runnable extension AT THE END of the name, which is exactly what
+ * the last-infix rule of {@link classifySource} says.
+ *
+ * @param filename a BASENAME — callers strip the directory with their own path
+ * helper (`node:path` on disk, `posix-path` in the browser twin).
+ */
+export declare function isEvalScript(filename: string): boolean;
+/** Is this basename a vigiles test of either tier? */
+export declare function isVigilesTest(filename: string): boolean;
+/** The glob `vigiles test` / `vigiles eval` discover a tier's scripts with. */
+export declare function testGlob(tier: TestTier): string;
+/** The patterns coverage credits tests with by default — one per tier, from the table. */
+export declare const DEFAULT_TEST_GLOBS: readonly string[];
+/** The last path segment, whichever separator precedes it. */
+export declare const baseName: (path: string) => string;
+/** Everything up to and including the last separator, or "" when there is none. */
+export declare const dirName: (path: string) => string;
+/**
+ * `guard.mjs` → `guard.hook.mjs`: the name a file must carry to be claimed as
+ * `marker`. Keeps the directory. The inverse of {@link preMarkerName}.
+ */
+export declare function markedName(path: string, marker: CompilableMarker): string;
+/**
+ * `guard.hook.mjs` → `guard.mjs`: the name a file carried before the marker
+ * existed, or `undefined` when the name has no such marker. Used to recognise
+ * the wiring an older vigiles wrote for the same file.
+ */
+export declare function preMarkerName(path: string, marker: CompilableMarker): string | undefined;
+//# sourceMappingURL=source-kinds.d.ts.map

package/dist/source-kinds.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * What a file in a vigiles-owned source directory IS — decided in ONE place.
+ *
+ * `.vigiles/hooks/` and `.vigiles/providers/` hold several kinds of file side by
+ * side: the programs `vigiles compile` turns into wiring, the tests that exercise
+ * them, type declarations, and the `.json` stamp `compile` writes next to each
+ * hook. Discovery used to ask "does it end in a runnable extension?" and treat
+ * every yes as a hook (#278): a `task-list-nudge.harness.mjs` beside its
+ * `task-list-nudge.hook.ts` was compiled as a hook and failed the build. The
+ * obvious patch — subtract the names that bit (`.harness.`, `.test.`) — is a list
+ * of what a hook is NOT, and a list of that kind is open: the next helper file
+ * somebody colocates is the next report.
+ *
+ * So a hook is defined by what it IS. A file's kind comes from ONE marker, the
+ * LAST dot-separated segment before the extension (`guard.hook.mjs` → `hook`),
+ * looked up in ONE table ({@link MARKERS}). Because exactly one segment decides,
+ * a name has exactly one kind; because the table is closed, every consumer can
+ * `switch` over {@link SourceKind} exhaustively and the compiler names the next
+ * one that forgets a case. A runnable file whose marker is not in the table is
+ * `unclaimed` — a kind of its own, not an absence — so a renamed-away hook is a
+ * reported fact rather than a silent hole.
+ *
+ * The patterns test discovery uses (`vigiles test`, `vigiles eval`, the coverage
+ * defaults, the browser twin) are DERIVED from the same table. They used to be
+ * five hand-kept copies of one fact: `*.harness.*` and `*.eval.*` are tests.
+ *
+ * Pure and import-free on purpose. `hook-install.ts` imports this and is reached
+ * from the hook runtime, where every module is a per-call cost, and the browser
+ * twin of coverage detection needs it too — nothing here may touch `node:*`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dirName = exports.baseName = exports.DEFAULT_TEST_GLOBS = exports.RUNNABLE_EXTS = void 0;
+exports.classifySource = classifySource;
+exports.isEvalScript = isEvalScript;
+exports.isVigilesTest = isVigilesTest;
+exports.testGlob = testGlob;
+exports.markedName = markedName;
+exports.preMarkerName = preMarkerName;
+/**
+ * Every extension Node executes directly. `.mts`/`.cts` are real (TS 4.7+) and
+ * Node 22 strips their types with no toolchain — measured, not assumed.
+ */
+exports.RUNNABLE_EXTS = ["mjs", "cjs", "js", "mts", "cts", "ts"];
+/**
+ * The marker table: the LAST dot-segment before the extension → its kind.
+ * Adding a kind of file means adding a row here and handling the new
+ * {@link SourceKind} member in each consumer's `switch`.
+ */
+const MARKERS = [
+    { infix: "hook", kind: { kind: "hook" } },
+    { infix: "provider", kind: { kind: "provider" } },
+    { infix: "harness", kind: { kind: "vigiles-test", test: "harness" } },
+    { infix: "eval", kind: { kind: "vigiles-test", test: "eval" } },
+];
+/**
+ * The tiers a vigiles test can belong to, read off {@link MARKERS}. A tier is
+ * also its own infix (`guard.eval.mjs` is tier `eval`): `source-kinds.test.ts`
+ * asserts that for every tier, so a row that broke it fails there.
+ */
+const TEST_TIERS = MARKERS.flatMap((m) => m.kind.kind === "vigiles-test" ? [m.kind.test] : []);
+const EXT_ALT = exports.RUNNABLE_EXTS.join("|");
+const DECLARATION = /\.d\.(?:ts|mts|cts)$/;
+const STAMP = new RegExp(`\\.(?:${EXT_ALT})\\.json$`);
+/**
+ * `<stem>.<infix>.<ext>`, the infix being the LAST segment before the extension.
+ * The stem may be empty (`.harness.mjs`): the runner's glob matches that, so the
+ * classifier must too; {@link classifySource} decides which kinds may go without
+ * one. `[\\s\\S]`, not `.`: `.` stops at a newline, and a name with one in it
+ * used to fall out of every kind and be dropped without a word.
+ */
+const MARKED = new RegExp(`^([\\s\\S]*)\\.([^.]+)\\.(?:${EXT_ALT})$`);
+const RUNNABLE = new RegExp(`^[\\s\\S]+\\.(?:${EXT_ALT})$`);
+const UNCLAIMED = { kind: "unclaimed" };
+/**
+ * The kind of a file, from its BASENAME. Total: every string has an answer, and
+ * the answer is one member of {@link SourceKind}.
+ *
+ * Order matters and is the whole algorithm: a declaration is a declaration even
+ * when its infix says `hook` (`x.hook.d.ts`); a `.json` beside a source is its
+ * stamp; then the last infix is looked up. Case-sensitive, like the file systems
+ * these names mostly live on.
+ */
+function classifySource(filename) {
+    if (DECLARATION.test(filename))
+        return { kind: "declaration" };
+    if (STAMP.test(filename))
+        return { kind: "stamp" };
+    if (!RUNNABLE.test(filename))
+        return { kind: "non-source" };
+    const parts = MARKED.exec(filename);
+    const row = MARKERS.find((m) => m.infix === parts?.[2]);
+    if (row === undefined)
+        return UNCLAIMED;
+    // A test needs no name to be run (`vigiles test` finds `.harness.mjs`); a hook
+    // or a provider must be nameable, so a stemless one is nobody's.
+    return parts?.[1] === "" && row.kind.kind !== "vigiles-test"
+        ? UNCLAIMED
+        : row.kind;
+}
+/**
+ * Is this basename an eval script — the PAID tier, the one that spends real
+ * model calls? It decides which of two runners owns a test file, and has been
+ * wrong in both directions:
+ *
+ * - As the full suffix `.eval.mjs`: `foo.eval.ts` fell into the free branch and
+ *   would have spent real model calls on every push.
+ * - As the bare INFIX `.eval.`: `parser.eval.test.ts`, an ordinary deterministic
+ *   test, was credited to the paid tier and dropped from the free one — though
+ *   `vigiles eval` cannot discover that name at all.
+ *
+ * The answer that is wrong in neither direction is the runner's own: `.eval.`
+ * followed by a runnable extension AT THE END of the name, which is exactly what
+ * the last-infix rule of {@link classifySource} says.
+ *
+ * @param filename a BASENAME — callers strip the directory with their own path
+ * helper (`node:path` on disk, `posix-path` in the browser twin).
+ */
+function isEvalScript(filename) {
+    const k = classifySource(filename);
+    return k.kind === "vigiles-test" && k.test === "eval";
+}
+/** Is this basename a vigiles test of either tier? */
+function isVigilesTest(filename) {
+    return classifySource(filename).kind === "vigiles-test";
+}
+/** The glob `vigiles test` / `vigiles eval` discover a tier's scripts with. */
+function testGlob(tier) {
+    return `**/*.${tier}.{${exports.RUNNABLE_EXTS.join(",")}}`;
+}
+/** The patterns coverage credits tests with by default — one per tier, from the table. */
+exports.DEFAULT_TEST_GLOBS = TEST_TIERS.map(testGlob);
+/** Split at the last directory separator — either one, so a Windows path works too. */
+const splitDir = (path) => {
+    const cut = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\")) + 1;
+    return [path.slice(0, cut), path.slice(cut)];
+};
+/** The last path segment, whichever separator precedes it. */
+const baseName = (path) => splitDir(path)[1];
+exports.baseName = baseName;
+/** Everything up to and including the last separator, or "" when there is none. */
+const dirName = (path) => splitDir(path)[0];
+exports.dirName = dirName;
+/**
+ * `guard.mjs` → `guard.hook.mjs`: the name a file must carry to be claimed as
+ * `marker`. Keeps the directory. The inverse of {@link preMarkerName}.
+ */
+function markedName(path, marker) {
+    const [dir, base] = splitDir(path);
+    return dir + base.replace(/\.([^.]+)$/, `.${marker}.$1`);
+}
+/**
+ * `guard.hook.mjs` → `guard.mjs`: the name a file carried before the marker
+ * existed, or `undefined` when the name has no such marker. Used to recognise
+ * the wiring an older vigiles wrote for the same file.
+ */
+function preMarkerName(path, marker) {
+    const [dir, base] = splitDir(path);
+    const m = new RegExp(`^([\\s\\S]+)\\.${marker}\\.(${EXT_ALT})$`).exec(base);
+    return m === null ? undefined : `${dir}${m[1]}.${m[2]}`;
+}
+//# sourceMappingURL=source-kinds.js.map