vigiles 26.0.1 → 26.2.0

package/dist/verify-plugin-guards.d.ts

@@ -0,0 +1,194 @@
+import { type NonCommandHookAction } from "./core/hook-normalize.js";
+export type { NonCommandHookAction } from "./core/hook-normalize.js";
+import type { HarnessAdapter } from "./core/adapter.js";
+import { type DisasterCategory, type DisasterEvent, type GuardrailResult } from "./guardrail-check.js";
+import type { RunHookOptions } from "./run-hook.js";
+/** The hook a sweep looked at, as its config declares it. */
+export interface SweptHook {
+    /** The event it registers under, e.g. `"PreToolUse"`. */
+    readonly event: string;
+    /** Its tool matcher, or `null` when it declares none (matches everything). */
+    readonly matcher: string | null;
+    /** Its condition as written (Claude Code's `if`), or `null` when unconditional. */
+    readonly condition: string | null;
+    /** The command, with the harness's plugin-root token already expanded. */
+    readonly command: string;
+    /**
+     * Its position in the flattened registration list, so two hooks sharing a
+     * command are still distinguishable in a report. Stable for one sweep of one
+     * directory; not an identity across versions.
+     */
+    readonly index: number;
+}
+/**
+ * What happened to one hook. A DISCRIMINATED UNION, not a result list plus three
+ * nullable fields: `results` exists on exactly the outcome that has them, so
+ * "read the score of a hook that was never run" is a type error rather than a
+ * `0/7` someone quotes.
+ */
+export type SweptHookOutcome = {
+    /** The battery reached this hook; `results` holds one entry per event. */
+    readonly status: "measured";
+    readonly hook: SweptHook;
+    /** One result per battery event, in catalog order. */
+    readonly results: readonly GuardrailResult[];
+    /** Ids of the events it denied. */
+    readonly blocked: readonly string[];
+    /** Ids it ran on and let through. */
+    readonly allowed: readonly string[];
+    /** Ids the harness would never have handed it (condition did not match). */
+    readonly notRun: readonly string[];
+} | {
+    /**
+     * The battery does not apply to this hook — a different event, or a matcher
+     * that selects none of the battery's tools. NOT a score of zero.
+     */
+    readonly status: "not-applicable";
+    readonly hook: SweptHook;
+    /** One line naming which of the two it is, and against what. */
+    readonly reason: string;
+} | {
+    /**
+     * The command names a variable nothing has set, so the program we would run
+     * is not the program the harness runs. Refusing is the honest answer; the
+     * fix is in the caller's hands (pass `env`).
+     */
+    readonly status: "unresolved";
+    readonly hook: SweptHook;
+    /** One line naming the unset variables. */
+    readonly reason: string;
+};
+/** The whole sweep. */
+export interface PluginGuardReport {
+    /** The directory swept, resolved to an absolute path. */
+    readonly dir: string;
+    /** The adapter that read it, e.g. `"claude-code"`. */
+    readonly harness: string;
+    /** The event each disaster was delivered as (default `"PreToolUse"`). */
+    readonly event: string;
+    /** The battery that was used, so a report says what it measured against. */
+    readonly events: readonly DisasterEvent[];
+    /** One outcome per declared COMMAND hook, in config order. */
+    readonly hooks: readonly SweptHookOutcome[];
+    /**
+     * Declared actions this tier cannot drive because they are not commands —
+     * `prompt`, `http`, `mcp_tool`, `agent`.
+     *
+     * 🔴 THEY USED TO BE DROPPED, AND DROPPING THEM MANUFACTURED THE FALSE EMPTY
+     * `notes` exists to prevent. A repository whose hooks are all `prompt` actions
+     * has declared guards; it was reported as declaring none, in the words of the
+     * one sentence this report writes to be sure nobody reads an empty result as a
+     * clean bill of health. Not measured is a limit of the tier and says so; not
+     * declared is an accusation about the repository, and it was not true.
+     *
+     * They carry no score and never will here — a shell battery cannot drive a
+     * prompt — so they are a separate list rather than a fourth outcome status
+     * with an invented command.
+     */
+    readonly unmeasurable: readonly NonCommandHookAction[];
+    /**
+     * Why the sweep measured less than a reader might assume — no COMMAND hooks
+     * declared, a harness with no shell hooks, every hook on another event, or an
+     * action this tier cannot drive. Empty only when at least one hook was
+     * measured AND nothing was left undrivable: an undrivable action is a gap in
+     * COVERAGE, so it is said even when other hooks scored.
+     *
+     * 🔴 THIS IS THE EMPTY CASE'S VOICE. `hooks: []` on its own reads as a clean
+     * bill of health, which is the exact false confidence the battery exists to
+     * remove — so a sweep that measured nothing always says so in words.
+     */
+    readonly notes: readonly string[];
+}
+/** Options for {@link experimental_verifyPluginGuards}. */
+export interface VerifyPluginGuardsOptions extends Omit<RunHookOptions, "condition" | "protocol"> {
+    /**
+     * The harness to read the repo as. Defaults to Claude Code, so an existing
+     * Claude Code repo needs nothing. The condition grammar and the block protocol
+     * both come from this adapter's `hookProtocol`.
+     */
+    readonly adapter?: HarnessAdapter;
+    /** Restrict the battery to these categories (default: the whole catalog). */
+    readonly categories?: readonly DisasterCategory[];
+    /** Override the battery entirely. */
+    readonly events?: readonly DisasterEvent[];
+    /** The event each disaster is delivered as (default `"PreToolUse"`). */
+    readonly event?: string;
+}
+/**
+ * Run the disaster battery against every hook a plugin or repo declares, using
+ * each hook's OWN event, matcher and condition, and report per hook.
+ *
+ * ```ts
+ * import { experimental_verifyPluginGuards } from "vigiles";
+ *
+ * const report = experimental_verifyPluginGuards(".");
+ * for (const h of report.hooks) {
+ *   if (h.status === "measured")
+ *     console.log(`${h.blocked.length}/${h.results.length}  ${h.hook.command}`);
+ *   else console.log(`⊘ ${h.status}  ${h.hook.command} — ${h.reason}`);
+ * }
+ * for (const note of report.notes) console.log(note);
+ * ```
+ *
+ * Nothing here needs a model or a key. The hooks it finds are the ones the
+ * harness would load, so a hook that is present on disk but not registered is
+ * absent from the report by construction — which is the correct answer, and the
+ * one you would not get by globbing `hooks/*.sh`.
+ *
+ * ⚠️ It RUNS each reachable hook. A hook is a program you did not necessarily
+ * write, so point this at a repo whose hooks you are willing to execute, or pass
+ * `trusted: false` / `sandbox: "auto"` (inherited from {@link RunHookOptions}) to
+ * confine them. `verifyGuardrail` has always had the same property; sweeping a
+ * whole plugin makes it worth saying out loud.
+ *
+ * @experimental Days old, with no consumer outside this repository. The REPORT
+ * SHAPE is the part most likely to move — specifically whether `not-applicable`
+ * stays one status or splits by cause, and whether the per-hook counts stay id
+ * arrays. The prefix comes off when that shape survives sweeping several real
+ * third-party repos unchanged; see docs/experimental.md.
+ *
+ * @param dir - the plugin or repo root to read hooks from.
+ */
+export declare function experimental_verifyPluginGuards(dir: string, opts?: VerifyPluginGuardsOptions): PluginGuardReport;
+/**
+ * Render a {@link PluginGuardReport} as terminal text.
+ *
+ * ```ts
+ * import {
+ *   experimental_verifyPluginGuards,
+ *   experimental_formatPluginGuardReport,
+ * } from "vigiles";
+ *
+ * console.log(
+ *   experimental_formatPluginGuardReport(experimental_verifyPluginGuards(".")),
+ * );
+ * ```
+ *
+ * NEUTRAL, the same way {@link formatGuardrailReport} is: it reports what each
+ * hook blocks without deciding whether that was the hook's job. A repo's config
+ * never says which of its hooks is meant to be a bash-safety guard, so a verdict
+ * here would be invented rather than read.
+ *
+ * 🔴 A HOOK THE BATTERY NEVER REACHED IS NEVER GIVEN A NUMBER. A `measured` hook
+ * prints `blocks n/7`; a `not-applicable` or `unresolved` one prints its REASON
+ * under a `⊘` heading and no count at all, because a rendered `0/7` is the same
+ * false confidence the discriminated union exists to prevent, reintroduced one
+ * layer up where the type system can no longer see it. For the same reason the
+ * report's `notes` are printed FIRST and in full: a sweep that measured nothing
+ * has to say so in words, since an output with no rows reads as a clean bill of
+ * health.
+ *
+ * MANY HOOKS STAY READABLE by grouping the unmeasured half BY REASON — a repo
+ * with thirty hooks usually has two or three distinct reasons — and naming at
+ * most {@link HOOKS_PER_REASON} hooks per reason before counting the rest. The
+ * measured half is never collapsed: those are the hooks you came for.
+ *
+ * @experimental It renders {@link PluginGuardReport}, whose SHAPE is the part
+ * most likely to move (see {@link experimental_verifyPluginGuards}), so a stable
+ * name here would promise a stability its only input does not have. The prefix
+ * comes off with the same change that takes it off the report.
+ *
+ * @param report - a sweep from {@link experimental_verifyPluginGuards}.
+ */
+export declare function experimental_formatPluginGuardReport(report: PluginGuardReport): string;
+//# sourceMappingURL=verify-plugin-guards.d.ts.map