repo-contract 0.1.0

package/src/config/validate-config.ts

@@ -0,0 +1,368 @@
+import {
+  DependencyDeclaredLaterError,
+  InvalidCheckConfigError,
+  InvalidRepoContractConfigError,
+} from "../errors.js"
+import type { OutputFormat, RepoContractConfig } from "../types.js"
+import { tokenizeRunString } from "./tokenize-command.js"
+
+const OUTPUT_FORMATS: readonly OutputFormat[] = ["json", "yaml", "text"]
+
+/**
+ * Validates a `RepoContractConfig` structurally and throws before any
+ * process spawns. A config with zero checks is valid (an empty `checks`
+ * object vacuously satisfies "every check passed"); everything else here is
+ * a genuine structural problem. Runtime checks are deliberately defensive
+ * about field types rather than trusting the compile-time type, since a
+ * config can arrive from plain JavaScript or a widened/cast value.
+ * @param config - the config to validate; throws if structurally invalid.
+ */
+export function validateRepoContractConfig(config: RepoContractConfig): void {
+  // Typed as `unknown` at this internal boundary (not the declared
+  // `RepoContractConfig` parameter type) deliberately -- this function's
+  // whole purpose is verifying something whose actual runtime shape isn't
+  // trusted (plain JavaScript callers, a widened or cast value), so
+  // narrowing from `unknown` keeps every check below genuinely meaningful
+  // rather than flagged as redundant against a type that's assumed valid.
+  const untrusted: unknown = config
+
+  if (untrusted === null || typeof untrusted !== "object") {
+    throw new InvalidRepoContractConfigError("config must be an object.")
+  }
+
+  const { checks, concurrency } = untrusted as Record<string, unknown>
+
+  if (checks === null || typeof checks !== "object" || Array.isArray(checks)) {
+    throw new InvalidRepoContractConfigError(
+      "checks must be an object mapping check id to check definition.",
+    )
+  }
+
+  if (concurrency !== undefined) {
+    // `typeof concurrency !== "number"` is behaviorally redundant with the
+    // clause after it: `Number.isInteger` returns `false` (never throws or
+    // coerces) for every non-number value, so `!Number.isInteger(...)`
+    // alone already rejects every case the typeof check would -- kept for
+    // readability at the call site, not because it changes behavior.
+    // Stryker disable next-line ConditionalExpression -- the typeof check is redundant with Number.isInteger, which returns false (never throws) for every non-number value, so it's kept only for readability at the call site.
+    if (typeof concurrency !== "number" || !Number.isInteger(concurrency) || concurrency < 1) {
+      throw new InvalidRepoContractConfigError(
+        "concurrency must be a positive integer when provided.",
+      )
+    }
+  }
+
+  for (const [checkId, check] of Object.entries(checks)) {
+    validateCheckDefinition(checkId, check)
+  }
+
+  validateDependencyGraph(checks as Record<string, { dependsOn?: readonly string[] }>)
+}
+
+/**
+ * Orchestrates one check's field-level validators. Deliberately just a flat
+ * sequence of calls with no branching of its own -- each field's validation
+ * logic (and its own complexity) lives in its own small function below, so
+ * this function's own cyclomatic complexity (and CRAP score) stays low
+ * regardless of how many fields exist to check.
+ * @param checkId - identifies which check is being validated, used in thrown error messages.
+ * @param check - the check definition to validate.
+ */
+function validateCheckDefinition(checkId: string, check: unknown): void {
+  // An integer-like key ("0", "42", ...) is enumerated by `Object.keys` in
+  // ascending numeric order ahead of every other key, regardless of insertion
+  // order -- so `validateDependencyGraph`'s `ids`/`indexById` (and the runtime
+  // scheduler) would see a different order than the source declares, silently
+  // breaking the "declaration order is the required topological order" contract.
+  if (/^(?:0|[1-9]\d*)$/.test(checkId)) {
+    throw new InvalidCheckConfigError(
+      checkId,
+      "check id must not be an integer-like string -- JavaScript would reorder it ahead of every " +
+        "other key and break the declaration-order-is-topological-order contract.",
+    )
+  }
+
+  if (check === null || typeof check !== "object") {
+    throw new InvalidCheckConfigError(checkId, "check definition must be an object.")
+  }
+
+  const fields = check as Record<string, unknown>
+  const usesShell = validateShell(checkId, fields.shell)
+  validateRun(checkId, fields.run, usesShell)
+  validateCwd(checkId, fields.cwd)
+  validateEnv(checkId, fields.env)
+  validateInheritEnv(checkId, fields.inheritEnv)
+  validateTimeoutMs(checkId, fields.timeoutMs)
+  validateOutput(checkId, fields.output)
+  validateDependsOn(checkId, fields.dependsOn)
+  validateIsolated(checkId, fields.isolated)
+  validatePolicy(checkId, fields.policy)
+}
+
+/**
+ * Returns whether `shell: true` was set, having already validated `shell`'s own type.
+ * @param checkId - identifies which check is being validated, used in thrown error messages.
+ * @param shell - the check's raw `shell` field to validate.
+ * @returns `true` if `shell` was set to `true`, `false` otherwise (including when omitted).
+ */
+function validateShell(checkId: string, shell: unknown): boolean {
+  if (shell !== undefined && typeof shell !== "boolean") {
+    throw new InvalidCheckConfigError(checkId, "shell must be a boolean when provided.")
+  }
+  return shell === true
+}
+
+/**
+ * Validates that `run` is a string or an array of strings, then delegates to the matching shape-specific validator.
+ * @param checkId - identifies which check is being validated, used in thrown error messages.
+ * @param run - the check's raw `run` field to validate.
+ * @param usesShell - whether `shell: true` was set, from `validateShell`.
+ */
+function validateRun(checkId: string, run: unknown, usesShell: boolean): void {
+  if (typeof run !== "string" && !Array.isArray(run)) {
+    throw new InvalidCheckConfigError(checkId, "run must be a string or an array of strings.")
+  }
+  if (typeof run === "string") {
+    validateStringRun(checkId, run, usesShell)
+  } else {
+    validateArrayRun(checkId, run as unknown[], usesShell)
+  }
+}
+
+/**
+ * Validates a string-form `run`: tokenizes it (for its side effect of rejecting unquoted shell operators) when no shell is used, or rejects an empty/whitespace-only string when a shell is used.
+ * @param checkId - identifies which check is being validated, used in thrown error messages.
+ * @param run - the check's raw `run` string to validate.
+ * @param usesShell - whether `shell: true` was set, from `validateShell`.
+ */
+function validateStringRun(checkId: string, run: string, usesShell: boolean): void {
+  if (!usesShell) {
+    // Tokenized here for its side effect (throws on an empty string or an
+    // unquoted shell operator); the result is recomputed at spawn time,
+    // since tokenization is cheap and pure. The first token is additionally
+    // checked for emptiness: `run: "''"` / `run: "'  ' build"` tokenizes to
+    // a non-empty array whose executable is `""`, which would otherwise fail
+    // only later as an opaque spawn error rather than a synchronous config
+    // error like every other structurally-broken `run`.
+    const [executable] = tokenizeRunString(run, checkId)
+    // `noUncheckedIndexedAccess` types the destructured `executable` as
+    // `string | undefined`, but `tokenizeRunString` throws on any input that
+    // would produce an empty token array (it rejects an empty or
+    // whitespace-only string outright), so `executable` is always a real
+    // string by the time control reaches here. The `?.` exists only to
+    // satisfy the compiler; removing it is behaviourally equivalent, so the
+    // OptionalChaining mutant here is an equivalent mutant with no test that
+    // could ever distinguish it.
+    // Stryker disable next-line OptionalChaining -- equivalent mutant: `executable` is provably always a string here (see comment above), so `executable?.trim()` and `executable.trim()` are identical.
+    if (executable?.trim().length === 0) {
+      throw new InvalidCheckConfigError(
+        checkId,
+        "run string's first token (the executable) is empty or contains only whitespace.",
+      )
+    }
+    return
+  }
+  if (run.trim().length === 0) {
+    throw new InvalidCheckConfigError(checkId, "run string is empty or contains only whitespace.")
+  }
+}
+
+/**
+ * Validates an array-form `run`: rejects it outright when a shell is used (array args can't express shell operators), and otherwise requires a non-empty array of strings.
+ * @param checkId - identifies which check is being validated, used in thrown error messages.
+ * @param items - the check's raw `run` array to validate.
+ * @param usesShell - whether `shell: true` was set, from `validateShell`.
+ */
+function validateArrayRun(checkId: string, items: readonly unknown[], usesShell: boolean): void {
+  if (usesShell) {
+    throw new InvalidCheckConfigError(
+      checkId,
+      "shell: true requires run to be a string -- an array of arguments is individually " +
+        "escaped for the shell and cannot express shell operators like pipes or redirects, " +
+        "so combining the two forms would silently do nothing useful.",
+    )
+  }
+  if (items.length === 0) {
+    throw new InvalidCheckConfigError(checkId, "run array must not be empty.")
+  }
+  if (items.some((item) => typeof item !== "string")) {
+    throw new InvalidCheckConfigError(checkId, "run array must contain only strings.")
+  }
+  // The first element is the executable; an empty or whitespace-only value
+  // there fails only later as an opaque spawn error, so reject it here like
+  // every other structurally-broken `run`.
+  if ((items[0] as string).trim().length === 0) {
+    throw new InvalidCheckConfigError(
+      checkId,
+      "run array's first element (the executable) is empty or contains only whitespace.",
+    )
+  }
+}
+
+/**
+ * Validates that `cwd`, if provided, is a string.
+ * @param checkId - identifies which check is being validated, used in thrown error messages.
+ * @param cwd - the check's raw `cwd` field to validate.
+ */
+function validateCwd(checkId: string, cwd: unknown): void {
+  if (cwd !== undefined && typeof cwd !== "string") {
+    throw new InvalidCheckConfigError(checkId, "cwd must be a string when provided.")
+  }
+}
+
+/**
+ * Validates that `env`, if provided, is an object mapping names to string values.
+ * @param checkId - identifies which check is being validated, used in thrown error messages.
+ * @param env - the check's raw `env` field to validate.
+ */
+function validateEnv(checkId: string, env: unknown): void {
+  if (env === undefined) return
+  if (env === null || typeof env !== "object" || Array.isArray(env)) {
+    throw new InvalidCheckConfigError(
+      checkId,
+      "env must be an object mapping name to value when provided.",
+    )
+  }
+  for (const [key, value] of Object.entries(env)) {
+    if (typeof value !== "string") {
+      throw new InvalidCheckConfigError(checkId, `env["${key}"] must be a string.`)
+    }
+  }
+}
+
+/**
+ * Validates that `inheritEnv`, if provided, is a boolean.
+ * @param checkId - identifies which check is being validated, used in thrown error messages.
+ * @param inheritEnv - the check's raw `inheritEnv` field to validate.
+ */
+function validateInheritEnv(checkId: string, inheritEnv: unknown): void {
+  if (inheritEnv !== undefined && typeof inheritEnv !== "boolean") {
+    throw new InvalidCheckConfigError(checkId, "inheritEnv must be a boolean when provided.")
+  }
+}
+
+/**
+ * Validates that `timeoutMs`, if provided, is a positive finite number.
+ * @param checkId - identifies which check is being validated, used in thrown error messages.
+ * @param timeoutMs - the check's raw `timeoutMs` field to validate.
+ */
+function validateTimeoutMs(checkId: string, timeoutMs: unknown): void {
+  if (timeoutMs === undefined) return
+  // Same redundancy as concurrency's typeof check above: `Number.isFinite`
+  // returns `false` (never throws or coerces) for every non-number value.
+  // Stryker disable next-line ConditionalExpression -- same redundancy as the concurrency check above: the typeof check is redundant with Number.isFinite, which returns false for every non-number value.
+  if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new InvalidCheckConfigError(checkId, "timeoutMs must be a positive number when provided.")
+  }
+}
+
+/**
+ * Validates that `output`, if provided, is an object whose `format` is one of the supported `OUTPUT_FORMATS`.
+ * @param checkId - identifies which check is being validated, used in thrown error messages.
+ * @param output - the check's raw `output` field to validate.
+ */
+function validateOutput(checkId: string, output: unknown): void {
+  if (output === undefined) return
+  if (output === null || typeof output !== "object") {
+    throw new InvalidCheckConfigError(checkId, "output must be an object when provided.")
+  }
+  const { format } = output as Record<string, unknown>
+  // `typeof format !== "string"` is behaviorally redundant with the clause
+  // after it: `Array#includes` uses strict equality, so a non-string
+  // `format` can never match an entry of `OUTPUT_FORMATS` (all strings),
+  // meaning `!OUTPUT_FORMATS.includes(...)` alone already rejects every
+  // case the typeof check would.
+  // Stryker disable next-line ConditionalExpression -- the typeof check is redundant with Array#includes' strict equality against OUTPUT_FORMATS (all strings), so a non-string format can never match regardless of the typeof check.
+  if (typeof format !== "string" || !OUTPUT_FORMATS.includes(format as OutputFormat)) {
+    throw new InvalidCheckConfigError(
+      checkId,
+      `output.format must be one of ${OUTPUT_FORMATS.map((f) => `"${f}"`).join(", ")}.`,
+    )
+  }
+}
+
+/**
+ * Validates that `policy` is a function.
+ * @param checkId - identifies which check is being validated, used in thrown error messages.
+ * @param policy - the check's raw `policy` field to validate.
+ */
+function validatePolicy(checkId: string, policy: unknown): void {
+  if (typeof policy !== "function") {
+    throw new InvalidCheckConfigError(checkId, "policy must be a function.")
+  }
+}
+
+/**
+ * Only this check's own shape (array of strings) and self-dependency --
+ * both need nothing beyond this one check's own id/field. Self-dependency
+ * is a degenerate one-node cycle, but is deliberately caught here rather
+ * than deferred to `validateDependencyGraph`'s cycle detector below: it
+ * needs no other check's data, gives a clearer message, and fails in this
+ * same per-check pass instead of waiting for a second one.
+ * @param checkId - identifies which check is being validated, used in thrown error messages and to detect self-dependency.
+ * @param dependsOn - the check's raw `dependsOn` field to validate.
+ */
+function validateDependsOn(checkId: string, dependsOn: unknown): void {
+  if (dependsOn === undefined) return
+  if (!Array.isArray(dependsOn) || dependsOn.some((id) => typeof id !== "string")) {
+    throw new InvalidCheckConfigError(
+      checkId,
+      "dependsOn must be an array of check ids (strings) when provided.",
+    )
+  }
+  if (dependsOn.includes(checkId)) {
+    throw new InvalidCheckConfigError(checkId, "dependsOn must not include the check's own id.")
+  }
+}
+
+/**
+ * Validates that `isolated`, if provided, is a boolean.
+ * @param checkId - identifies which check is being validated, used in thrown error messages.
+ * @param isolated - the check's raw `isolated` field to validate.
+ */
+function validateIsolated(checkId: string, isolated: unknown): void {
+  if (isolated !== undefined && typeof isolated !== "boolean") {
+    throw new InvalidCheckConfigError(checkId, "isolated must be a boolean when provided.")
+  }
+}
+
+/**
+ * Whole-graph properties that can't be checked per-check in isolation --
+ * run once, after every check's own `dependsOn` shape has already been
+ * validated by `validateDependsOn` above, so this can walk every
+ * `dependsOn` array without re-checking its shape.
+ *
+ * Declaration order in the `checks` object doubles as the required topological order (see
+ * `CheckDefinition.dependsOn`'s own doc comment): every `dependsOn` id must name a check declared
+ * earlier* than the check declaring it. This single backward-reference check subsumes what used
+ * to be two separate passes (an unknown-id check, then a DFS cycle detector) -- a cycle is no
+ * longer expressible at all once every edge is required to point backward, so there is nothing
+ * left for a separate cycle detector to catch. `isolated` needs no validation-time edge computation
+ * here: its own implied positional edges (see `run-checks.ts`'s `dependencyIndexesFor`) always
+ * point backward (to earlier-declared checks) or are pointed at by later-declared checks, by
+ * construction, so they can never introduce a cycle either.
+ * @param checks - the full check map, keyed by check id, in declaration order.
+ */
+export function validateDependencyGraph(
+  checks: Record<string, { dependsOn?: readonly string[] }>,
+): void {
+  const ids = Object.keys(checks)
+  const indexById = new Map(ids.map((id, index) => [id, index]))
+
+  for (const [index, id] of ids.entries()) {
+    const check = checks[id]
+    // `id` always comes from `Object.keys(checks)`, so `checks[id]` can
+    // never actually be undefined -- kept only because
+    // `noUncheckedIndexedAccess` can't itself express that invariant.
+    // Stryker disable next-line OptionalChaining -- id always comes from Object.keys(checks), so check can never be undefined here; the optional chaining exists only to satisfy noUncheckedIndexedAccess.
+    for (const depId of check?.dependsOn ?? []) {
+      const depIndex = indexById.get(depId)
+      if (depIndex === undefined) {
+        throw new InvalidCheckConfigError(id, `dependsOn references unknown check id "${depId}".`)
+      }
+      if (depIndex >= index) {
+        throw new DependencyDeclaredLaterError(id, depId)
+      }
+    }
+  }
+}

package/src/errors.ts

@@ -0,0 +1,229 @@
+/**
+ * Error hierarchy for repo-contract. Every concrete error carries a stable
+ * `code` string for programmatic handling, and never embeds raw
+ * stdout/stderr/env values in its message -- only check ids and field names
+ * (see SECURITY.md).
+ *
+ * Three distinct failure classes are kept deliberately separate (see
+ * specs/architecture.md):
+ *   - Structural config problems throw synchronously, before any process
+ *     spawns (`InvalidRepoContractConfigError`, `InvalidCheckConfigError`).
+ *   - Anything only discoverable by attempting execution becomes evidence,
+ *     never a throw (a bad `cwd`, a missing binary -- recorded as
+ *     `status: "spawn_error"` on that check's `CheckEvidence`).
+ *   - A policy function throwing or rejecting is a bug in consumer code, not
+ *     a check failing its contract -- it propagates as a rejected
+ *     `runRepoContract()` promise (`PolicyThrewError`), never silently
+ *     turned into a failed verdict entry.
+ */
+export abstract class RepoContractError extends Error {
+  /** Stable, machine-readable identifier for this error's specific failure mode. */
+  abstract readonly code: string
+}
+
+/** The top-level `RepoContractConfig` itself is structurally invalid -- e.g. `checks` is not an object, or `concurrency` is not a positive integer. (A `checks` object with zero entries is deliberately valid: the run produces an empty, passing `Verdict`.) Thrown synchronously by `runRepoContract`, before anything spawns -- not by `defineRepoContract`, which performs no runtime validation of its own (see its own doc comment). */
+export class InvalidRepoContractConfigError extends RepoContractError {
+  /** Always `"REPO_CONTRACT_INVALID_CONFIG"`. */
+  readonly code = "REPO_CONTRACT_INVALID_CONFIG"
+
+  constructor(reason: string) {
+    super(`Invalid repo-contract config -- ${reason}`)
+    this.name = "InvalidRepoContractConfigError"
+  }
+}
+
+/** One check's `CheckDefinition` is structurally invalid -- e.g. an empty `run`, a `run` string containing an unquoted shell operator without `shell: true`, or a missing `policy`. Thrown synchronously, before that check (or any other) spawns. */
+export class InvalidCheckConfigError extends RepoContractError {
+  /** Always `"REPO_CONTRACT_INVALID_CHECK_CONFIG"`. */
+  readonly code = "REPO_CONTRACT_INVALID_CHECK_CONFIG"
+  /** The id of the check whose configuration was invalid. */
+  readonly checkId: string
+
+  constructor(checkId: string, reason: string) {
+    super(`Invalid check config for "${checkId}" -- ${reason}`)
+    this.name = "InvalidCheckConfigError"
+    this.checkId = checkId
+  }
+}
+
+/**
+ * `RunRepoContractOptions.checks` (a partial-run request) names a check id that doesn't exist in
+ * the configured `checks`. Unlike a `dependsOn` id (already validated to exist by
+ * `validateRepoContractConfig` before any run starts), `options.checks` is only ever checked once
+ * `runChecks` actually resolves it -- there is no earlier structural-validation pass for it.
+ */
+export class UnknownCheckIdError extends RepoContractError {
+  /** Always `"REPO_CONTRACT_UNKNOWN_CHECK_ID"`. */
+  readonly code = "REPO_CONTRACT_UNKNOWN_CHECK_ID"
+  /** The unrecognized check id named in `options.checks`. */
+  readonly checkId: string
+
+  constructor(checkId: string) {
+    super(
+      `options.checks names "${checkId}", which is not a check id in this config's checks object.`,
+    )
+    this.name = "UnknownCheckIdError"
+    this.checkId = checkId
+  }
+}
+
+/**
+ * A check's `dependsOn` names a check declared *later* in the same `checks` object.
+ * `dependsOn` may only reference a check declared earlier -- see `CheckDefinition.dependsOn`'s own
+ * doc comment. Declaration order doubles as the required topological order, so this is the only
+ * way an invalid dependency graph can arise; a real cycle is structurally impossible once every
+ * edge points backward. Thrown synchronously, before any check spawns.
+ */
+export class DependencyDeclaredLaterError extends RepoContractError {
+  /** Always `"REPO_CONTRACT_DEPENDENCY_DECLARED_LATER"`. */
+  readonly code = "REPO_CONTRACT_DEPENDENCY_DECLARED_LATER"
+  /** The id of the check whose `dependsOn` names a later-declared check. */
+  readonly checkId: string
+  /** The later-declared check id named in `checkId`'s `dependsOn`. */
+  readonly dependencyId: string
+
+  constructor(checkId: string, dependencyId: string) {
+    super(
+      `Invalid check config for "${checkId}" -- dependsOn: ["${dependencyId}"], but "${dependencyId}" ` +
+        `is declared later in the checks object. dependsOn may only reference a check declared ` +
+        `earlier -- reorder the checks object so "${dependencyId}" is declared before "${checkId}".`,
+    )
+    this.name = "DependencyDeclaredLaterError"
+    this.checkId = checkId
+    this.dependencyId = dependencyId
+  }
+}
+
+/** A check requested `output: { format: "yaml" }` but the optional `yaml` peer dependency is not installed. Thrown when that check's output is parsed, not at config-validation time (parsing only happens after the process has already run). */
+export class ParserDependencyMissingError extends RepoContractError {
+  /** Always `"REPO_CONTRACT_PARSER_DEPENDENCY_MISSING"`. */
+  readonly code = "REPO_CONTRACT_PARSER_DEPENDENCY_MISSING"
+  /** The id of the check whose output could not be parsed. */
+  readonly checkId: string
+  /** The output format that was requested but whose optional peer dependency is missing. */
+  readonly format: OutputFormatForError
+
+  constructor(checkId: string, format: OutputFormatForError, cause: unknown) {
+    super(
+      `Check "${checkId}" requested output.format: "${format}", but the optional "${format}" ` +
+        `peer dependency is not installed -- run \`npm install ${format}\` to enable it.`,
+      { cause },
+    )
+    this.name = "ParserDependencyMissingError"
+    this.checkId = checkId
+    this.format = format
+  }
+}
+
+// Kept narrow and local rather than importing OutputFormat from types.ts --
+// only "yaml" can ever produce this error today (json/text have no external
+// dependency to be missing), but the field stays named/typed generically in
+// case a future optional format needs the same treatment.
+type OutputFormatForError = "yaml"
+
+/**
+ * A check's `policy` function threw synchronously, or returned a `Promise`
+ * that later rejected. Both failure modes are wrapped identically. The
+ * original thrown/rejected value is preserved verbatim via the native
+ * `Error` `cause` chain -- never stringified, summarized, or discarded --
+ * so a consumer catching this can still inspect exactly what their own
+ * policy code did wrong.
+ *
+ * A policy throwing never stops any other check's policy from running --
+ * every configured check's policy is invoked exactly once regardless of
+ * what any other policy does. If more than one policy fails this way in the
+ * same run, `runRepoContract()` rejects with a native `AggregateError` whose
+ * `errors` array holds one error per failing check -- `PolicyThrewError`,
+ * or one of its two narrower siblings below (`PolicyReadUnrequestedOutputError`,
+ * `PolicyReadFailedParseValueError`) when the failure matches one of their
+ * more specific shapes -- rather than surfacing only the first one found.
+ */
+export class PolicyThrewError extends RepoContractError {
+  /** Always `"REPO_CONTRACT_POLICY_THREW"`. */
+  readonly code = "REPO_CONTRACT_POLICY_THREW"
+  /** The id of the check whose policy threw or rejected. */
+  readonly checkId: string
+
+  constructor(checkId: string, cause: unknown) {
+    super(`Policy for check "${checkId}" threw instead of returning a PolicyResult`, { cause })
+    this.name = "PolicyThrewError"
+    this.checkId = checkId
+  }
+}
+
+/**
+ * A narrower `runPolicies` throws instead of `PolicyThrewError` when the
+ * thrown `TypeError`'s own message shows it came from reading a
+ * `result.output` property (`.success`, `.value`, `.error`, or `.format`),
+ * and this check's `CheckEvidence.output` really is `undefined` -- which
+ * happens only when its config never requested `output: { format: ... }` in
+ * the first place (see `CheckEvidence.output` in types.ts). Detected from
+ * the `TypeError`'s exact V8-produced message ("Cannot read properties of
+ * undefined (reading '...')") cross-checked against that `undefined` fact,
+ * so it is thrown only for a policy that plausibly hit this exact mistake --
+ * any other `TypeError`, or a check that did request a format, still becomes
+ * a plain `PolicyThrewError`. This is best-effort inference from the
+ * `TypeError`'s message text, not a verified trace back to `result.output`
+ * itself -- V8's message carries only the property name, so an unrelated
+ * bug that happens to read the same property name off some other
+ * `undefined` value can still be misclassified this way (see
+ * `unrequestedOutputProperty` in run-policies.ts). `cause` still holds the
+ * original `TypeError` verbatim, exactly as `PolicyThrewError` guarantees
+ * for every other policy failure, so the true cause remains recoverable
+ * either way.
+ */
+export class PolicyReadUnrequestedOutputError extends RepoContractError {
+  /** Always `"REPO_CONTRACT_POLICY_READ_UNREQUESTED_OUTPUT"`. */
+  readonly code = "REPO_CONTRACT_POLICY_READ_UNREQUESTED_OUTPUT"
+  /** The id of the check whose policy read `result.output` without requesting a format. */
+  readonly checkId: string
+
+  constructor(checkId: string, property: string, cause: unknown) {
+    super(
+      `Policy for check "${checkId}" read \`result.output.${property}\`, but "${checkId}" never ` +
+        `requested an output format, so \`result.output\` is undefined -- add ` +
+        `\`output: { format: "json" }\` (or "yaml"/"text") to check "${checkId}"'s definition to ` +
+        `parse its stdout, then narrow with \`result.output?.success\` before reading ` +
+        `\`.value\`/\`.error\`.`,
+      { cause },
+    )
+    this.name = "PolicyReadUnrequestedOutputError"
+    this.checkId = checkId
+  }
+}
+
+/**
+ * `PolicyThrewError`'s other special case, alongside
+ * `PolicyReadUnrequestedOutputError`: this check *did* request
+ * `output: { format: ... }`, but that parse itself failed
+ * (`result.output.success === false` -- see `ParsedOutputFailure` in types.ts, which
+ * has no `value` field, only `error`), and the policy read a property off
+ * `result.output.value` anyway without checking `.success` first. Detected the same
+ * way `runPolicies` detects the sibling case -- a thrown `TypeError` whose own
+ * message shows a property read off `undefined` -- cross-checked against this
+ * check's own evidence having `output.success === false`, so a genuinely unrelated
+ * `TypeError`, or a check whose parse actually succeeded, still becomes a plain
+ * `PolicyThrewError`. Unlike `PolicyReadUnrequestedOutputError`, the read property
+ * isn't restricted to a known list here -- `result.output.value`'s shape is whatever
+ * the external tool printed, entirely unknown to repo-contract -- so this match is
+ * necessarily a little broader. `cause` still holds the original `TypeError`
+ * verbatim; the message never repeats `result.output.error`'s own text, which may
+ * contain raw stdout content (see SECURITY.md).
+ */
+export class PolicyReadFailedParseValueError extends RepoContractError {
+  /** Always `"REPO_CONTRACT_POLICY_READ_FAILED_PARSE_VALUE"`. */
+  readonly code = "REPO_CONTRACT_POLICY_READ_FAILED_PARSE_VALUE"
+  /** The id of the check whose policy read `result.output.value` after a failed parse. */
+  readonly checkId: string
+
+  constructor(checkId: string, property: string, cause: unknown) {
+    super(
+      `Policy for check "${checkId}" read \`result.output.value.${property}\`, but "${checkId}"'s ` +
+        `output failed to parse -- a failed parse has \`result.output.error\`, never \`.value\` -- ` +
+        `check \`result.output.success\` before reading \`.value\`.`,
+      { cause },
+    )
+    this.name = "PolicyReadFailedParseValueError"
+    this.checkId = checkId
+  }
+}