@vibe-agent-toolkit/cli 0.2.0-rc.5 → 0.2.0-rc.7

package/dist/utils/resource-loader.js

@@ -1,13 +1,37 @@
 /**
  * Utilities for loading and crawling resources
  */
-import { existsSync, statSync } from 'node:fs';
-import { buildResourcePopulation, DEFAULT_RESOURCE_INCLUDE, gitExtentSelected, ResourceRegistry, } from '@vibe-agent-toolkit/resources';
+import { buildLinkAuthEngineConfig, buildResourcePopulation, DEFAULT_RESOURCE_INCLUDE, gitExtentSelected, ResourceRegistry, } from '@vibe-agent-toolkit/resources';
 import { safePath, toForwardSlash } from '@vibe-agent-toolkit/utils';
 import { GitTracker, gitTreeSnapshot } from '@vibe-agent-toolkit/utils/git';
 import { loadConfig } from './config-loader.js';
 import { collectionsOption } from './population-wiring.js';
+import { assertDirectoryArgument } from './project-root-policy.js';
 import { withPopulationCache } from './projection-store.js';
+/**
+ * Refuse a `resources.linkAuth` provider that cannot compile HERE, where the
+ * config is loaded, so every verb that loads it answers the same way.
+ *
+ * `buildLinkAuthEngineConfig` is the one place the per-provider compile check
+ * (`assertProviderCompiles`) lives, and the registry calls it only when it
+ * constructs the external-link validator — i.e. under `--check-external-urls`.
+ * Every other verb on this loader (`vat validate`, `vat resources validate`
+ * without the flag, `vat resources scan`, `vat rag index`) accepted an
+ * uncompilable `when` and exited 0, while the validation-code registry
+ * promised the refusal "at config load … and every other command that loads
+ * `resources.linkAuth`". The registry was right about what the contract should
+ * be; this makes the code keep it. The built config is discarded — the
+ * registry builds its own when the lane runs — because the value wanted is
+ * the throw, and calling the same function is how the two stay one check.
+ *
+ * @throws {LinkAuthConfigError} naming `providers[<n>]`, the host and the field;
+ *   every caller's catch turns a thrown error into exit 2.
+ */
+function assertLinkAuthProvidersCompile(config) {
+    const linkAuth = config.resources?.linkAuth;
+    if (linkAuth !== undefined)
+        buildLinkAuthEngineConfig(linkAuth);
+}
 /**
  * Scope resource include patterns to a subdirectory of the crawl base.
  *
@@ -50,15 +74,29 @@ function crawlOptionsForPath(pathArg, projectRoot, config, logger) {
         // them silently — silent dropping is the bug this function exists to fix.
         logger.warn(`${resolved} is outside projectRoot ${projectRoot}; ` +
             `resources include/exclude patterns from the config do not apply to it`);
-        return { baseDir: resolved };
+        return { baseDir: resolved, unreadable: RESOURCES_UNREADABLE };
     }
-    assertCrawlableDirectory(resolved);
+    // The crawler used to perform this check itself, because it received the path
+    // argument as its `baseDir`. Now that `baseDir` is the project root, a bad path
+    // argument would otherwise degrade into a glob that matches nothing — a green
+    // run reporting `filesScanned: 0`.
+    assertDirectoryArgument(resolved);
     return {
         baseDir: projectRoot,
+        unreadable: RESOURCES_UNREADABLE,
         include: scopeIncludeToSubtree(DEFAULT_RESOURCE_INCLUDE, normalizedRelDir),
         ...(config?.resources?.exclude ? { exclude: config.resources.exclude } : {}),
     };
 }
+/**
+ * The resources verbs' ruling for a directory the crawl cannot list: refuse
+ * the run by name, exit 2 — `vat resources validate`/`scan`/`check` and every
+ * verb that reaches this loader act on the registry as the whole population,
+ * and the projection lane behind `populationSource` refuses the same directory
+ * with the same sentence, so the two lanes cannot reach different exits.
+ * See `RegistryUnreadablePolicy` on the registry.
+ */
+const RESOURCES_UNREADABLE = 'refuse';
 /**
  * The env var that selects the crawler behind every resources-crawling verb —
  * `vat resources scan`/`validate`, `vat rag index`, the pipeline oracles, and
@@ -94,9 +132,10 @@ export const RESOURCES_CRAWL_WALK = 'walk';
  *
  * ⚠️⚠️ **ONE DISAGREEMENT SURVIVES, AND IT DROPS FINDINGS: SYMLINKS.** The
  * `filesystem` extent crawls with `followSymlinks: false` and records no link's
- * own path, and `GitCrawlSource` skips mode `120000` deliberately to match it —
- * so BOTH projection extents omit a committed symlink that the incumbent walk
- * includes. For an out-of-tree target those bytes have no other path into the
+ * own path, and `GitCrawlSource` drops one at a single seam to match it (git's
+ * mode `120000` for the paths the tree snapshot described, an `lstat` for the
+ * collapsed `ls-files --others` entries that carry no mode) — so BOTH projection
+ * extents omit a symlink, committed or not, that the incumbent walk includes. For an out-of-tree target those bytes have no other path into the
  * population, which means **a broken symlink the walk reports as
  * `LINK_BROKEN_FILE` is not reported on this lane.** That is a real loss, it is
  * known, and it is the cost this default was accepted at; closing it is its own
@@ -171,7 +210,7 @@ function populationSourceFor(root, gitTracker, observeExtentSource, cache) {
                 ...collectionsOption(enumeratedRoot),
             });
             observeExtentSource(population.extentSource);
-            return population.paths;
+            return { paths: population.paths, conditions: population.conditions };
         },
     };
 }
@@ -230,24 +269,6 @@ export async function withResourcePopulationSource(options, work) {
         return work(populationSourceFor(options.root, gitTracker, options.observeExtentSource ?? (() => undefined), cache));
     });
 }
-/**
- * Fail loudly on a path argument that cannot be crawled.
- *
- * The crawler used to perform this check itself, because it received the path
- * argument as its `baseDir`. Now that `baseDir` is the project root, a bad path
- * argument would otherwise degrade into a glob that matches nothing — a green
- * run reporting `filesScanned: 0`.
- */
-function assertCrawlableDirectory(resolved) {
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI path argument, resolved above
-    if (!existsSync(resolved)) {
-        throw new Error(`Path does not exist: ${resolved}`);
-    }
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI path argument, existence checked above
-    if (!statSync(resolved).isDirectory()) {
-        throw new Error(`Path is not a directory: ${resolved}`);
-    }
-}
 /**
  * Load resources from a path with config support
  *
@@ -281,20 +302,29 @@ export async function loadResourcesWithConfig(pathArg, projectRoot, logger) {
     const config = loadConfig(projectRoot);
     if (config) {
         logger.debug(`Loaded config from ${projectRoot}`);
+        assertLinkAuthProvidersCompile(config);
     }
     // Built here, but deliberately NOT initialized here — see the call inside the
     // population-cache bracket below. The registry only reads the tracker during
     // `crawl`, which happens inside that bracket, so nothing observes it empty.
     const gitTracker = new GitTracker(projectRoot);
     // Create registry and crawl
-    // Build options conditionally to satisfy exactOptionalPropertyTypes
+    // Build options conditionally to satisfy exactOptionalPropertyTypes.
+    //
+    // 🚨 The config is handed over WHENEVER one was loaded — never gated on one of
+    // its keys. This used to read `if (config?.resources?.collections)`, written
+    // when collections were the only thing the registry read from it. The registry
+    // has since grown a second consumer, `resources.linkAuth`, and the gate made
+    // it silently inert for every adopter who declared `linkAuth` without
+    // `collections`: no rewrite, no token, no `LINK_AUTH_*` code — the anonymous
+    // lane ran and the run reported success. Every read inside the registry is
+    // already `this.config?.resources?.<key>`-guarded, so an undeclared key costs
+    // nothing; a key-gate here can only ever hide the next consumer the same way.
     const registryOptions = {
         baseDir: projectRoot,
         gitTracker,
+        ...(config === undefined ? {} : { config }),
     };
-    if (config?.resources?.collections) {
-        registryOptions.config = config;
-    }
     const registry = new ResourceRegistry(registryOptions);
     let crawlOptions;
     if (pathArg) {
@@ -309,6 +339,7 @@ export async function loadResourcesWithConfig(pathArg, projectRoot, logger) {
         logger.debug(`No path argument, using: ${projectRoot}`);
         crawlOptions = {
             baseDir: projectRoot,
+            unreadable: RESOURCES_UNREADABLE,
             // Apply include patterns from config (if specified)
             ...(config?.resources?.include ? { include: config.resources.include } : {}),
             // Apply exclude patterns from config (if specified)

package/dist/utils/resource-loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"resource-loader.js","sourceRoot":"","sources":["../../src/utils/resource-loader.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resource-loader.js","sourceRoot":"","sources":["../../src/utils/resource-loader.ts"],"names":[],"mappings":"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"}

package/dist/utils/root-argv.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The argv grammar `bin.ts` needs BEFORE commander parses anything.
+ *
+ * Two decisions have to be made from raw argv: which command module to load
+ * (only one is, so `vat --version` does not pay for the whole CLI surface), and
+ * whether this invocation is one of the four `--verbose` help pages commander
+ * cannot render itself. Both must model commander's grammar rather than
+ * pattern-match the line, and getting that wrong is silent by construction —
+ * every failure mode below ended in a wrong page at exit 0.
+ *
+ * It lives here and not in `bin.ts` because `bin.ts` is the executable:
+ * importing it PARSES ARGV AND RUNS A COMMAND, so nothing there can be unit
+ * tested. Same reason `command-loaders.ts` is its own module.
+ */
+import type { Option } from 'commander';
+/** The argv questions `bin.ts` asks, bound to what the root program declares. */
+export interface RootArgvGrammar {
+    /**
+     * The command the user actually asked for, or `undefined` when the whole tree
+     * is needed (or nothing is).
+     */
+    requestedCommand(argv: readonly string[]): string | undefined;
+    /** Whether this is `vat <group> --verbose` for the named command group. */
+    wantsGroupVerboseHelp(argv: readonly string[], group: string): boolean;
+    /** Whether this is a bare `vat --help --verbose`. */
+    wantsRootVerboseHelp(argv: readonly string[]): boolean;
+}
+/**
+ * Build the grammar from the root program's OWN option declarations.
+ *
+ * Read off commander's declarations rather than hardcoded, because the blast
+ * radius grows with every future root option. Today that is `--version`,
+ * `--cwd <dir>`, `--debug` and `--no-cache`; only `--cwd` takes a value.
+ *
+ * ⚠️ ORDERING MATTERS at the call site: this must be built AFTER
+ * `registerCacheControl(program)`, which is what puts `--no-cache` into
+ * `program.options`. Built before that call, `--no-cache` would read as
+ * unknown and every `vat --no-cache <verb>` would silently give up the lazy
+ * load and register the whole tree — a quiet perf regression with no failing
+ * test to announce it.
+ *
+ * Note what is deliberately NOT synthesised here: a `--no-x` twin for boolean
+ * options, and a positive `--cache` twin for `--no-cache`. Commander matches an
+ * option by exact string (`Option.is()` is `short === arg || long === arg`), so
+ * `--no-debug` and `--cache` are UNKNOWN options that end the parse in an
+ * error. Accepting them here would re-create the very bug this scan exists to
+ * avoid: a token commander rejects, treated by us as an ordinary flag to skip.
+ *
+ * @param rootOptions - `program.options`, after every root option is registered
+ * @returns The grammar, closed over what those options declare
+ */
+export declare function createRootArgvGrammar(rootOptions: readonly Option[]): RootArgvGrammar;
+//# sourceMappingURL=root-argv.d.ts.map

package/dist/utils/root-argv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-argv.d.ts","sourceRoot":"","sources":["../../src/utils/root-argv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AASxC,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,gBAAgB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAAC;IAC9D,2EAA2E;IAC3E,qBAAqB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACvE,qDAAqD;IACrD,oBAAoB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC;CACxD;AAOD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,eAAe,CAyKrF"}

package/dist/utils/root-argv.js

@@ -0,0 +1,215 @@
+/**
+ * The argv grammar `bin.ts` needs BEFORE commander parses anything.
+ *
+ * Two decisions have to be made from raw argv: which command module to load
+ * (only one is, so `vat --version` does not pay for the whole CLI surface), and
+ * whether this invocation is one of the four `--verbose` help pages commander
+ * cannot render itself. Both must model commander's grammar rather than
+ * pattern-match the line, and getting that wrong is silent by construction —
+ * every failure mode below ended in a wrong page at exit 0.
+ *
+ * It lives here and not in `bin.ts` because `bin.ts` is the executable:
+ * importing it PARSES ARGV AND RUNS A COMMAND, so nothing there can be unit
+ * tested. Same reason `command-loaders.ts` is its own module.
+ */
+/** How many argv slots a step occupies: a `pair` takes its value with it. */
+function widthOf(step) {
+    return step === 'pair' ? 2 : 1;
+}
+/**
+ * Build the grammar from the root program's OWN option declarations.
+ *
+ * Read off commander's declarations rather than hardcoded, because the blast
+ * radius grows with every future root option. Today that is `--version`,
+ * `--cwd <dir>`, `--debug` and `--no-cache`; only `--cwd` takes a value.
+ *
+ * ⚠️ ORDERING MATTERS at the call site: this must be built AFTER
+ * `registerCacheControl(program)`, which is what puts `--no-cache` into
+ * `program.options`. Built before that call, `--no-cache` would read as
+ * unknown and every `vat --no-cache <verb>` would silently give up the lazy
+ * load and register the whole tree — a quiet perf regression with no failing
+ * test to announce it.
+ *
+ * Note what is deliberately NOT synthesised here: a `--no-x` twin for boolean
+ * options, and a positive `--cache` twin for `--no-cache`. Commander matches an
+ * option by exact string (`Option.is()` is `short === arg || long === arg`), so
+ * `--no-debug` and `--cache` are UNKNOWN options that end the parse in an
+ * error. Accepting them here would re-create the very bug this scan exists to
+ * avoid: a token commander rejects, treated by us as an ordinary flag to skip.
+ *
+ * @param rootOptions - `program.options`, after every root option is registered
+ * @returns The grammar, closed over what those options declare
+ */
+export function createRootArgvGrammar(rootOptions) {
+    const declaredRootFlags = new Set(['-h', '--help']);
+    const valueTakingRootFlags = new Set();
+    const declareRootFlag = (flag, takesValue) => {
+        if (!flag)
+            return;
+        declaredRootFlags.add(flag);
+        if (takesValue)
+            valueTakingRootFlags.add(flag);
+    };
+    for (const option of rootOptions) {
+        const takesValue = Boolean(option.required || option.optional);
+        declareRootFlag(option.short, takesValue);
+        declareRootFlag(option.long, takesValue);
+    }
+    /**
+     * Classify an option-shaped token against what this program declares.
+     *
+     * The `--flag=value` case is not just "strip the suffix": commander only
+     * accepts the inline form for a VALUE-TAKING option — its `--foo=bar` branch
+     * requires `option.required || option.optional` — so `--debug=1` is an unknown
+     * option even though `--debug` is declared.
+     *
+     * Anything unrecognised is reported as `unknown` rather than guessed at.
+     * The cost of being wrong is asymmetric: a false `unknown` only forfeits
+     * the lazy-load saving, while a false "declared" ships a wrong help page at
+     * exit 0.
+     */
+    function classifyOptionToken(arg) {
+        const equalsIndex = arg.indexOf('=');
+        if (equalsIndex !== -1) {
+            return valueTakingRootFlags.has(arg.slice(0, equalsIndex)) ? 'flag' : 'unknown';
+        }
+        if (!declaredRootFlags.has(arg))
+            return 'unknown';
+        return valueTakingRootFlags.has(arg) ? 'pair' : 'flag';
+    }
+    /**
+     * How the scan steps over one token: an operand, or one of the option kinds.
+     *
+     * A lone `-` is an OPERAND — commander's `maybeOption` requires
+     * `arg.length > 1` — and so is anything not option-shaped. Shared by both
+     * scans below so the grammar cannot be modelled on one side of the command
+     * name and pattern-matched on the other, which is how `wantsGroupVerboseHelp`
+     * shipped.
+     */
+    function stepOver(arg) {
+        return arg.length > 1 && arg.startsWith('-') ? classifyOptionToken(arg) : 'operand';
+    }
+    /**
+     * Where in argv commander will read the command name, or `undefined` when it
+     * will not read one.
+     *
+     * This must model commander's grammar, not just "the first token without a
+     * dash". Ways a naive scan got it wrong, all shipped and all verified:
+     *
+     * - **An option's VALUE is not a verb.** `--cwd <dir>` takes a value that does
+     *   not start with `-`, so `vat --cwd skills validate` picked `skills`,
+     *   registered only that, and left `validate` unregistered — while
+     *   `vat --cwd skills validate --help` printed ROOT help and exited **0**.
+     *   Only the space-separated form was affected; `--cwd=skills` carries its
+     *   value inline. The advertised `vat --cwd <dir> build` also lost the entire
+     *   startup saving, since a non-colliding directory matched no loader key and
+     *   fell through to loading everything.
+     * - **`--help` BEFORE the verb renders ROOT help**, which has to list every
+     *   command. Loading only the named one made `vat --help audit` print a help
+     *   page claiming the CLI has exactly one command, and exit 0. `vat audit
+     *   --help` is the other order and returns on the verb before reaching the
+     *   flag, so it still loads just `audit`.
+     * - **An UNDECLARED option is not a flag to skip over.** `--help` is only the
+     *   most visible member of that class — it is not in `program.options` either,
+     *   which is exactly why the bail-out above works. Commander's `parseOptions`
+     *   switches its destination to `unknown` at the FIRST unrecognised
+     *   option-shaped token and never switches back, so the verb after it never
+     *   reaches `operands`; the run ends in `unknownOption()` +
+     *   `showHelpAfterError()`, i.e. ROOT help. `vat --verbose audit` therefore
+     *   printed an error page listing exactly one command. Every undeclared option
+     *   gets the `--help` treatment for that reason.
+     * - **A lone `-` is an OPERAND, not an option.** Commander's `maybeOption`
+     *   requires `arg.length > 1`, so `-` lands in `operands` and reaches the
+     *   `command:*` handler as an unknown command — which again renders root help.
+     *   Returning its index hands `-` to the dispatcher, where it matches no
+     *   loader key and the whole tree loads.
+     *
+     * `--` is option-shaped by the length test but declared by nobody, so it takes
+     * the undeclared bail-out. That is the right answer: commander treats every
+     * token after it as an operand, and loading the whole tree is always
+     * behaviourally correct — the scan only ever trades away startup time.
+     */
+    function commandIndex(argv) {
+        let index = 0;
+        while (index < argv.length) {
+            const arg = argv[index] ?? '';
+            if (arg === '--help' || arg === '-h')
+                return undefined;
+            const step = stepOver(arg);
+            if (step === 'operand')
+                return index;
+            if (step === 'unknown')
+                return undefined;
+            index += widthOf(step);
+        }
+        return undefined;
+    }
+    return {
+        requestedCommand(argv) {
+            const index = commandIndex(argv);
+            return index === undefined ? undefined : argv[index];
+        },
+        /**
+         * Whether this is `vat <group> --verbose`, asked by POSITION.
+         *
+         * 🪤 The three shipped checks asked `process.argv.includes('<group>')
+         * && process.argv.includes('--verbose')`, which matches the word anywhere
+         * on the line — as another command's subcommand, as a path, as a value:
+         *
+         *     vat inventory resources --verbose   → printed RESOURCES' verbose help, exit 0
+         *     vat resources scan rag --verbose    → printed RAG's verbose help, exit 0
+         *
+         * Neither ran what the user typed and neither said so; the second exited 0
+         * having enumerated nothing at all, on a line whose only sin was naming a
+         * directory `rag`. So the group has to be the token commander itself would
+         * read as the command name — the same question the lazy loader asks — and
+         * `--verbose` has to follow it with no subcommand in between.
+         *
+         * 🪤 "No subcommand in between" is the SAME grammar as `commandIndex`, applied
+         * to the tokens after the group. Commander accepts a root option on either
+         * side of the command name, so `--cwd`'s value is no more a subcommand after
+         * the group than before it — but this branch read `after.some(!startsWith('-'))`,
+         * which is the naive scan the rest of this module replaced, and
+         * `vat resources --verbose --cwd docs` died on `unknown option '--verbose'`
+         * while `vat --cwd docs resources --verbose` printed the page. An undeclared
+         * option after the group is likewise commander's to refuse, not ours to skip:
+         * `vat resources --verbose --nonsense` printed the page at exit 0 with the
+         * typo silently dropped.
+         */
+        wantsGroupVerboseHelp(argv, group) {
+            const index = commandIndex(argv);
+            if (index === undefined || argv[index] !== group)
+                return false;
+            let verbose = false;
+            let cursor = index + 1;
+            while (cursor < argv.length) {
+                const arg = argv[cursor] ?? '';
+                if (arg === '--verbose') {
+                    verbose = true;
+                    cursor += 1;
+                    continue;
+                }
+                // A subcommand of its own is commander's to run, and so is an option
+                // nobody declared; only the bare group has no page but the hand-written one.
+                const step = stepOver(arg);
+                if (step === 'operand' || step === 'unknown')
+                    return false;
+                cursor += widthOf(step);
+            }
+            return verbose;
+        },
+        /**
+         * Whether this is a bare `vat --help --verbose`.
+         *
+         * "Bare" is decided the same way, and for the same reason: the shipped
+         * check treated any token without a leading dash as a subcommand, so
+         * `vat --cwd docs --help --verbose` read `docs` as the command and silently
+         * rendered the NON-verbose root page instead.
+         */
+        wantsRootVerboseHelp(argv) {
+            const hasHelp = argv.includes('--help') || argv.includes('-h');
+            return hasHelp && argv.includes('--verbose') && commandIndex(argv) === undefined;
+        },
+    };
+}
+//# sourceMappingURL=root-argv.js.map

package/dist/utils/root-argv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-argv.js","sourceRoot":"","sources":["../../src/utils/root-argv.ts"],"names":[],"mappings":"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"}

package/dist/utils/run-integrity.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The run-integrity refusal: ONE mechanism for every gate that must never
+ * answer `success` after checking nothing.
+ *
+ * ## The class this closes
+ *
+ * A gate that checked nothing produces the same document as a gate that was
+ * removed. `vat resources check` shipped it (no `checks:` block → `status:
+ * success`, exit 0), then `vat claude budget` (a path matching no working
+ * location), then the repo's own audit quality gate (a green path over zero
+ * parsed findings), then `vat resources validate` (a `--collection` matching
+ * nothing → `filesScanned: 0`, exit 0), `vat claude marketplace validate` (no
+ * `plugins/` to walk, no count published), `vat corpus scan` (an empty tree
+ * "audits cleanly"), `vat verify`'s `packaged-content` phase (a typo'd glob
+ * discovers no bundle and the phase reports `success`), then `vat skills
+ * validate` (the same typo'd glob: one info line, no document, exit 0 — and
+ * `vat validate` folded that into `success`) and `vat audit` (an existing tree
+ * with nothing auditable: `status: success` over `filesScanned: 0`). Nine
+ * instances of one shape, and each was first fixed by hand at its own site.
+ * This module is where that hand-fixing stops: every site derives its refusal
+ * through the same three functions, so the invariants below are properties of
+ * the mechanism rather than of each author's memory.
+ *
+ * ## The invariants
+ *
+ * 1. **Code {@link RUN_INTEGRITY_CODE} — `RESOURCE_CHECK_BROKEN` — and never a
+ *    sibling per site.** It is the registry's one run-integrity claim — *these
+ *    assertions did not execute meaningfully, so the green means nothing* — and
+ *    `ValidationConfigSchema` refuses it as a `severity` key, which is what makes
+ *    it non-overridable by construction. A code per site would buy a consumer
+ *    nothing the message does not already say while adding one more thing an
+ *    adopter's CI has to know to look for.
+ * 2. **Severity `error`, and not a parameter.** The one thing that must never be
+ *    configurable about "the gate did not do its job" is whether it gates.
+ * 3. **Derived inside the DOCUMENT builder, never asserted in a handler.** The
+ *    builder is the one function every lane's document passes through, so
+ *    deriving the refusal there lands it after `resolveIssueSeverity` and
+ *    `applyAllowFilter` and makes "denominator zero, status clean"
+ *    unrepresentable rather than merely unwritten. A pure function, unit-testable
+ *    without I/O.
+ * 4. **ONE finding per run**, however many things went unmatched. The claim is
+ *    about the RUN; one per argument is per-finding duplication.
+ * 5. **The message says what did not run and what the operator can do.** It
+ *    must not claim the corpus is broken — it claims the run is not a verdict.
+ * 6. **stderr may still carry a human warning; the document and the exit code
+ *    must agree with it.** The human channel and the machine channel were what
+ *    disagreed in every shipped instance, and only the machine channel gates.
+ */
+import type { ValidationIssue } from '@vibe-agent-toolkit/schema';
+/**
+ * The code every run-integrity refusal carries.
+ *
+ * 🔑 **One code for every refusal, on purpose.** A statement that would not
+ * compile, a corpus with no members, a run with no rules, a run that was killed,
+ * a scan that matched no file, a walk that missed a declared plugin, a phase that
+ * found no bundle — all are the same claim to a consumer, and they need the
+ * identical non-overridability, which
+ * `ValidationConfigSchema` grants by refusing this code as a `severity` key.
+ */
+export declare const RUN_INTEGRITY_CODE = "RESOURCE_CHECK_BROKEN";
+/**
+ * A run-integrity refusal: the non-overridable code, at `error`, always.
+ *
+ * The severity is not a parameter and must not become one. Every caller is
+ * reporting that the gate did not do its job, and the one thing that must never
+ * be configurable about that report is whether it gates.
+ *
+ * @param message - What did not run, and what the operator can do about it
+ * @returns The finding
+ */
+export declare function runIntegrityFinding(message: string): ValidationIssue;
+/**
+ * The refusal for a run whose denominator is zero — nothing was checked.
+ *
+ * 🪤 **It asks the DENOMINATOR, never the config.** A builder cannot see why
+ * nothing ran and deliberately does not ask. An absent config block, a filter
+ * that matched nothing, a glob with a typo, a directory that was never built —
+ * all arrive as the same document, and all of them are a gate that asserted
+ * nothing. The message is where a site names the likely causes and the remedy.
+ *
+ * 🪤 **One report per situation.** A run that already carries a run-integrity
+ * finding (an interrupted run, say) has the more specific of the two claims on
+ * the document, so this stands down rather than handing the operator two reports
+ * about one situation. Nothing weaker is needed: every such finding is `error`,
+ * so the status is already refused.
+ *
+ * @param denominator - How many things the run actually checked
+ * @param issues - What the run already found, so an existing run-integrity
+ *   report is not duplicated
+ * @param message - The site's own account of what did not run and what to do;
+ *   evaluated lazily so a populated run pays nothing for it
+ * @returns The one finding, or nothing when at least one thing was checked
+ */
+export declare function nothingCheckedFinding(denominator: number, issues: readonly ValidationIssue[], message: () => string): readonly ValidationIssue[];
+//# sourceMappingURL=run-integrity.d.ts.map

package/dist/utils/run-integrity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-integrity.d.ts","sourceRoot":"","sources":["../../src/utils/run-integrity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,0BAA0B,CAAC;AAE1D;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAEpE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,OAAO,EAAE,MAAM,MAAM,GACpB,SAAS,eAAe,EAAE,CAI5B"}