vigiles 32.0.2 → 32.1.1

package/dist/core/instruction-baseline.js

@@ -0,0 +1,224 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INSTRUCTION_WEIGHT_MEASURE = exports.INSTRUCTION_BASELINE_VERSION = exports.UPDATE_BASELINE_COMMAND = exports.INSTRUCTION_BASELINE_FILE = void 0;
+exports.parseInstructionBaseline = parseInstructionBaseline;
+exports.entryFor = entryFor;
+exports.compareToBaseline = compareToBaseline;
+exports.recordEntries = recordEntries;
+exports.serializeBaseline = serializeBaseline;
+exports.formatVerdict = formatVerdict;
+exports.formatWeightLine = formatWeightLine;
+/**
+ * The instruction-weight RATCHET: the always-loaded weight may not grow past
+ * what the repository itself last recorded.
+ *
+ * WHY A RATCHET AND NOT THE BUDGET. `./instruction-weight.ts` explains why the
+ * harness's own threshold cannot gate: real repositories sit several times over
+ * it, and a rule that fails every repo on day one is switched off on day one.
+ * What CAN gate is the repository's own past. The baseline is whatever the repo
+ * weighed when it was last recorded, so a repo four times over budget starts
+ * green — and stays green only while it does not get heavier. The measured case
+ * this exists for: a root instruction file cut from ~4 100 lines to ~1 900, then
+ * regrown by ~1 000 lines over ten ordinary commits, with nothing in CI to say so.
+ *
+ * WHY THE SUM, AGAIN. The baseline records `committedTotal`, the same number the
+ * audit report scores: everything the harness loads without being asked that a
+ * teammate on the same commit also loads. A per-file baseline would read text
+ * moved into an always-loaded sibling as a shrink — the evasion the weight
+ * module was built to see through. The per-file sizes are recorded too, but only
+ * so a message can say WHICH file moved; the verdict is decided on the total.
+ *
+ * WHY A SHRINK IS A FINDING TOO. A baseline left above the tree is headroom, and
+ * headroom is exactly where the regrowth above landed: every character up to the
+ * old number would pass. So, like ESLint's unpruned suppressions and `betterer
+ * ci`, a tree LIGHTER than its baseline asks for the baseline to be lowered —
+ * one command, in the same change that made the cut. The baseline then always
+ * equals the tree on the default branch, and any growth at all is a diff a
+ * reviewer sees.
+ *
+ * WHO WRITES IT. Never `lint` on its own: a read never writes. The file is
+ * written only by the explicit `vigiles lint --update-baseline`, the same shape
+ * as `eslint --suppress-all` / `--prune-suppressions` and `jest -u`. Raising the
+ * baseline is allowed and is the point: growth is not forbidden, it is made
+ * visible as a reviewed diff of a committed file.
+ *
+ * Pure: parsing, comparison and formatting only. Reading and writing the file
+ * is the caller's (`src/instruction-weight-ratchet.ts`).
+ */
+const zod_1 = require("zod");
+/** Where the baseline lives, relative to the directory `.vigilesrc.json` is read from. */
+exports.INSTRUCTION_BASELINE_FILE = ".vigiles/instruction-weight.json";
+/** The command that writes the baseline — named once, quoted by every message. */
+exports.UPDATE_BASELINE_COMMAND = "vigiles lint --update-baseline";
+/** Bumped only on an incompatible change to the on-disk shape. */
+exports.INSTRUCTION_BASELINE_VERSION = 1;
+/**
+ * Which MEASUREMENT produced a recorded number — bumped whenever a release
+ * changes what counts (chain membership in any adapter, how a file is sized),
+ * even when the file shape stays the same.
+ *
+ * Without it, a vigiles fix that moves a file into or out of the chain moves
+ * `committedTotal` on every consumer with a committed baseline, and they see
+ * `grew`/`shrank` attributed to their own content. With it, they see one
+ * "re-record" verdict that names the cause. `version` cannot do this job: it
+ * describes the file, not the number in it.
+ */
+exports.INSTRUCTION_WEIGHT_MEASURE = 1;
+const entrySchema = zod_1.z
+    .object({
+    unit: zod_1.z.enum(["chars", "bytes"]),
+    measure: zod_1.z.number().int().nonnegative(),
+    total: zod_1.z.number().int().nonnegative(),
+    files: zod_1.z.record(zod_1.z.string(), zod_1.z.number().int().nonnegative()),
+})
+    .strict()
+    .refine((e) => Object.values(e.files).reduce((a, b) => a + b, 0) === e.total, {
+    message: "`total` is not the sum of `files` — the file was edited by hand; re-record it",
+});
+const baselineSchema = zod_1.z
+    .object({
+    version: zod_1.z.literal(exports.INSTRUCTION_BASELINE_VERSION),
+    /** Keyed by bundle location from the config root; `.` is the root itself. */
+    bundles: zod_1.z.record(zod_1.z.string(), entrySchema),
+})
+    .strict();
+function parseInstructionBaseline(text) {
+    const json = (() => {
+        try {
+            return { ok: true, value: JSON.parse(text) };
+        }
+        catch {
+            return { ok: false };
+        }
+    })();
+    if (!json.ok)
+        return { kind: "invalid", message: "not valid JSON" };
+    const parsed = baselineSchema.safeParse(json.value);
+    return parsed.success
+        ? { kind: "ok", baseline: parsed.data }
+        : {
+            kind: "invalid",
+            message: parsed.error.issues
+                .map((i) => `${i.path.join(".") || "(top level)"}: ${i.message}`)
+                .join("; "),
+        };
+}
+/** What a measured weight would be recorded as: the SCORED files only. */
+function entryFor(weight) {
+    const scored = weight.files.filter((f) => f.scope === "repo");
+    return {
+        unit: weight.unit,
+        measure: exports.INSTRUCTION_WEIGHT_MEASURE,
+        total: weight.committedTotal,
+        files: Object.fromEntries([...scored]
+            .sort((a, b) => a.path.localeCompare(b.path))
+            .map((f) => [f.path, f.size])),
+    };
+}
+function changesBetween(before, after) {
+    const paths = [...new Set([...Object.keys(before), ...Object.keys(after)])];
+    const size = (m, p) => Object.hasOwn(m, p) ? m[p] : null;
+    return paths
+        .map((path) => ({ path, from: size(before, path), to: size(after, path) }))
+        .filter((c) => c.from !== c.to)
+        .sort((a, b) => Math.abs((b.to ?? 0) - (b.from ?? 0)) -
+        Math.abs((a.to ?? 0) - (a.from ?? 0)) || a.path.localeCompare(b.path));
+}
+function compareToBaseline(weight, recorded) {
+    const current = entryFor(weight);
+    if (recorded === undefined)
+        return { kind: "unrecorded", current };
+    if (recorded.unit !== current.unit) {
+        return {
+            kind: "unit-changed",
+            recorded: recorded.unit,
+            current: current.unit,
+        };
+    }
+    if (recorded.measure !== current.measure) {
+        return {
+            kind: "measure-changed",
+            recorded: recorded.measure,
+            current: current.measure,
+        };
+    }
+    if (current.total === recorded.total) {
+        return { kind: "held", total: current.total, unit: current.unit };
+    }
+    return {
+        kind: current.total > recorded.total ? "grew" : "shrank",
+        from: recorded.total,
+        to: current.total,
+        unit: current.unit,
+        changes: changesBetween(recorded.files, current.files),
+    };
+}
+/** Replace the measured bundles' entries; `null` removes one. Others are kept. */
+function recordEntries(previous, measured) {
+    const removed = new Set(measured.filter(([, e]) => e === null).map(([at]) => at));
+    const kept = Object.entries(previous?.bundles ?? {}).filter(([at]) => !removed.has(at));
+    const fresh = measured.flatMap(([at, e]) => e === null ? [] : [[at, e]]);
+    return {
+        version: exports.INSTRUCTION_BASELINE_VERSION,
+        bundles: Object.fromEntries([...new Map([...kept, ...fresh]).entries()].sort(([a], [b]) => a.localeCompare(b))),
+    };
+}
+/** Stable text: sorted keys, two-space indent, trailing newline, no timestamp. */
+function serializeBaseline(baseline) {
+    return `${JSON.stringify(baseline, null, 2)}\n`;
+}
+const n = (x) => x.toLocaleString("en-US");
+const signed = (x) => (x > 0 ? `+${n(x)}` : n(x));
+function describeChange(c) {
+    if (c.from === null)
+        return `${c.path} +${n(c.to ?? 0)} (new)`;
+    if (c.to === null)
+        return `${c.path} -${n(c.from)} (gone)`;
+    return `${c.path} ${signed(c.to - c.from)}`;
+}
+/** The one-paragraph message a verdict prints as, prefixed by its bundle. */
+function formatVerdict(verdict, at) {
+    const where = at === "." ? "" : `${at}: `;
+    switch (verdict.kind) {
+        case "unrecorded":
+            return (`${where}no instruction-weight baseline recorded (${n(verdict.current.total)} ${verdict.current.unit} always loaded) — ` +
+                `run \`${exports.UPDATE_BASELINE_COMMAND}\` and commit ${exports.INSTRUCTION_BASELINE_FILE} to stop it growing unnoticed`);
+        case "unit-changed":
+            return (`${where}the instruction-weight baseline is in ${verdict.recorded} but this harness counts ${verdict.current} — ` +
+                `re-record it with \`${exports.UPDATE_BASELINE_COMMAND}\``);
+        case "measure-changed":
+            return (`${where}the instruction-weight baseline was recorded by measurement ${String(verdict.recorded)}, this vigiles uses ${String(verdict.current)} — ` +
+                `what counts changed in vigiles, not in your files. Re-record it with \`${exports.UPDATE_BASELINE_COMMAND}\``);
+        case "held":
+            return `${where}always-loaded instructions held at ${n(verdict.total)} ${verdict.unit} (baseline)`;
+        case "grew":
+        case "shrank": {
+            const head = `${n(verdict.from)} → ${n(verdict.to)} ${verdict.unit} (${signed(verdict.to - verdict.from)})`;
+            const moved = verdict.changes.length > 0
+                ? ` Changed: ${verdict.changes.map(describeChange).join(", ")}.`
+                : "";
+            return verdict.kind === "grew"
+                ? `${where}always-loaded instructions grew ${head} over the recorded baseline.${moved} ` +
+                    `If the growth is intended, record it with \`${exports.UPDATE_BASELINE_COMMAND}\` — the diff of ${exports.INSTRUCTION_BASELINE_FILE} is the review.`
+                : `${where}always-loaded instructions shrank ${head}; the baseline still allows the old weight.${moved} ` +
+                    `Lock the cut in with \`${exports.UPDATE_BASELINE_COMMAND}\`, or the headroom can be regrown without a finding.`;
+        }
+    }
+}
+/** The compile-time one-liner: weight now, against the baseline when there is one. */
+function formatWeightLine(verdict) {
+    switch (verdict.kind) {
+        case "unrecorded":
+            return `always-loaded: ${n(verdict.current.total)} ${verdict.current.unit} (no baseline — \`${exports.UPDATE_BASELINE_COMMAND}\`)`;
+        case "unit-changed":
+            return `always-loaded: baseline is in ${verdict.recorded}, this harness counts ${verdict.current}`;
+        case "measure-changed":
+            return `always-loaded: baseline recorded by measurement ${String(verdict.recorded)}, this vigiles uses ${String(verdict.current)} — re-record`;
+        case "held":
+            return `always-loaded: ${n(verdict.total)} ${verdict.unit} (baseline ${n(verdict.total)}, ±0)`;
+        case "grew":
+        case "shrank":
+            return `always-loaded: ${n(verdict.to)} ${verdict.unit} (baseline ${n(verdict.from)}, ${signed(verdict.to - verdict.from)})`;
+    }
+}
+//# sourceMappingURL=instruction-baseline.js.map

package/dist/core/instruction-weight.d.ts

@@ -28,12 +28,13 @@
  * number carries a different severity per harness, so the harness must supply
  * it — hence a port field, not a constant.
  *
- * NOT A GATE, AND THAT IS MEASURED. Both corpora this was built against sit at
- * roughly four times the Claude Code threshold. A rule that fails every real
- * repo on day one is switched off on day one (`lint-rule-calibration`: severity
- * tracks confidence, and a check nobody leaves on catches nothing). So the
- * first consumer is `audit`, as a REPORT. It earns a severity when a corpus
- * exists that it would not immediately fail.
+ * THE BUDGET IS NOT A GATE, AND THAT IS MEASURED. Both corpora this was built
+ * against sit at roughly four times the Claude Code threshold. A rule that
+ * fails every real repo on day one is switched off on day one
+ * (`lint-rule-calibration`: severity tracks confidence, and a check nobody
+ * leaves on catches nothing). So `audit` reports the budget, and what `lint`
+ * gates is the repo's OWN recorded weight (`./instruction-baseline.ts`): green
+ * on day one at any size, red the day it grows.
  */
 import type { InstructionChain, InstructionRole, InstructionScope } from "./instruction-chain.js";
 /** What the harness counts, and what it does when the count is exceeded. */
@@ -147,7 +148,16 @@ export interface InstructionWeight {
         readonly to: readonly string[];
     }[];
 }
-/** Size in the harness's own unit. Bytes and chars differ on any non-ASCII text. */
+/**
+ * Size in the harness's own unit. Bytes and chars differ on any non-ASCII text.
+ *
+ * Line endings are counted as `\n`. A checkout with `core.autocrlf` holds the
+ * same commit with one more character per line, and a number that differs
+ * between two clones of one commit cannot be committed and compared — a
+ * 1 000-line file read +1 000 on Windows with no content change. The harness
+ * may count the CR itself; reproducibility is worth more here than that
+ * fidelity.
+ */
 export declare function sizeIn(text: string, unit: "chars" | "bytes"): number;
 /**
  * Weigh a harness's LOADED chain against its own budget.

package/dist/core/instruction-weight.js

@@ -29,19 +29,30 @@
  * number carries a different severity per harness, so the harness must supply
  * it — hence a port field, not a constant.
  *
- * NOT A GATE, AND THAT IS MEASURED. Both corpora this was built against sit at
- * roughly four times the Claude Code threshold. A rule that fails every real
- * repo on day one is switched off on day one (`lint-rule-calibration`: severity
- * tracks confidence, and a check nobody leaves on catches nothing). So the
- * first consumer is `audit`, as a REPORT. It earns a severity when a corpus
- * exists that it would not immediately fail.
+ * THE BUDGET IS NOT A GATE, AND THAT IS MEASURED. Both corpora this was built
+ * against sit at roughly four times the Claude Code threshold. A rule that
+ * fails every real repo on day one is switched off on day one
+ * (`lint-rule-calibration`: severity tracks confidence, and a check nobody
+ * leaves on catches nothing). So `audit` reports the budget, and what `lint`
+ * gates is the repo's OWN recorded weight (`./instruction-baseline.ts`): green
+ * on day one at any size, red the day it grows.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sizeIn = sizeIn;
 exports.weighInstructions = weighInstructions;
-/** Size in the harness's own unit. Bytes and chars differ on any non-ASCII text. */
+/**
+ * Size in the harness's own unit. Bytes and chars differ on any non-ASCII text.
+ *
+ * Line endings are counted as `\n`. A checkout with `core.autocrlf` holds the
+ * same commit with one more character per line, and a number that differs
+ * between two clones of one commit cannot be committed and compared — a
+ * 1 000-line file read +1 000 on Windows with no content change. The harness
+ * may count the CR itself; reproducibility is worth more here than that
+ * fidelity.
+ */
 function sizeIn(text, unit) {
-    return unit === "chars" ? text.length : Buffer.byteLength(text, "utf8");
+    const lf = text.replaceAll("\r\n", "\n");
+    return unit === "chars" ? lf.length : Buffer.byteLength(lf, "utf8");
 }
 /**
  * Weigh a harness's LOADED chain against its own budget.
@@ -107,10 +118,15 @@ function weighInstructions(chain, files, budget) {
         committedTotal,
         effectiveTotal: sum(weighed.filter((f) => f.notLoadedHere === undefined)),
         overBy: committedTotal > budget.limit ? committedTotal - budget.limit : null,
+        // NOT "absent from the map": a second-hop target can be in the map (the
+        // import pass read it because its importer was also a candidate) and still
+        // not be in the chain, because the second hop is named, never taken. What
+        // makes an import unread is that the chain did not classify its target.
         unreadImports: [
             ...new Set(chain.imports
                 .map((i) => i.path)
-                .filter((path) => files[path] === undefined)),
+                .filter((path) => !chain.loaded.some((e) => e.path === path) &&
+                !chain.unloaded.some((e) => e.path === path))),
         ].sort(),
         unweighedPatterns: [
             ...new Set(chain.patterns.map((p) => p.pattern)),

package/dist/core/rule-meta.js

@@ -210,6 +210,14 @@ exports.RULE_META = {
         summary: "Two model-invocable skills aren't near-identical (wrong one fires).",
         detector: "findDescriptionOverlaps",
     },
+    "instruction-weight": {
+        id: "instruction-weight",
+        bucket: "external-decidable",
+        surface: ["instruction"],
+        defaultSeverity: "error",
+        summary: "The always-loaded instruction weight did not move off its committed baseline.",
+        detector: "compareToBaseline",
+    },
     "skill-description-budget": {
         id: "skill-description-budget",
         bucket: "heuristic-behavioral",

package/dist/core/types.d.ts

@@ -122,6 +122,14 @@ export interface RulesConfig {
      * exited 0 (#173). Default: "error", matching `compile`.
      */
     "spec-refs"?: RuleSeverity;
+    /**
+     * The always-loaded instruction weight may not move away from the committed
+     * baseline in `.vigiles/instruction-weight.json` — a ratchet against the
+     * repo's own past, not a fixed budget. No baseline file → a one-line note,
+     * never a finding, so turning this on fails no repository on day one.
+     * `vigiles lint --update-baseline` records it. Default: "error".
+     */
+    "instruction-weight"?: RuleSeverity;
     /**
      * Near-duplicate rules WITHIN one spec, by NCD similarity — spec bloat, two
      * rules saying the same thing in different words.

package/dist/coverage-probe.d.ts

@@ -106,6 +106,21 @@ import { type SurfaceProbe } from "./check-count.js";
  * runner resolves refs against real discovered surfaces or drops them.
  */
 export declare function commandRefs(command: string, env?: Record<string, string>): string[];
+/**
+ * The files that a `hook-runtime run-program` command needs to exist: the hook
+ * file it names, and the runtime script when the command starts it by path
+ * (`node "$DIR/node_modules/vigiles/dist/cli.js" hook-runtime run-program …`).
+ *
+ * Narrower than {@link commandRefs}, which lists every program a command runs.
+ * This lists only what a compiled hook depends on, because the start-of-session
+ * check (`hook-check.ts`) reports these files as missing. `bash scripts/build.sh`
+ * is not one of them; reporting it missing in a fresh clone would be a false
+ * alarm that `npm install` does not fix.
+ *
+ * Like `commandRefs`, it only counts a command that really starts vigiles, so
+ * `echo vigiles hook-runtime run-program x.mjs` names nothing.
+ */
+export declare function runProgramFiles(command: string): string[];
 /** The transcript shape this module reads — structural, so it imports no tier. */
 export interface ProbeableTrace {
     readonly toolCalls: readonly {

package/dist/coverage-probe.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.commandRefs = commandRefs;
+exports.runProgramFiles = runProgramFiles;
 exports.traceRefs = traceRefs;
 exports.probeCommand = probeCommand;
 exports.probeTrace = probeTrace;
@@ -586,6 +587,34 @@ function commandRefs(command, env) {
     }
     return [...out];
 }
+/**
+ * The files that a `hook-runtime run-program` command needs to exist: the hook
+ * file it names, and the runtime script when the command starts it by path
+ * (`node "$DIR/node_modules/vigiles/dist/cli.js" hook-runtime run-program …`).
+ *
+ * Narrower than {@link commandRefs}, which lists every program a command runs.
+ * This lists only what a compiled hook depends on, because the start-of-session
+ * check (`hook-check.ts`) reports these files as missing. `bash scripts/build.sh`
+ * is not one of them; reporting it missing in a fresh clone would be a false
+ * alarm that `npm install` does not fix.
+ *
+ * Like `commandRefs`, it only counts a command that really starts vigiles, so
+ * `echo vigiles hook-runtime run-program x.mjs` names nothing.
+ */
+function runProgramFiles(command) {
+    const out = new Set();
+    for (const argv of (0, bash_effects_js_1.leafArgvSource)(command)) {
+        const head = argv[0] ?? "";
+        const entry = SCRIPT_RE.test(head) ? head : interpretedScript(argv);
+        const hook = runProgramRef(argv, entry);
+        if (hook === undefined)
+            continue;
+        if (entry !== undefined)
+            out.add(entry);
+        out.add(hook);
+    }
+    return [...out];
+}
 /**
  * The tools that DISPATCH a subagent. Both spellings, because the live CLI names
  * it `Agent` and older docs name it `Task` — the same pair `parseSubagents`

package/dist/hook-check-install.d.ts

@@ -0,0 +1,3 @@
+import type { HarnessAdapter } from "./core/adapter.js";
+export declare function installHookCheck(adapters: readonly HarnessAdapter[], cwd?: string): void;
+//# sourceMappingURL=hook-check-install.d.ts.map

package/dist/hook-check-install.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installHookCheck = installHookCheck;
+/**
+ * Writes the start-of-session check described in `src/hook-check.ts` and adds its
+ * entry to each harness's settings. `vigiles compile` calls this once, after it
+ * has merged the hooks.
+ *
+ * The list of files comes from the settings as they are now, not from the hooks
+ * this run compiled. So compiling one hook does not make the check forget the
+ * others, and compiling twice changes nothing. The entry is found again by the
+ * script's path, so a recompile replaces it in place and leaves any
+ * `SessionStart` hook the user wrote alone.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const hook_check_js_1 = require("./hook-check.js");
+const hook_install_js_1 = require("./hook-install.js");
+function isShellAdapter(adapter) {
+    return adapter.shellHooks;
+}
+/** One harness's settings as a plain object, or `undefined` if the file does not exist yet. */
+function readSettings(adapter, cwd) {
+    const file = (0, node_path_1.resolve)(cwd, adapter.layout.settingsPath);
+    return (0, node_fs_1.existsSync)(file)
+        ? adapter.layout.settings.parse((0, node_fs_1.readFileSync)(file, "utf-8"))
+        : undefined;
+}
+/** Add the check's `SessionStart` entry to one harness's settings, or replace it where it already is. */
+function registerCheck(adapter, existing, cwd) {
+    const ref = (0, hook_install_js_1.hookGateRef)(hook_check_js_1.HOOK_CHECK_REF, adapter.layout.projectRootTokens);
+    const merged = adapter.hookProtocol.mergeRegistrations(existing, {
+        SessionStart: [
+            { hooks: [{ type: "command", command: `sh ${ref} || exit 0` }] },
+        ],
+    }, hook_check_js_1.HOOK_CHECK_REF);
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(cwd, adapter.layout.settingsPath), adapter.layout.settings.render(merged));
+}
+function installHookCheck(adapters, cwd = process.cwd()) {
+    const found = adapters.filter(isShellAdapter).flatMap((adapter) => {
+        const settings = readSettings(adapter, cwd);
+        return settings === undefined ? [] : [{ adapter, settings }];
+    });
+    const { paths, unsafe } = (0, hook_check_js_1.checkPaths)(found.flatMap((f) => (0, hook_check_js_1.commandsIn)(f.settings.hooks)));
+    for (const path of unsafe) {
+        console.warn(`⚠ hook-check: ${path} has characters the check cannot quote safely, so it is NOT covered.`);
+    }
+    if (paths.length === 0)
+        return;
+    const script = (0, node_path_1.resolve)(cwd, hook_check_js_1.HOOK_CHECK_REF);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(script), { recursive: true });
+    (0, node_fs_1.writeFileSync)(script, (0, hook_check_js_1.renderHookCheck)(paths));
+    for (const { adapter, settings } of found)
+        registerCheck(adapter, settings, cwd);
+    console.log(`✓ ${hook_check_js_1.HOOK_CHECK_REF} → SessionStart notice for ${paths.length} wired hook file(s)`);
+}
+//# sourceMappingURL=hook-check-install.js.map

package/dist/hook-check.d.ts

@@ -0,0 +1,36 @@
+/** Where the generated script is written. It is committed, next to the hook sources. */
+export declare const HOOK_CHECK_REF = ".vigiles/hook-check.sh";
+/**
+ * Every `command` string in a parsed hooks block. It looks for the key `command`
+ * instead of following one layout, because the layout depends on the harness
+ * (Claude Code nests commands under a matcher block, Codex's TOML is flat).
+ */
+export declare function commandsIn(node: unknown): string[];
+export interface CheckPaths {
+    /** Paths relative to the project, sorted, no duplicates: what the script tests. */
+    readonly paths: readonly string[];
+    /**
+     * Paths the check found but cannot safely write into the script. `compile`
+     * warns about each one, because a path left out is a hook the check does not
+     * cover.
+     */
+    readonly unsafe: readonly string[];
+}
+/**
+ * The files that the compiled-hook commands in `commands` need, as paths relative
+ * to the project. Two kinds of path are left out on purpose: absolute paths
+ * (another machine's checkout will not have them) and paths that use any variable
+ * except the project root, such as `$HOME` or a plugin root (we cannot resolve
+ * them here).
+ */
+export declare function checkPaths(commands: readonly string[]): CheckPaths;
+/**
+ * The text of the script. The same paths always give the same text, so a
+ * recompile that finds the same hooks writes the same bytes.
+ *
+ * The script prints JSON with an `additionalContext` field instead of plain text.
+ * That form is confirmed for the start of a session on both Claude Code and
+ * Codex; plain text is only confirmed on Claude Code.
+ */
+export declare function renderHookCheck(paths: readonly string[]): string;
+//# sourceMappingURL=hook-check.d.ts.map

package/dist/hook-check.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOOK_CHECK_REF = void 0;
+exports.commandsIn = commandsIn;
+exports.checkPaths = checkPaths;
+exports.renderHookCheck = renderHookCheck;
+/**
+ * A check that runs when a session starts and says "run npm install" if files
+ * that the repo's hooks need are missing.
+ *
+ * Why it exists (#312). A compiled hook lives in two places: the wiring in
+ * `.claude/settings.json` (stored in git) and the files that wiring runs (in
+ * `node_modules`, stored by npm). A fresh container, a merge that brings new
+ * wiring, or a dependency update can change one without the other. Today the
+ * first sign is a hook refusing the first command. This check notices one step
+ * earlier and names the fix.
+ *
+ * What it does not do: fix anything. If a hook that can block commands has
+ * missing files, it still refuses every shell command, including the install.
+ * The check only says so before the first command is tried, so a person can run
+ * the install from a terminal outside the session. Removing the cause would need
+ * hook files stored in git next to their wiring; that is a separate decision
+ * (#312).
+ *
+ * Three rules shape the code:
+ *
+ * - It must work when nothing is installed. So the script is plain POSIX `sh`
+ *   using only built-in commands (no node, no vigiles, no grep), and it is
+ *   committed, so it arrives together with the wiring.
+ * - It only prints and always exits 0. We have not verified what exit code 2
+ *   does at session start, and a check that could fail would be one more way to
+ *   break the session it is meant to help. It is wired `|| exit 0`, like any
+ *   reminder.
+ * - It lists only what a compiled hook needs: the hook files named by
+ *   `hook-runtime run-program` commands in the settings, plus the local runtime
+ *   when it is started by path. Reporting any other script (say
+ *   `scripts/build.sh`) as missing in a fresh clone would be a false alarm,
+ *   because `npm install` does not create it.
+ *
+ * The list is read from the settings after `compile` has merged into them. So it
+ * also covers hooks that another tool wrote there, and it does not shrink when
+ * `compile` is run on just one hook. A hook added after the last `compile` is
+ * not covered until the next one.
+ *
+ * Limits: it checks that a file exists, not that it loads. A package that is
+ * present but no longer exports what a hook imports passes this check and still
+ * breaks. A path is recognised by the same pattern the coverage code uses, which
+ * has no room for spaces or quotes, so a hook under such a path is not covered,
+ * and the check cannot say so.
+ */
+const coverage_probe_js_1 = require("./coverage-probe.js");
+/** Where the generated script is written. It is committed, next to the hook sources. */
+exports.HOOK_CHECK_REF = ".vigiles/hook-check.sh";
+/**
+ * Every `command` string in a parsed hooks block. It looks for the key `command`
+ * instead of following one layout, because the layout depends on the harness
+ * (Claude Code nests commands under a matcher block, Codex's TOML is flat).
+ */
+function commandsIn(node) {
+    if (Array.isArray(node))
+        return node.flatMap(commandsIn);
+    if (typeof node !== "object" || node === null)
+        return [];
+    return Object.entries(node).flatMap(([key, value]) => key === "command" && typeof value === "string"
+        ? [value]
+        : commandsIn(value));
+}
+/** How a command may spell the project root. It is removed to leave a relative path. */
+const PROJECT_ROOT_PREFIX = /^\$(?:\{CLAUDE_PROJECT_DIR\}|CLAUDE_PROJECT_DIR)\//;
+/** The characters a path may contain. It is written into a shell string and a JSON string. */
+const SAFE_PATH = /^[A-Za-z0-9._@+/-]+$/;
+/**
+ * The files that the compiled-hook commands in `commands` need, as paths relative
+ * to the project. Two kinds of path are left out on purpose: absolute paths
+ * (another machine's checkout will not have them) and paths that use any variable
+ * except the project root, such as `$HOME` or a plugin root (we cannot resolve
+ * them here).
+ */
+function checkPaths(commands) {
+    const relative = commands
+        .flatMap(coverage_probe_js_1.runProgramFiles)
+        .map((file) => file.replace(PROJECT_ROOT_PREFIX, ""))
+        .filter((file) => !file.startsWith("/") && !file.includes("$"));
+    const unique = [...new Set(relative)].sort();
+    return {
+        paths: unique.filter((p) => SAFE_PATH.test(p)),
+        unsafe: unique.filter((p) => !SAFE_PATH.test(p)),
+    };
+}
+/**
+ * The text of the script. The same paths always give the same text, so a
+ * recompile that finds the same hooks writes the same bytes.
+ *
+ * The script prints JSON with an `additionalContext` field instead of plain text.
+ * That form is confirmed for the start of a session on both Claude Code and
+ * Codex; plain text is only confirmed on Claude Code.
+ */
+function renderHookCheck(paths) {
+    const list = paths.map((p) => `  '${p}'`).join(" \\\n");
+    return `#!/bin/sh
+# Generated by \`vigiles compile\`. Do not edit; the next compile rewrites it.
+#
+# Start-of-session notice (vigiles #312). If a file that a compiled hook runs is
+# not installed, it says so in the first turn. It uses only plain sh and shell
+# built-ins (no node, no node_modules, no vigiles), because "not installed" is
+# exactly the situation it reports. It only prints and always exits 0.
+#
+# It does not fix anything. A hook that can block commands, with its files
+# missing, refuses every shell command including the install, so the install has
+# to be run from a terminal outside the session.
+root="\${CLAUDE_PROJECT_DIR:-.}"
+missing=""
+for p in \\
+${list}
+do
+  [ -e "$root/$p" ] || missing="$missing $p"
+done
+if [ -n "$missing" ]; then
+  printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"}}\\n' \\
+    "vigiles: hook files that this repo runs are not installed:$missing. Run npm ci (or npm install) from a terminal outside this session before anything else. A blocking hook whose files are missing refuses every shell command in a session, the install included; a reminder-only hook that cannot load is skipped. See docs/compiled-hooks.md, When a hook cannot load."
+fi
+exit 0
+`;
+}
+//# sourceMappingURL=hook-check.js.map