@vibe-agent-toolkit/cli 0.1.42 → 0.2.0-rc.10

package/dist/commands/resources/check.d.ts

@@ -0,0 +1,593 @@
+/**
+ * `vat resources check` — run the project's own assertions over its resource
+ * projection, as a gate.
+ *
+ * The invariants this file implements are written down once, in
+ * `docs/architecture/cli.md` under "`vat resources check [path]`". Read that
+ * before changing anything here; the headlines, so a reader knows when to:
+ *
+ * - 🔑 **Four ways to check nothing are all refusals**, at error severity under
+ *   the non-overridable `RESOURCE_CHECK_BROKEN`: a statement that will not run
+ *   (the `catch` in `runUnits`), a corpus that enumerated empty
+ *   ({@link emptyCorpusFinding}), a `--check` name nothing declares
+ *   (`requireKnownCheck`), and not one check executed at all
+ *   ({@link noCheckRanFinding}, derived in {@link buildCheckOutputData} so an
+ *   emptied `BUILTIN_CHECKS` cannot publish a clean document).
+ * - ⚠️ That last one does NOT make the step always able to fail: the only
+ *   built-in ships at `info`. Do not invent a second refusal for it — that
+ *   would refuse the no-config run the default set exists to serve.
+ * - 🔑 **No built-in check may be SQL.** {@link checkCommand} reads
+ *   `config?.resources?.checks` and nothing else for statements; built-ins are
+ *   TypeScript predicates over the row model, and a built-in's `sqlTwin` is
+ *   documentation an adopter copies, never executed here.
+ * - 🔑 **The default set belongs to the pipeline, not the config file.**
+ *   `BUILTIN_CHECKS` reaches {@link runProjectChecks} as a REQUIRED `builtins`
+ *   argument via {@link runOutcome}; nothing on that path reads `config`.
+ * - 🚨 **Adopter SQL runs unsandboxed on purpose, and contributed SQL is not
+ *   adopter SQL** — a contributed statement ships as a reviewed example.
+ * - ⛔ A TypeScript/SQL twin is documentation and a differential oracle, never
+ *   a runtime optimizer to schedule between.
+ */
+import { type BoundBuiltinCheck, type ResourceCheck } from '@vibe-agent-toolkit/resources';
+import { type Report, type ValidationIssue } from '@vibe-agent-toolkit/schema';
+import { z } from 'zod';
+import { type SeverityOverrides } from '../../utils/issue-severity.js';
+import { type Logger } from '../../utils/logger.js';
+import { type AskProjection, type PopulationExtent, type ProjectionProvenance } from '../../utils/projection-query.js';
+import { type ProgressEntry } from './check-progress.js';
+import { type AbnormalDeath } from './check-supervisor.js';
+/**
+ * Where a supervised run announces what it is doing, one unit at a time.
+ *
+ * A plain callback rather than the writer itself, so the loop knows nothing
+ * about files: the unit suite hands it an array, the supervised child hands it
+ * {@link createProgressWriter}'s append, and `--budget 0` hands it nothing.
+ */
+export type ProgressSink = (entry: ProgressEntry) => void;
+interface CheckOptions {
+    debug?: boolean;
+    /** Run only this check, by its config key. */
+    check?: string;
+    /** `yaml` (default) or `json`. Same document either way. */
+    format?: string;
+    /**
+     * How long the run may go WITHOUT completing a unit of work, in seconds.
+     * `0` removes the bound and keeps everything in this process.
+     */
+    budget?: string;
+    /**
+     * Hidden. Where to append progress — and, by its mere presence, the
+     * instruction to do the work here rather than supervise a child that does.
+     * Set by {@link childArgs} and by nothing else; an operator passing it by hand
+     * gets an unsupervised run and a log file, which is harmless.
+     */
+    costLog?: string;
+}
+/**
+ * What one declared check cost, and what it found.
+ *
+ * 🚨 **The population is charged to NOBODY, and that is deliberate.**
+ * {@link durationMs} is the STATEMENT alone; the shared setup is published as
+ * `populationSecs`. Why, and the pooled-arm defect this avoids:
+ * `docs/architecture/cli.md`, "The population is charged to NOBODY".
+ */
+export interface CheckCost {
+    /** The check's key in `resources.checks`, or a built-in's name. */
+    readonly name: string;
+    /** Wall time of this check's selection, and of nothing it shares with others. */
+    readonly durationMs: number;
+    /** Rows the selection returned — the violations it found. Absent when it did not run. */
+    readonly rows?: number;
+    /** Set when the check threw. One that did not complete has no row count. */
+    readonly broken?: true;
+    /**
+     * Set when VAT supplied this check rather than the project. 🔑 Without it a
+     * reader whose config declares nothing finds a rule they never wrote in
+     * `checks[]` with no way to tell a default from a stale declaration — or, when
+     * a project declares a check of the same name, to tell the two entries apart.
+     */
+    readonly builtin?: true;
+}
+/** What one run of the checks produced. */
+interface CheckOutcome extends ProjectionProvenance, PopulationExtent {
+    issues: readonly ValidationIssue[];
+    /**
+     * One record per check that actually ran — the denominator every count below
+     * is read against, and what each of them cost.
+     *
+     * 🔑 A LIST rather than a count beside a list. `checksRun` used to be carried
+     * separately and is now derived from `costs.length`, because two numbers that
+     * must agree are a drift bug with no gate on it: nothing fails when a new
+     * `continue` skips the record but not the counter, and the document then
+     * reports a denominator no published entry accounts for.
+     */
+    costs: readonly CheckCost[];
+}
+export interface CheckPayloadInput extends CheckOutcome {
+    root: string;
+    durationMs: number;
+}
+/**
+ * What the check run reports beyond its findings.
+ *
+ * The envelope's `examined` is `membersEnumerated` — what the rules ran
+ * AGAINST. `checksRun` is the other denominator, the number of RULES, and both
+ * are needed: zero findings is the pass condition and either number at zero
+ * makes that pass vacuous.
+ */
+export declare const CheckDataSchema: z.ZodObject<{
+    root: z.ZodString;
+    /** Whether the projection was derived this run or read from the store. */
+    population: z.ZodEnum<["derived", "store"]>;
+    /** What the population cost — charged to no check, see `CheckCost`. */
+    populationSecs: z.ZodNumber;
+    /** What evaluating the lenses cost, paid before the first statement ran. */
+    lensSecs: z.ZodNumber;
+    /**
+     * Which lenses that covers — the derived relations this run's checks could
+     * actually read. 🔑 An empty list says "no check asked for a derived relation"
+     * rather than "a lens stopped running"; without it `lensSecs: 0` is the same
+     * document either way, and a gate whose rules silently read empty relations is
+     * a gate that cannot fail.
+     */
+    lensesEvaluated: z.ZodArray<z.ZodString, "many">;
+    /**
+     * The prose frame {@link CheckDataSchema.limits} is read under. Present
+     * exactly when a lens with stated bounds was evaluated.
+     */
+    boundsStatement: z.ZodOptional<z.ZodString>;
+    /**
+     * What the derived rows this run could read do NOT settle — signed and
+     * directional, the same list `vat claude context` publishes beside its own
+     * answer. Absent when no bounded lens ran: an empty list would claim nothing
+     * bounds the answer, which is stronger than "the answer holds no such row".
+     */
+    limits: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        direction: z.ZodEnum<["over-report", "under-report", "scope", "assumption"]>;
+        statement: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        direction: "scope" | "over-report" | "under-report" | "assumption";
+        statement: string;
+    }, {
+        id: string;
+        direction: "scope" | "over-report" | "under-report" | "assumption";
+        statement: string;
+    }>, "many">>;
+    /** The number of rules that EXECUTED. Derived from `checks`, never carried beside it. */
+    checksRun: z.ZodNumber;
+    /** What each rule cost, directly under the denominator it is the breakdown of. */
+    checks: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        /** Three significant figures, so a 0.4 ms rule serializes as 0.0004 rather than a zero that reads as "not measured". */
+        durationSecs: z.ZodNumber;
+        /** Rows the statement returned. ABSENT, never 0, when the statement did not complete. */
+        rows: z.ZodOptional<z.ZodNumber>;
+        broken: z.ZodOptional<z.ZodLiteral<true>>;
+        /** Present and `true` only for a rule VAT supplied — see {@link CheckCost.builtin}. */
+        builtin: z.ZodOptional<z.ZodLiteral<true>>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        durationSecs: number;
+        rows?: number | undefined;
+        broken?: true | undefined;
+        builtin?: true | undefined;
+    }, {
+        name: string;
+        durationSecs: number;
+        rows?: number | undefined;
+        broken?: true | undefined;
+        builtin?: true | undefined;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    root: string;
+    population: "derived" | "store";
+    lensesEvaluated: string[];
+    populationSecs: number;
+    lensSecs: number;
+    checksRun: number;
+    checks: {
+        name: string;
+        durationSecs: number;
+        rows?: number | undefined;
+        broken?: true | undefined;
+        builtin?: true | undefined;
+    }[];
+    boundsStatement?: string | undefined;
+    limits?: {
+        id: string;
+        direction: "scope" | "over-report" | "under-report" | "assumption";
+        statement: string;
+    }[] | undefined;
+}, {
+    root: string;
+    population: "derived" | "store";
+    lensesEvaluated: string[];
+    populationSecs: number;
+    lensSecs: number;
+    checksRun: number;
+    checks: {
+        name: string;
+        durationSecs: number;
+        rows?: number | undefined;
+        broken?: true | undefined;
+        builtin?: true | undefined;
+    }[];
+    boundsStatement?: string | undefined;
+    limits?: {
+        id: string;
+        direction: "scope" | "over-report" | "under-report" | "assumption";
+        statement: string;
+    }[] | undefined;
+}>;
+export type CheckData = z.infer<typeof CheckDataSchema>;
+/** The document this command publishes. */
+export declare const CHECK_REPORT_SCHEMA: import("@vibe-agent-toolkit/schema").ReportZodSchema<z.ZodObject<{
+    root: z.ZodString;
+    /** Whether the projection was derived this run or read from the store. */
+    population: z.ZodEnum<["derived", "store"]>;
+    /** What the population cost — charged to no check, see `CheckCost`. */
+    populationSecs: z.ZodNumber;
+    /** What evaluating the lenses cost, paid before the first statement ran. */
+    lensSecs: z.ZodNumber;
+    /**
+     * Which lenses that covers — the derived relations this run's checks could
+     * actually read. 🔑 An empty list says "no check asked for a derived relation"
+     * rather than "a lens stopped running"; without it `lensSecs: 0` is the same
+     * document either way, and a gate whose rules silently read empty relations is
+     * a gate that cannot fail.
+     */
+    lensesEvaluated: z.ZodArray<z.ZodString, "many">;
+    /**
+     * The prose frame {@link CheckDataSchema.limits} is read under. Present
+     * exactly when a lens with stated bounds was evaluated.
+     */
+    boundsStatement: z.ZodOptional<z.ZodString>;
+    /**
+     * What the derived rows this run could read do NOT settle — signed and
+     * directional, the same list `vat claude context` publishes beside its own
+     * answer. Absent when no bounded lens ran: an empty list would claim nothing
+     * bounds the answer, which is stronger than "the answer holds no such row".
+     */
+    limits: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        direction: z.ZodEnum<["over-report", "under-report", "scope", "assumption"]>;
+        statement: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        direction: "scope" | "over-report" | "under-report" | "assumption";
+        statement: string;
+    }, {
+        id: string;
+        direction: "scope" | "over-report" | "under-report" | "assumption";
+        statement: string;
+    }>, "many">>;
+    /** The number of rules that EXECUTED. Derived from `checks`, never carried beside it. */
+    checksRun: z.ZodNumber;
+    /** What each rule cost, directly under the denominator it is the breakdown of. */
+    checks: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        /** Three significant figures, so a 0.4 ms rule serializes as 0.0004 rather than a zero that reads as "not measured". */
+        durationSecs: z.ZodNumber;
+        /** Rows the statement returned. ABSENT, never 0, when the statement did not complete. */
+        rows: z.ZodOptional<z.ZodNumber>;
+        broken: z.ZodOptional<z.ZodLiteral<true>>;
+        /** Present and `true` only for a rule VAT supplied — see {@link CheckCost.builtin}. */
+        builtin: z.ZodOptional<z.ZodLiteral<true>>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        durationSecs: number;
+        rows?: number | undefined;
+        broken?: true | undefined;
+        builtin?: true | undefined;
+    }, {
+        name: string;
+        durationSecs: number;
+        rows?: number | undefined;
+        broken?: true | undefined;
+        builtin?: true | undefined;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    root: string;
+    population: "derived" | "store";
+    lensesEvaluated: string[];
+    populationSecs: number;
+    lensSecs: number;
+    checksRun: number;
+    checks: {
+        name: string;
+        durationSecs: number;
+        rows?: number | undefined;
+        broken?: true | undefined;
+        builtin?: true | undefined;
+    }[];
+    boundsStatement?: string | undefined;
+    limits?: {
+        id: string;
+        direction: "scope" | "over-report" | "under-report" | "assumption";
+        statement: string;
+    }[] | undefined;
+}, {
+    root: string;
+    population: "derived" | "store";
+    lensesEvaluated: string[];
+    populationSecs: number;
+    lensSecs: number;
+    checksRun: number;
+    checks: {
+        name: string;
+        durationSecs: number;
+        rows?: number | undefined;
+        broken?: true | undefined;
+        builtin?: true | undefined;
+    }[];
+    boundsStatement?: string | undefined;
+    limits?: {
+        id: string;
+        direction: "scope" | "over-report" | "under-report" | "assumption";
+        statement: string;
+    }[] | undefined;
+}>>;
+export type CheckReport = Report<CheckData>;
+/**
+ * Build the check report.
+ *
+ * Pure: no file system, no clock, no `process.exit` — the same contract every
+ * other payload builder here follows, so the document's shape stays under unit
+ * test rather than only under a CLI spawn.
+ *
+ * `checksRun` is published beside the counts and is not decoration: zero
+ * findings from four checks and zero findings from **no** checks are the same
+ * document without it, and they mean opposite things. A project whose config key
+ * is misspelled would otherwise read as passing. It is DERIVED from the `checks`
+ * list rather than carried alongside it, so the denominator and the entries that
+ * account for it cannot disagree.
+ *
+ * 🚨 `populationSecs` and the per-check `durationSecs` do not overlap and do not
+ * sum to `durationMs`. The population is paid once and shared by every check;
+ * see {@link CheckCost} for why it is charged to none of them.
+ *
+ * 🔑 A denominator of zero is refused HERE rather than published — see
+ * {@link noCheckRanFinding}. This is the one function every lane's document
+ * passes through, so deriving the refusal in it is what makes "checked nothing,
+ * status clean" unrepresentable rather than merely unwritten.
+ *
+ * 🪤 The findings are NOT run through `relativizePathEntries`. Every other
+ * payload builder re-bases here because its producer keeps absolute paths
+ * internally; these arrive project-relative instead, and re-basing an
+ * already-relative path would resolve it against the wrong base and silently
+ * corrupt it. The guarantee is `locationOf` in `sql-checks.ts` — the one place
+ * a projection column becomes a finding's `location`, and which refuses an
+ * absolute or backslashed value there. Nothing on this path parses findings
+ * through the schema at runtime, and do not "fix" that by parsing at this
+ * boundary: it would convert a slip in `locationOf` from "this finding loses
+ * its anchor" into "the whole run throws", which is strictly worse for a gate.
+ *
+ * @param input - The findings and the provenance of the run behind them
+ * @returns The document to serialize
+ */
+export declare function buildCheckOutputData(input: CheckPayloadInput): CheckReport;
+/**
+ * Refuse a `--check` name that names neither a built-in nor a declared check.
+ *
+ * 🔑 **An unknown name is otherwise a silent green.** With nothing comparing the
+ * flag against the known names, `--check nope` filters every check away, runs
+ * none, and exits 0 with `checksRun: 0` and `issues: []` on empty stderr — and
+ * the "no checks are declared" warning does not fire, because it asks whether
+ * the `checks` MAP is empty, never whether the FILTER matched anything. Not a
+ * hypothetical typo: rename or delete a check and the CI step keeps passing
+ * forever while asserting nothing.
+ *
+ * Thrown rather than reported as a finding, because it is an OPERATOR error and
+ * not a content violation — the two have different exit codes in this command's
+ * contract (2 versus 1) and different audiences. Thrown before the projection is
+ * populated, so a mistyped flag costs no crawl.
+ *
+ * 🔑 **A built-in is nameable here exactly like a declared one.** A guard that
+ * only knew the config would refuse the very rules that run when there is no
+ * config at all. The refusal names both sets.
+ *
+ * @param builtinNames - The default set's names — {@link BUILTIN_CHECK_NAMES} in
+ *   production, and passed in rather than imported here so a test can prove the
+ *   guard rather than restate the constant
+ * @param checks - The project's `resources.checks`
+ * @param only - The `--check` value, or undefined
+ * @throws When `only` names no check this run would attempt
+ */
+export declare function requireKnownCheck(builtinNames: readonly string[], checks: Readonly<Record<string, ResourceCheck>>, only: string | undefined): void;
+/**
+ * Name every `CUSTOM:` severity override that overrides nothing.
+ *
+ * 🔑 **The same silent-green shape as an unknown `--check` name, one surface
+ * over.** {@link requireKnownCheck} refuses `--check nope` because a filter
+ * that matched nothing ran nothing and exited 0. A `validation.severity` entry
+ * keyed `CUSTOM:<name>` for a check that is not declared is the mirror image: it
+ * parses (the schema validates the KEY's shape and cannot see
+ * `resources.checks`), applies to no finding, and says nothing. An adopter
+ * renames a check and leaves the override behind, or mistypes it while standing
+ * down an inherited one — and in the second direction the check they meant to
+ * silence keeps failing their build with no clue why.
+ *
+ * ⚠️ **A warning, not a refusal, and the asymmetry with `--check` is
+ * deliberate.** `--check` is a flag typed for THIS run, so a mistake is an
+ * operator error and exiting 2 costs nothing. A `severity` entry lives in a
+ * committed config that may legitimately be shared across repositories or
+ * outlive a check through a rename in flight; refusing it would be a new
+ * breaking config error, which is exactly the change this release already
+ * decided not to make twice (see `ResourcesConfigSchema`). Stderr, so the
+ * document on stdout stays parseable — the same channel and the same reasoning
+ * as the "no checks are declared" warning in {@link checkCommand}.
+ *
+ * 📌 The registry half of the key space needs no equivalent: a misspelled
+ * REGISTRY code is already refused by `SeverityOverrideCodeSchema`, whose
+ * `SEVERITY_KEY_PATTERN` alternates every registry code name with the `CUSTOM:`
+ * namespace — so a key has to BE one of the shipped codes to match that half.
+ * Only the open `CUSTOM:` half can name something that does not exist, because
+ * only it matches on shape rather than on identity.
+ *
+ * @param checks - The project's `resources.checks`
+ * @param validation - The project's `resources.validation`, or undefined
+ * @param logger - Where the warning goes (stderr)
+ */
+export declare function warnUndeclaredOverrides(checks: Readonly<Record<string, ResourceCheck>>, validation: SeverityOverrides | undefined, logger: Logger): void;
+/**
+ * How a supervised run stopped short of publishing its own document.
+ *
+ * Two endings, and telling them apart is the whole reason this is a type rather
+ * than a number. A watchdog kill means *no progress within the budget*, and the
+ * remedy may genuinely be a larger bound. An abnormal death means *the run
+ * died* — most often out of memory — and there the budget was never involved,
+ * so advice to raise it is a false diagnosis that makes the situation worse.
+ */
+export type CheckRunEnding = {
+    readonly kind: 'budget';
+    readonly budgetSecs: number;
+} | {
+    readonly kind: 'abnormal';
+    readonly death: AbnormalDeath;
+};
+/**
+ * The exit code Node uses for its own fatal abort, on EVERY platform.
+ *
+ * 🚨 **This is measured, and it is NOT the local platform's signal number.** On
+ * macOS and Linux 134 is the shell encoding `128 + SIGABRT`, where `SIGABRT` is
+ * 6. On Windows `os.constants.signals.SIGABRT` is **22** — MSVC numbers it
+ * differently — so deriving the code from that table gives 150 and matches
+ * nothing Node ever emits. A `windows-latest` run of the heap-abort case
+ * reported exactly **134**, the same as Unix: the number comes from Node's own
+ * abort path, not from the platform's signal table.
+ *
+ * 🪤 An earlier version of this file DID derive it from `os.constants.signals`,
+ * and its unit test derived the same way — so the test agreed with the code, the
+ * round-trip passed on every machine, and the pair was wrong together on the one
+ * platform the branch exists for. The value is therefore pinned as a measured
+ * fact, and a test asserts the number itself rather than re-deriving it.
+ *
+ * ⛔ Not a version constant: it decides nothing about whether stored data is
+ * still valid. It is an external protocol value, like an API header.
+ */
+export declare const NODE_FATAL_ABORT_EXIT_CODE = 134;
+/**
+ * Rebuild the document from what an INTERRUPTED run left on disk.
+ *
+ * Both interruptions come here — the watchdog's kill and an abnormal death —
+ * because everything below this line is identical for them: the same recovered
+ * costs, the same non-overridable finding, the same refusal when there is no
+ * population. Only the sentences differ, and {@link CheckRunEnding} carries that.
+ *
+ * 🔑 It feeds {@link buildCheckOutputData}, the SAME builder a completed run
+ * uses. A second payload builder for this lane would be a second shape to
+ * keep in step with every future field — and the failure mode is silent, because
+ * nobody reads an interrupted run's document until the day they need it.
+ *
+ * 🚨 **A run interrupted during POPULATION gets no document at all.** There is no
+ * projection, so `population`, `populationSecs` and `membersEnumerated` have no
+ * honest value — and inventing `membersEnumerated: 0` would be worse than a
+ * blank, because that value already MEANS "this gate ran over an empty corpus",
+ * which is a different and wrong claim. The throw becomes an operator error
+ * (exit 2) through the same `handleReportCommandError` path everything else here uses.
+ *
+ * @param options - The wreckage
+ * @param options.entries - What `parseProgressLog` recovered
+ * @param options.root - The corpus root the parent resolved
+ * @param options.ending - Which way the run was interrupted
+ * @param options.durationMs - Wall time from spawn to ending
+ * @returns The input to {@link buildCheckOutputData}
+ * @throws When the child never reported a completed population
+ */
+export declare function buildInterruptedCheckInput(options: {
+    entries: readonly ProgressEntry[];
+    root: string;
+    ending: CheckRunEnding;
+    durationMs: number;
+}): CheckPayloadInput;
+/**
+ * Run this project's checks — VAT's default set plus whatever the project
+ * declared — and resolve their severities: the whole of this verb's logic, with
+ * the database taken out.
+ *
+ * 🔑 **`builtins` is a required argument beside `checks`, never a default inside
+ * this function.** That is what makes "the default set belongs to the pipeline,
+ * not to the config file" a property of the signature — nobody can get the
+ * defaults by omitting an argument or lose them by supplying no config.
+ *
+ * Exported and pure so the loop is provable without a spawn. It was not: every
+ * spawned case declared ONE check (the `--check` case declares two and filters
+ * to one, which the loop cannot distinguish), so `checksRun` was never observed
+ * above 1 and a `break` at the end of the loop would have left the suite green.
+ *
+ * Pure in the same sense the payload builder is, with ONE seam: it reads a
+ * clock. That is why the clock is a parameter — the measurement is the point of
+ * the `costs` it returns, and a duration nothing can pin is a number nobody can
+ * trust.
+ *
+ * @param options - The run
+ * @param options.builtins - The default set, already bound to this run's
+ *   projection. Required, and `[]` is a deliberate statement rather than an
+ *   omission
+ * @param options.checks - The declared checks
+ * @param options.only - A single check name, or undefined for all
+ * @param options.ask - Runs one statement against the populated projection
+ * @param options.validation - The project's severity overrides, or undefined
+ * @param options.membersEnumerated - How many members the population enumerated.
+ *   Told rather than asked, because no answer can reveal it: an `ask` over an
+ *   empty projection and an `ask` over a clean one both return no rows
+ * @param options.now - The measurement clock in milliseconds, defaulting to
+ *   `performance.now()`. Injected only so a unit test can pin an exact per-check
+ *   duration; nothing in production passes it
+ * @param options.onProgress - Where each check's `start` and cost are announced
+ *   so an outside supervisor can see them, or undefined when the run is not
+ *   supervised. Optional rather than required because `--budget 0` and every
+ *   unit case run with nobody watching
+ * @returns The resolved findings, and one cost record per check that ran
+ */
+export declare function runProjectChecks(options: {
+    builtins: readonly BoundBuiltinCheck[];
+    checks: Readonly<Record<string, ResourceCheck>>;
+    only: string | undefined;
+    ask: AskProjection;
+    validation: SeverityOverrides | undefined;
+    membersEnumerated: number;
+    now?: () => number;
+    onProgress?: ProgressSink | undefined;
+}): {
+    issues: ValidationIssue[];
+    costs: CheckCost[];
+};
+/**
+ * Run the project's declared checks against its projection.
+ *
+ * ## 🚨 Why this verb spawns a child and `vat resources query` does not
+ *
+ * Both verbs run SQL an adopter wrote, over the same projection, through the
+ * same `withQueriedProjection` — which does NOT diverge here, and must not. The
+ * fork is this function and nothing below it.
+ *
+ * `query`'s author is at the keyboard, and Ctrl-C already works for them. It
+ * works for one reason worth stating, because it is fragile: NO signal handler
+ * is installed anywhere on this path. A process blocked in synchronous
+ * `node:sqlite` dies instantly on SIGINT while that remains true, and SURVIVES
+ * SIGINT and SIGTERM the moment a handler exists — the handler is a JS callback
+ * and the event loop that would schedule it is the blocked resource. Adding one
+ * would take Ctrl-C away from `query` without adding anything to `check`.
+ *
+ * `check` runs unattended in CI, where nobody is there to press it. So it gets a
+ * bound enforced from outside itself, and a hang becomes a bounded failure
+ * instead of a job that burns its runner minutes and reports nothing.
+ *
+ * ## `[path]` locates the project; a `WHERE` clause is the only scope a check has
+ *
+ * Same contract as `vat resources query`, for the same reason (see
+ * `queryCommand`): the projection is the whole tracked tree, so the argument is
+ * where root discovery starts and nothing more. A locator that names no
+ * directory is refused HERE, before the fork below — the parent would otherwise
+ * resolve it silently to the cwd's project and spawn a child to run every check
+ * over a tree the operator did not name, at exit 0.
+ *
+ * @param pathArg - Where to look for the project, or omitted for the current directory
+ * @param options - Parsed command-line options
+ */
+export declare function checkCommand(pathArg: string | undefined, options: CheckOptions): Promise<void>;
+export {};
+//# sourceMappingURL=check.d.ts.map

package/dist/commands/resources/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../../src/commands/resources/check.ts"],"names":[],"mappings":"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"}