repo-contract 0.3.0 → 0.3.2

package/dist/.dts/types.d.ts

@@ -0,0 +1,424 @@
+/**
+ * Public type surface for repo-contract. Evidence describes what happened;
+ * Verdict describes whether it was acceptable. They are deliberately
+ * separate concepts (see specs/architecture.md) even though
+ * `runRepoContract` returns both together.
+ */
+import type { ChildProcess, SpawnOptions, SpawnSyncOptions, SpawnSyncReturns } from "node:child_process";
+import type { StandardSchemaV1 } from "./standard-schema/types.js";
+/** Output interpretation a check can explicitly request. No format requested means no parsing -- the consumer gets raw stdout/stderr only. */
+export type OutputFormat = "json" | "yaml" | "text";
+/**
+ * Why a check's process ended up in its terminal state. `"completed"` means
+ * the process ran to exit on its own -- the exit code may still be
+ * non-zero, and that is for the check's policy to interpret, never this
+ * package. The other five values all mean the process did not exit on its
+ * own; repo-contract terminated it, or it was terminated for a reason
+ * repo-contract can observe but did not cause.
+ *
+ * `"signaled"` specifically means a signal repo-contract did *not* itself request -- an
+ * externally-caused termination. A check killed because the *host* process running repo-contract
+ * received its own SIGINT/SIGTERM (see `run-checks.ts`'s termination-handler cleanup) is instead
+ * `"host_terminated"`: repo-contract did request that signal, just not via `options.signal` or
+ * `timeoutMs` (see `"aborted"`/`"timed_out"`), so it must not be conflated with an externally-caused
+ * `"signaled"`.
+ */
+export type CheckStatus = "completed" | "timed_out" | "signaled" | "host_terminated" | "spawn_error" | "aborted";
+/** A requested parse of a check's stdout succeeded. */
+export interface ParsedOutputSuccess<T> {
+    /** The format that was requested and successfully parsed. */
+    readonly format: OutputFormat;
+    /** Always `true`. */
+    readonly success: true;
+    /** The parsed value. */
+    readonly value: T;
+}
+/**
+ * A requested parse of a check's stdout failed. The raw stdout on the
+ * parent `CheckEvidence` is preserved unchanged -- a parse failure is never
+ * silently reinterpreted or discarded.
+ */
+export interface ParsedOutputFailure {
+    /** The format that was requested (and failed to parse). */
+    readonly format: OutputFormat;
+    /** Always `false`. */
+    readonly success: false;
+    /** The parse error's message. */
+    readonly error: string;
+}
+/** The result of a check's requested output-format parse: either a successful `ParsedOutputSuccess`, or a `ParsedOutputFailure`. */
+export type ParsedOutput<T> = ParsedOutputSuccess<T> | ParsedOutputFailure;
+/**
+ * What actually happened when one configured check ran. `output` is present
+ * only if that check's config requested a format, and is otherwise
+ * `undefined` -- a policy narrows with `ctx.result.output?.success` (or an
+ * `if (ctx.result.output) { ... }` guard) before reading `.value`/`.error`.
+ *
+ * `output.value` is the value produced by the configured `format` parser, optionally validated
+ * and (if a schema transforms/coerces it) replaced by `output.schema` (see
+ * `CheckDefinitionConfig.output.schema`) -- so it is not necessarily the raw parser result once a
+ * check's config supplies a schema. It is typed `unknown` for every format regardless, including
+ * `"text"` (even though `parseText` always produces a `string` at runtime) and regardless of
+ * whether a schema was supplied -- neither repo-contract nor TypeScript's generic inference can
+ * reliably carry a specific check's own literal `output.format` (or a specific `schema`'s own
+ * inferred output type) through to that same check's `policy` parameter once several checks with
+ * heterogeneous formats live together in one `checks` record (a real TypeScript inference
+ * limitation hit and confirmed during implementation, not a hypothetical -- see specs/decisions/
+ * for the isolated repro). This is a deliberate, acknowledged tradeoff, not a gap this package
+ * is attempting to close: a schema still gives its own author real compile-time input/output
+ * typing via `StandardSchemaV1<Input, Output>` for their own code, just not threaded through this
+ * shared `CheckEvidence` shape. A policy author narrows or casts `.value` themselves, exactly as
+ * they already must for `"json"`/`"yaml"` with no schema supplied.
+ */
+export interface CheckEvidence {
+    /** The executable that was actually spawned (after tokenization, if `run` was a string). */
+    readonly command: string;
+    /** The arguments passed to `command`, exactly as spawned. */
+    readonly args: readonly string[];
+    /** ISO 8601 timestamp of when the process was spawned. */
+    readonly startedAt: string;
+    /** ISO 8601 timestamp of when the process reached its terminal state. */
+    readonly completedAt: string;
+    /** Wall-clock time from spawn to termination, in milliseconds. */
+    readonly durationMs: number;
+    /** `null` when the process never exited normally -- see `signal` and `status`. */
+    readonly exitCode: number | null;
+    /** The signal that terminated the process, if any. `null` for a normal exit or a spawn failure. */
+    readonly signal: NodeJS.Signals | null;
+    /** The process's raw standard output, captured verbatim up to an internal size cap (10 MiB); content beyond the cap is replaced with a truncation marker. */
+    readonly stdout: string;
+    /** The process's raw standard error, captured verbatim up to an internal size cap (10 MiB); content beyond the cap is replaced with a truncation marker. */
+    readonly stderr: string;
+    /** Why the process reached its terminal state; see `CheckStatus`. */
+    readonly status: CheckStatus;
+    /** Populated only for `status === "spawn_error"` -- the underlying Node error message (e.g. "spawn foo ENOENT"). Never populated for any other status. */
+    readonly spawnError?: string;
+    /** Populated only for `status === "spawn_error"` -- the underlying Node `ErrnoException`'s structured `.code` (e.g. `"ENOENT"`, `"EACCES"`), when Node provides one. Never populated for any other status. Distinguishes "the executable does not exist" from other spawn failures (permission denied, invalid executable format, etc.) without parsing `spawnError`'s free-text message. */
+    readonly spawnErrorCode?: string;
+    /**
+     * The parsed interpretation of `stdout`, present only if this check's config requested a
+     * `format`. If that config also supplied `output.schema`, a successful parse is additionally
+     * validated (and possibly transformed) by that schema before landing here -- see this
+     * interface's own doc comment above and `CheckDefinitionConfig.output.schema`.
+     */
+    readonly output?: ParsedOutput<unknown>;
+}
+/**
+ * Versioned, immutable record of one complete `runRepoContract` execution --
+ * every configured check's evidence, plus timing for the run as a whole.
+ * Says nothing about whether any of it was acceptable; see `Verdict`.
+ * Additive fields are a compatible change; changing or removing an existing
+ * field requires bumping this version number (see VERSIONING.md).
+ */
+export interface Evidence<TChecks extends CheckSchema = CheckSchema> {
+    /** Schema version of this shape; see VERSIONING.md. */
+    readonly version: 1;
+    /** ISO 8601 timestamp of when the run began. */
+    readonly startedAt: string;
+    /** ISO 8601 timestamp of when the last check finished. */
+    readonly completedAt: string;
+    /** Wall-clock time for the run as a whole, in milliseconds. */
+    readonly durationMs: number;
+    /** Each configured check's own evidence, keyed by check id. */
+    readonly checks: {
+        readonly [K in keyof TChecks]: CheckEvidence;
+    };
+}
+/**
+ * What a check's `policy` function is called with. `result` is that check's
+ * own evidence; `evidence` is the complete run's evidence, including every
+ * sibling check -- present so a policy can make cross-check decisions (e.g.
+ * "only enforce the mutation-score threshold if the tests check passed").
+ * By the time any policy runs, every check has already finished executing
+ * and every check's evidence has already been assembled -- no policy ever
+ * observes a partially-populated `evidence` (see specs/architecture.md).
+ */
+export interface PolicyContext<TChecks extends CheckSchema = CheckSchema> {
+    /** This check's own evidence. */
+    readonly result: CheckEvidence;
+    /** The complete run's evidence, including every sibling check. */
+    readonly evidence: Evidence<TChecks>;
+    /**
+     * This check's own declared `dependsOn` dependencies' evidence, keyed by
+     * check id -- a convenience view, fully derivable from `evidence.checks`
+     * plus this check's own `dependsOn`, provided so no policy has to do that
+     * lookup itself. `{}` for a check with no `dependsOn` -- always an
+     * object, never `undefined`, matching how `evidence.checks` is already
+     * used today (a policy narrows a specific key's presence, never the
+     * field itself). Evidence only, not policy outcomes -- a dependency's
+     * policy result stays visible only via the top-level `Verdict`, exactly
+     * as today; this keeps policy evaluation itself fully parallel and
+     * unaffected by `dependsOn`.
+     */
+    readonly dependencies: Readonly<Record<string, CheckEvidence>>;
+}
+/**
+ * `"pass"`: the repository-owned policy evaluated the captured evidence as
+ * satisfying its configured requirements. `"fail"`: the evidence did not
+ * satisfy them. `"warn"`: the evidence does not violate the policy's
+ * blocking requirements, but the policy has intentionally decided the
+ * condition is materially relevant and wants it surfaced -- not a synonym
+ * for "minor failure"; a `warn` never fails `Verdict.passed` (see
+ * `runPolicies` in `src/policy/run-policies.ts`).
+ */
+export type PolicyOutcome = "pass" | "fail" | "warn";
+/**
+ * A repository-owned policy's interpretation of one check's captured
+ * evidence -- fully JSON-serializable (a plain object of primitives only,
+ * never an `Error`, class instance, function, or tool-specific object) so it
+ * can be persisted, transmitted, aggregated across parallel checks, and
+ * consumed directly by a human or an AI without rerunning anything.
+ *
+ * `rationale` is mandatory and must contain enough actionable detail --
+ * specific file/line locations, rule ids, test names, counts -- for a
+ * consumer to understand *why* the policy reached its outcome from this
+ * value alone. A rationale like "see output above" or "check the report for
+ * details" defeats the purpose: it forces the consumer back to raw,
+ * unstructured command output, exactly what this type exists to avoid. See
+ * specs/architecture.md for the evidence/rationale/judgment distinction this
+ * type is built around: evidence answers "what happened?", `rationale`
+ * answers "what does the repository's policy conclude about what
+ * happened?", and a policy's `outcome` is not the final word -- a human or
+ * AI consumer still makes the final judgment call using both.
+ */
+export interface PolicyResult {
+    /** The policy's pass/fail/warn decision. */
+    readonly outcome: PolicyOutcome;
+    /** Why the policy reached `outcome`, in enough detail to act on without rerunning anything. */
+    readonly rationale: string;
+}
+/**
+ * A repository-owned decision about whether one check's evidence is
+ * acceptable. Returns a `PolicyResult` -- never a bare boolean or string --
+ * so a policy can communicate more than pass/fail even when the run is
+ * otherwise acceptable (see `PolicyResult`/`PolicyOutcome`). May be
+ * synchronous or return a `Promise`. repo-contract does not interpret
+ * `rationale` beyond storing and surfacing it verbatim; the package has no
+ * opinion about what makes a check pass, fail, or warrant a `warn`.
+ */
+export type Policy<TChecks extends CheckSchema = CheckSchema> = (ctx: PolicyContext<TChecks>) => PolicyResult | Promise<PolicyResult>;
+/** One partially configured check: how to run it, how (if at all) to interpret its output, and the policy that decides whether its evidence is acceptable. */
+export interface CheckDefinitionConfig {
+    /**
+     * The command to run. A `string` is tokenized into executable + arguments
+     * without invoking a shell -- shell operators (`;`, `&`, `|`, backticks,
+     * `$(`, `<`, `>`, newlines) are rejected with a configuration error rather
+     * than silently passed through as literal arguments, since a string
+     * containing one almost always reflects a mistaken assumption that shell
+     * interpretation is happening. Glob characters (`*`, `?`, `~`, `[`, `]`,
+     * `{`, `}`) are NOT rejected -- they are common, legitimate literal argv
+     * content (e.g. `eslint "src/**\/*.ts"`) that many CLI tools glob-expand
+     * internally, and carry no shell-injection risk when no shell is invoked.
+     * An array bypasses tokenization entirely and is used as argv verbatim.
+     */
+    readonly run: string | readonly string[];
+    /**
+     * Opt into real shell execution instead of the safe argv-only default.
+     * When `true` (or left unset with `RepoContractConfig.shell: true` as the
+     * run-wide default -- see that field), `run` must be a `string` and is
+     * passed to the platform shell as-is (via the supplied `Spawner`'s own
+     * `shell` option) -- shell metacharacter rejection does not apply. See
+     * SECURITY.md before enabling this.
+     */
+    readonly shell?: boolean;
+    /** Working directory for the spawned process. Defaults to the current process's `cwd`. */
+    readonly cwd?: string;
+    /** Additional environment variables for the spawned process, applied on top of (or, if `inheritEnv` is `false`, instead of) the inherited environment. */
+    readonly env?: Readonly<Record<string, string>>;
+    /** Whether the spawned process inherits `process.env`. Defaults to `true` -- most check commands (npm scripts, locally-installed CLIs) need `PATH` and similar to resolve at all. Set to `false` for a minimal environment containing only `env` (plus whatever the OS itself always provides). */
+    readonly inheritEnv?: boolean;
+    /** Maximum time to let this check's process run before it is terminated and recorded with `status: "timed_out"`. No timeout by default. */
+    readonly timeoutMs?: number;
+    /** Request that stdout be parsed as this format. Omit for no parsing -- the consumer gets raw stdout/stderr only. */
+    readonly output?: {
+        readonly format: OutputFormat;
+        /**
+         * An optional Standard Schema-compliant validator (Zod, Valibot, ArkType, or any other
+         * implementation of https://standardschema.dev), run once the requested `format` parse
+         * itself succeeds. repo-contract never imports a schema library itself --
+         * `StandardSchemaV1` is hand-vendored (see `src/standard-schema/types.ts`) purely as a
+         * type-level contract, so accepting any consumer's own schema object costs zero new
+         * runtime or dev dependencies (see
+         * specs/decisions/0012-hand-vendored-standard-schema-support-for-optional-output-validation.md). A successful
+         * `~standard.validate()` result *replaces* the parsed value on `CheckEvidence.output.value`
+         * (letting a schema transform, not just check, its input); a failing result becomes an
+         * ordinary `ParsedOutputFailure`, indistinguishable in shape from a malformed-JSON/YAML
+         * parse failure -- both are "this check's output isn't what was expected," reported as
+         * data, never a throw (see `parseOutput`). `validate()` itself throwing or rejecting is a
+         * different case -- a bug in the supplied schema, not malformed output -- and surfaces as
+         * `StandardSchemaValidateThrewError` instead (see that error's own doc comment). Like every
+         * other format's `value`, `schema`'s inferred output type is *not* threaded to
+         * `CheckEvidence.output.value`'s declared type -- it stays `unknown`, for the same
+         * heterogeneous-checks-in-one-record TypeScript inference limitation already documented on
+         * `CheckEvidence` above; a policy still narrows or casts `.value` itself, now
+         * shaped/transformed by `schema` at runtime even though the type alone doesn't say so.
+         */
+        readonly schema?: StandardSchemaV1;
+    };
+    /**
+     * A full scheduling barrier at this check's own position in the `checks` object: it does not
+     * spawn until every check declared *earlier* has reached a terminal status (nothing "currently in
+     * flight" when its turn comes can be anything other than an earlier-declared check, since nothing
+     * declared later has even been reached yet), and every check declared *after* it waits for it in
+     * turn -- so nothing overlaps it in either direction. Purely a scheduling primitive for a check
+     * whose own tooling spawns concurrent workers that would otherwise contend with the rest of the
+     * run for machine resources (e.g. Stryker's own worker pool); it expresses no need for any other
+     * check's evidence, only for the machine to itself, and never appears in a policy's
+     * `ctx.dependencies` or in a partial `options.checks` run's transitive closure on its own (an
+     * explicit `dependsOn` alongside it still works exactly as it would on any other check). Defaults
+     * to `false` -- unaffected, fully-parallel scheduling in declaration order, unchanged. Two
+     * isolated checks are always sequential relative to each other (whichever is declared second
+     * waits for the first, as one of the "every check declared earlier" it's barred behind). See
+     * specs/decisions/0002-dependson-and-isolated-are-two-scheduling-primitives.md.
+     */
+    readonly isolated?: boolean;
+    /** Decides whether this check's evidence is acceptable, once its process has finished running. */
+    readonly policy: Policy;
+}
+/** One fully configured check: how to run it, how (if at all) to interpret its output, and the policy that decides whether its evidence is acceptable. */
+export interface CheckDefinition extends CheckDefinitionConfig {
+    /**
+     * Other check ids (from this same `checks` record) that must reach a
+     * terminal status -- not necessarily a passing policy -- before this
+     * check's own process is spawned. Execution ordering only: whether a
+     * dependency's *policy* passed is never consulted by repo-contract to
+     * decide whether this check's process spawns -- that is this check's
+     * own command or policy's decision (see `ctx.dependencies` on
+     * `PolicyContext`). Omit, or an empty array, for no dependencies -- the
+     * default, fully-parallel behavior, unchanged. Validated before any
+     * process spawns: every named id must exist in `checks`, a check cannot
+     * depend on itself, and -- since declaration order in the `checks` object
+     * doubles as the required topological order -- every named id must be
+     * declared *earlier* than the check declaring `dependsOn` on it (a
+     * forward reference throws `DependencyDeclaredLaterError`; a cycle is
+     * consequently impossible, since no edge can ever point forward). See
+     * specs/decisions/0002-dependson-and-isolated-are-two-scheduling-primitives.md.
+     */
+    readonly dependsOn?: readonly string[];
+}
+/** The full set of checks in a `RepoContractConfig`, keyed by check id. */
+export type CheckSchema = Record<string, CheckDefinition>;
+/**
+ * Same shape as a check schema `T`, except each check's own `dependsOn` is
+ * narrowed from `readonly string[]` to only the *other* keys of that same
+ * `T` -- so a typo'd or self-referencing id fails to compile instead of
+ * only failing at runtime (`validate-config.ts` still enforces this at
+ * runtime too, for any config that reaches `runRepoContract` without having
+ * gone through `defineRepoContract`'s static checking first, e.g. one
+ * assembled dynamically from untyped data).
+ *
+ * Used as an additional constraint on `defineRepoContract`'s parameter,
+ * intersected with `RepoContractConfig<TChecks>` rather than substituted
+ * for it -- inferring `TChecks` from the *unwrapped* `RepoContractConfig<TChecks>`
+ * position first is what keeps every check's own `policy` callback
+ * contextually typed (a real TypeScript inference limitation: inferring
+ * `TChecks` directly from a mapped/conditional type over itself, as this
+ * type is, loses that contextual typing -- confirmed during implementation,
+ * not a hypothetical).
+ */
+export type ValidatedCheckSchema<T> = {
+    readonly [K in keyof T]: T[K] extends CheckDefinitionConfig ? Omit<T[K], "dependsOn"> & {
+        readonly dependsOn?: readonly (Exclude<keyof T, K> & string)[];
+    } : never;
+};
+/**
+ * Spawns a child process, given a resolved command, argv, and options --
+ * modeled directly on `node:child_process`'s own `spawn(command, args,
+ * options)` signature so both `node:child_process.spawn` and cross-spawn's
+ * exported `spawn` are valid, drop-in values with no adapter code required
+ * (see specs/decisions/0011-process-spawning-and-ambient-environment-access-are-consumer-supplied-capabilities-not-package-owned.md).
+ * repo-contract treats whatever function is supplied as a trusted
+ * capability: it calls it with a resolved command/argv/options and does not
+ * inspect, wrap, or sanitize it -- the security properties of the spawned
+ * process are entirely the supplied function's own.
+ */
+export type Spawner = (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
+/**
+ * Synchronously spawns a child process and waits for it to exit -- modeled directly on
+ * `node:child_process`'s own `spawnSync(command, args, options)` signature, the same
+ * drop-in-compatibility approach as `Spawner`. Used only for `RepoContractConfig.killProcessTree`
+ * (Windows process-tree cleanup via `taskkill`, which fundamentally needs to run synchronously from
+ * a signal-handling context that cannot `await` anything else -- see
+ * specs/decisions/0011-process-spawning-and-ambient-environment-access-are-consumer-supplied-capabilities-not-package-owned.md).
+ * `node:child_process.spawnSync` and cross-spawn's exported `sync` are both valid, drop-in values.
+ */
+export type SyncSpawner = (command: string, args: readonly string[], options: SpawnSyncOptions) => SpawnSyncReturns<Buffer | string>;
+/** Top-level configuration passed to `defineRepoContract`/`runRepoContract`. */
+export interface RepoContractConfig<TChecks extends CheckSchema = CheckSchema> {
+    /** Every check to run, keyed by check id. */
+    readonly checks: TChecks;
+    /** Maximum number of checks to execute concurrently. Defaults to `os.availableParallelism()`. Must be a positive integer. */
+    readonly concurrency?: number;
+    /**
+     * The trusted capability repo-contract calls to spawn every check's
+     * process -- e.g. `child_process.spawn` (from `"node:child_process"`) or
+     * cross-spawn's exported `spawn`. Required: repo-contract never imports a
+     * process-spawning implementation itself (see ADR 0011 above `Spawner`).
+     * `child_process.spawn` alone does not resolve Windows `.cmd`/`.bat`
+     * shims (most npm-installed CLI tools on Windows) without `shell: true`;
+     * pass cross-spawn instead for that correctness without enabling shell
+     * metacharacter interpretation -- cross-spawn is a spawn implementation
+     * choice, not a `shell: true` equivalent. See `shell` below.
+     */
+    readonly spawn: Spawner;
+    /**
+     * The ambient environment repo-contract treats as inheritable by each
+     * check whose `inheritEnv` is not `false` (the default) -- typically
+     * `process.env`, passed straight through by reference (never copied
+     * internally) so a consumer that mutates `process.env` mid-run still sees
+     * that reflected in later-spawned checks, exactly as if repo-contract had
+     * read `process.env` itself. Required: repo-contract never reads
+     * `process.env` internally (see ADR 0011 above `Spawner`). Typed as
+     * `NodeJS.ProcessEnv` so `env: process.env` needs no casting.
+     */
+    readonly env: NodeJS.ProcessEnv;
+    /**
+     * Global default for every check's own `shell` when that check doesn't
+     * set one itself (`check.shell ?? shell ?? false`). Defaults to `false`,
+     * the safe argv-only mode -- unrelated to which `spawn` is supplied; see
+     * `spawn`'s own doc comment for that distinction.
+     */
+    readonly shell?: boolean;
+    /**
+     * The trusted capability repo-contract calls, on Windows only, to forcibly terminate a check's
+     * entire process tree (not just its immediate process) on a timeout, an aborted run, or a
+     * host-process SIGINT/SIGTERM -- e.g. `child_process.spawnSync` (from `"node:child_process"`) or
+     * cross-spawn's exported `sync`. Optional, unlike `spawn`/`env`: when omitted, Windows cleanup
+     * falls back to terminating only the check's own immediate process (not any subprocess it spawned
+     * internally) -- correct for the common case, but a check that spawns its own descendants (e.g.
+     * `npm test` spawning the real test runner) may leave them running. POSIX cleanup never needs
+     * this at all (`process.kill(-pid, signal)` reaches the whole process group directly, no spawning
+     * required) -- see specs/decisions/0011-process-spawning-and-ambient-environment-access-are-consumer-supplied-capabilities-not-package-owned.md.
+     */
+    readonly killProcessTree?: SyncSpawner;
+}
+/** Optional per-run controls for `runRepoContract`. */
+export interface RunRepoContractOptions {
+    /** Abort the entire run. Checks already in flight are terminated; checks not yet started never spawn. Every configured check still receives a well-formed evidence entry (`status: "aborted"`) and still has its policy invoked. */
+    readonly signal?: AbortSignal;
+    /** Restrict this run to only these check ids (and whatever they `dependsOn`, transitively). Every configured check runs when omitted. */
+    readonly checks?: string[];
+}
+/**
+ * Versioned, immutable aggregate result of evaluating every configured
+ * check's policy against its evidence -- each check's own `PolicyResult`,
+ * verbatim, keyed by check id. `passed` is `true` only if every check's
+ * `outcome` is `"pass"` or `"warn"` -- `"fail"` is the only outcome that
+ * fails the run; one failing check never collapses into a single generic
+ * message, every check remains individually inspectable under `checks`.
+ * Versioned independently of `Evidence` (see VERSIONING.md's
+ * schema-versioning policy) -- `version: 2` reflects `checks[id]` changing
+ * shape from `{ passed, reason? }` to a full `PolicyResult`
+ * (`{ outcome, rationale }`); see ADR 0001.
+ */
+export interface Verdict<TChecks extends CheckSchema = CheckSchema> {
+    /** Schema version of this shape; see VERSIONING.md. */
+    readonly version: 2;
+    /** `true` only if every check's `outcome` is `"pass"` or `"warn"`. */
+    readonly passed: boolean;
+    /** Each configured check's own `PolicyResult`, verbatim, keyed by check id. */
+    readonly checks: {
+        readonly [K in keyof TChecks]: PolicyResult;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/.dts/types.d.ts.map

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

package/dist/index.cjs

@@ -96,6 +96,20 @@ var ParserDependencyMissingError = class extends RepoContractError {
     this.format = format;
   }
 };
+var StandardSchemaValidateThrewError = class extends RepoContractError {
+  /** Always `"REPO_CONTRACT_STANDARD_SCHEMA_VALIDATE_THREW"`. */
+  code = "REPO_CONTRACT_STANDARD_SCHEMA_VALIDATE_THREW";
+  /** The id of the check whose `output.schema` threw during validation. */
+  checkId;
+  constructor(checkId, cause) {
+    super(
+      `Check "${checkId}"'s output.schema["~standard"].validate() threw instead of returning a Result`,
+      { cause }
+    );
+    this.name = "StandardSchemaValidateThrewError";
+    this.checkId = checkId;
+  }
+};
 var PolicyThrewError = class extends RepoContractError {
   /** Always `"REPO_CONTRACT_POLICY_THREW"`. */
   code = "REPO_CONTRACT_POLICY_THREW";
@@ -380,13 +394,46 @@ function validateOutput(checkId, output) {
   if (output === null || typeof output !== "object") {
     throw new InvalidCheckConfigError(checkId, "output must be an object when provided.");
   }
-  const { format } = output;
+  const { format, schema } = output;
   if (typeof format !== "string" || !OUTPUT_FORMATS.includes(format)) {
     throw new InvalidCheckConfigError(
       checkId,
       `output.format must be one of ${OUTPUT_FORMATS.map((f) => `"${f}"`).join(", ")}.`
     );
   }
+  validateOutputSchema(checkId, schema);
+}
+function validateOutputSchema(checkId, schema) {
+  if (schema === void 0) return;
+  if (schema === null || typeof schema !== "object" && typeof schema !== "function") {
+    throw new InvalidCheckConfigError(
+      checkId,
+      "output.schema must be a Standard Schema-compliant object or function when provided (see https://standardschema.dev)."
+    );
+  }
+  const standard = schema["~standard"];
+  if (standard === null || typeof standard !== "object") {
+    throw new InvalidCheckConfigError(
+      checkId,
+      'output.schema must have a "~standard" property (see https://standardschema.dev).'
+    );
+  }
+  const { version, vendor, validate } = standard;
+  if (version !== 1) {
+    throw new InvalidCheckConfigError(checkId, 'output.schema["~standard"].version must be 1.');
+  }
+  if (typeof vendor !== "string") {
+    throw new InvalidCheckConfigError(
+      checkId,
+      'output.schema["~standard"].vendor must be a string.'
+    );
+  }
+  if (typeof validate !== "function") {
+    throw new InvalidCheckConfigError(
+      checkId,
+      'output.schema["~standard"].validate must be a function.'
+    );
+  }
 }
 function validatePolicy(checkId, policy) {
   if (typeof policy !== "function") {
@@ -427,6 +474,28 @@ function validateDependencyGraph(checks) {
   }
 }
 
+// src/parsing/format-schema-issues.ts
+function formatSchemaIssues(issues) {
+  return `Schema validation failed: ${issues.map(formatIssue).join("; ")}`;
+}
+function formatIssue(issue) {
+  const path = formatPath(issue.path);
+  return path === "" ? issue.message : `${path}: ${issue.message}`;
+}
+function formatPath(path) {
+  if (path === void 0 || path.length === 0) return "";
+  return path.map(
+    (segment) => (
+      // eslint-disable-next-line secure-coding/no-improper-type-validation -- `segment` is declared `PropertyKey | StandardSchemaV1.PathSegment` (never `null` or an array), so `typeof segment === "object"` can only match the `PathSegment` object form here; the null/array-safe rewrite this rule suggests is flagged as an unreachable condition by @typescript-eslint/no-unnecessary-condition given that exact type, so satisfying both rules at once is impossible -- the type itself is the guarantee this check would otherwise add at runtime.
+      typeof segment === "object" ? segment.key : segment
+    )
+  ).map((key, index) => {
+    if (typeof key === "number") return `[${String(key)}]`;
+    const rendered = String(key);
+    return index === 0 ? rendered : `.${rendered}`;
+  }).join("");
+}
+
 // src/parsing/parse-json.ts
 function parseJson(stdout) {
   try {
@@ -465,7 +534,24 @@ async function parseYaml(stdout, checkId) {
 }
 
 // src/parsing/parse-output.ts
-async function parseOutput(format, stdout, checkId) {
+async function parseOutput(format, stdout, checkId, schema) {
+  const parsed = await dispatch(format, stdout, checkId);
+  if (!parsed.success || schema === void 0) return parsed;
+  let result;
+  try {
+    result = await schema["~standard"].validate(parsed.value);
+    if (typeof result !== "object" || result === null) {
+      throw new TypeError(`validate() returned ${String(result)} instead of a Result object`);
+    }
+  } catch (error) {
+    throw new StandardSchemaValidateThrewError(checkId, error);
+  }
+  if (result.issues === void 0) {
+    return { format, success: true, value: result.value };
+  }
+  return { format, success: false, error: formatSchemaIssues(result.issues) };
+}
+async function dispatch(format, stdout, checkId) {
   switch (format) {
     case "json":
       return parseJson(stdout);
@@ -483,7 +569,12 @@ async function buildEvidence(results, startedAt, completedAt) {
     results.map(async ([checkId, check, raw]) => {
       if (check.output === void 0) return [checkId, check, raw];
       try {
-        const output = await parseOutput(check.output.format, raw.stdout, checkId);
+        const output = await parseOutput(
+          check.output.format,
+          raw.stdout,
+          checkId,
+          check.output.schema
+        );
         return [checkId, check, { ...raw, output }];
       } catch (error) {
         thrown.push(error);
@@ -496,7 +587,10 @@ async function buildEvidence(results, startedAt, completedAt) {
     throw only;
   }
   if (thrown.length > 1) {
-    throw new AggregateError(thrown, `${String(thrown.length)} check output(s) failed to parse.`);
+    throw new AggregateError(
+      thrown,
+      `${String(thrown.length)} check output(s) failed during output processing.`
+    );
   }
   const evidence = {
     version: 1,
@@ -1096,6 +1190,7 @@ exports.PolicyReadFailedParseValueError = PolicyReadFailedParseValueError;
 exports.PolicyReadUnrequestedOutputError = PolicyReadUnrequestedOutputError;
 exports.PolicyThrewError = PolicyThrewError;
 exports.RepoContractError = RepoContractError;
+exports.StandardSchemaValidateThrewError = StandardSchemaValidateThrewError;
 exports.UnknownCheckIdError = UnknownCheckIdError;
 exports.defineRepoContract = defineRepoContract;
 exports.runRepoContract = runRepoContract;