repo-contract 0.1.0

package/schemas/evidence.schema.json

@@ -0,0 +1,253 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://maverickcer.github.io/repo-contract/schema/evidence.schema.json",
+  "title": "repo-contract Evidence",
+  "description": "Machine-readable record of what happened when a repo-contract configuration was executed -- one entry per configured check, describing the command run, its exit status, captured output, and (if requested) parsed output. Says nothing about whether the result was acceptable -- see the paired Verdict schema for that. Generated from src/types.ts's Evidence type -- never hand-authored.",
+  "$ref": "#/definitions/EvidenceSchemaSource",
+  "definitions": {
+    "EvidenceSchemaSource": {
+      "$ref": "#/definitions/Evidence"
+    },
+    "Evidence": {
+      "type": "object",
+      "properties": {
+        "version": {
+          "type": "number",
+          "const": 1,
+          "description": "Schema version of this shape; see VERSIONING.md."
+        },
+        "startedAt": {
+          "type": "string",
+          "description": "ISO 8601 timestamp of when the run began."
+        },
+        "completedAt": {
+          "type": "string",
+          "description": "ISO 8601 timestamp of when the last check finished."
+        },
+        "durationMs": {
+          "type": "number",
+          "description": "Wall-clock time for the run as a whole, in milliseconds."
+        },
+        "checks": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/CheckEvidence"
+          },
+          "description": "Each configured check's own evidence, keyed by check id."
+        }
+      },
+      "required": [
+        "version",
+        "startedAt",
+        "completedAt",
+        "durationMs",
+        "checks"
+      ],
+      "description": "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)."
+    },
+    "CheckEvidence": {
+      "type": "object",
+      "properties": {
+        "command": {
+          "type": "string",
+          "description": "The executable that was actually spawned (after tokenization, if `run` was a string)."
+        },
+        "args": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The arguments passed to `command`, exactly as spawned."
+        },
+        "startedAt": {
+          "type": "string",
+          "description": "ISO 8601 timestamp of when the process was spawned."
+        },
+        "completedAt": {
+          "type": "string",
+          "description": "ISO 8601 timestamp of when the process reached its terminal state."
+        },
+        "durationMs": {
+          "type": "number",
+          "description": "Wall-clock time from spawn to termination, in milliseconds."
+        },
+        "exitCode": {
+          "type": [
+            "number",
+            "null"
+          ],
+          "description": "`null` when the process never exited normally -- see `signal` and `status`."
+        },
+        "signal": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/global.NodeJS.Signals"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "The signal that terminated the process, if any. `null` for a normal exit or a spawn failure."
+        },
+        "stdout": {
+          "type": "string",
+          "description": "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."
+        },
+        "stderr": {
+          "type": "string",
+          "description": "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."
+        },
+        "status": {
+          "$ref": "#/definitions/CheckStatus",
+          "description": "Why the process reached its terminal state; see `CheckStatus`."
+        },
+        "spawnError": {
+          "type": "string",
+          "description": "Populated only for `status === \"spawn_error\"` -- the underlying Node error message (e.g. \"spawn foo ENOENT\"). Never populated for any other status."
+        },
+        "spawnErrorCode": {
+          "type": "string",
+          "description": "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."
+        },
+        "output": {
+          "$ref": "#/definitions/ParsedOutput%3Cunknown%3E",
+          "description": "The parsed interpretation of `stdout`, present only if this check's config requested a `format`."
+        }
+      },
+      "required": [
+        "command",
+        "args",
+        "startedAt",
+        "completedAt",
+        "durationMs",
+        "exitCode",
+        "signal",
+        "stdout",
+        "stderr",
+        "status"
+      ],
+      "description": "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`.\n\n`output.value` is typed `unknown` for every format, including `\"text\"` (even though `parseText` always produces a `string` at runtime) -- neither repo-contract nor TypeScript's generic inference can reliably carry a specific check's own literal `output.format` 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). A policy author narrows or casts `.value` themselves, exactly as they already must for `\"json\"`/`\"yaml\"` where no schema knowledge exists either way."
+    },
+    "global.NodeJS.Signals": {
+      "type": "string",
+      "enum": [
+        "SIGABRT",
+        "SIGALRM",
+        "SIGBUS",
+        "SIGCHLD",
+        "SIGCONT",
+        "SIGFPE",
+        "SIGHUP",
+        "SIGILL",
+        "SIGINT",
+        "SIGIO",
+        "SIGIOT",
+        "SIGKILL",
+        "SIGPIPE",
+        "SIGPOLL",
+        "SIGPROF",
+        "SIGPWR",
+        "SIGQUIT",
+        "SIGSEGV",
+        "SIGSTKFLT",
+        "SIGSTOP",
+        "SIGSYS",
+        "SIGTERM",
+        "SIGTRAP",
+        "SIGTSTP",
+        "SIGTTIN",
+        "SIGTTOU",
+        "SIGUNUSED",
+        "SIGURG",
+        "SIGUSR1",
+        "SIGUSR2",
+        "SIGVTALRM",
+        "SIGWINCH",
+        "SIGXCPU",
+        "SIGXFSZ",
+        "SIGBREAK",
+        "SIGLOST",
+        "SIGINFO"
+      ]
+    },
+    "CheckStatus": {
+      "type": "string",
+      "enum": [
+        "completed",
+        "timed_out",
+        "signaled",
+        "host_terminated",
+        "spawn_error",
+        "aborted"
+      ],
+      "description": "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.\n\n`\"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\"`."
+    },
+    "ParsedOutput<unknown>": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/ParsedOutputSuccess%3Cunknown%3E"
+        },
+        {
+          "$ref": "#/definitions/ParsedOutputFailure"
+        }
+      ],
+      "description": "The result of a check's requested output-format parse: either a successful `ParsedOutputSuccess`, or a `ParsedOutputFailure`."
+    },
+    "ParsedOutputSuccess<unknown>": {
+      "type": "object",
+      "properties": {
+        "format": {
+          "$ref": "#/definitions/OutputFormat",
+          "description": "The format that was requested and successfully parsed."
+        },
+        "success": {
+          "type": "boolean",
+          "const": true,
+          "description": "Always `true`."
+        },
+        "value": {
+          "description": "The parsed value."
+        }
+      },
+      "required": [
+        "format",
+        "success",
+        "value"
+      ],
+      "description": "A requested parse of a check's stdout succeeded."
+    },
+    "OutputFormat": {
+      "type": "string",
+      "enum": [
+        "json",
+        "yaml",
+        "text"
+      ],
+      "description": "Output interpretation a check can explicitly request. No format requested means no parsing -- the consumer gets raw stdout/stderr only."
+    },
+    "ParsedOutputFailure": {
+      "type": "object",
+      "properties": {
+        "format": {
+          "$ref": "#/definitions/OutputFormat",
+          "description": "The format that was requested (and failed to parse)."
+        },
+        "success": {
+          "type": "boolean",
+          "const": false,
+          "description": "Always `false`."
+        },
+        "error": {
+          "type": "string",
+          "description": "The parse error's message."
+        }
+      },
+      "required": [
+        "format",
+        "success",
+        "error"
+      ],
+      "description": "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."
+    }
+  }
+}

package/schemas/verdict.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://maverickcer.github.io/repo-contract/schema/verdict.schema.json",
+  "title": "repo-contract Verdict",
+  "description": "Machine-readable aggregate pass/fail result produced by evaluating repository-owned policies against an Evidence object -- one entry per configured check, each individually inspectable. Generated from src/types.ts's Verdict type -- never hand-authored.",
+  "$ref": "#/definitions/VerdictSchemaSource",
+  "definitions": {
+    "VerdictSchemaSource": {
+      "$ref": "#/definitions/Verdict"
+    },
+    "Verdict": {
+      "type": "object",
+      "properties": {
+        "version": {
+          "type": "number",
+          "const": 2,
+          "description": "Schema version of this shape; see VERSIONING.md."
+        },
+        "passed": {
+          "type": "boolean",
+          "description": "`true` only if every check's `outcome` is `\"pass\"` or `\"warn\"`."
+        },
+        "checks": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/PolicyResult"
+          },
+          "description": "Each configured check's own `PolicyResult`, verbatim, keyed by check id."
+        }
+      },
+      "required": [
+        "version",
+        "passed",
+        "checks"
+      ],
+      "description": "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."
+    },
+    "PolicyResult": {
+      "type": "object",
+      "properties": {
+        "outcome": {
+          "$ref": "#/definitions/PolicyOutcome",
+          "description": "The policy's pass/fail/warn decision."
+        },
+        "rationale": {
+          "type": "string",
+          "description": "Why the policy reached `outcome`, in enough detail to act on without rerunning anything."
+        }
+      },
+      "required": [
+        "outcome",
+        "rationale"
+      ],
+      "description": "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.\n\n`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."
+    },
+    "PolicyOutcome": {
+      "type": "string",
+      "enum": [
+        "pass",
+        "fail",
+        "warn"
+      ],
+      "description": "`\"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`)."
+    }
+  }
+}

package/src/config/define-repo-contract.ts

@@ -0,0 +1,38 @@
+import type { CheckSchema, RepoContractConfig, ValidatedCheckSchema } from "../types.js"
+
+/**
+ * Identity function whose only job is type inference: authoring a config
+ * through `defineRepoContract` lets each check's `output` (present or
+ * absent, and which format) flow into that same check's `policy` parameter
+ * type, without the consumer writing any type annotations themselves. It
+ * also statically validates every check's `dependsOn` against its sibling
+ * check ids (see `ValidatedCheckSchema`) -- a typo'd or self-referencing id
+ * fails to compile here rather than only failing at runtime. Performs no
+ * other validation and no cloning -- `runRepoContract` validates whatever
+ * config it is ultimately given, whether or not it passed through this
+ * function first.
+ *
+ * `const TChecks` (TypeScript 5.0's `const` type parameter modifier) keeps
+ * each check's own configuration -- notably whether `output` is present at
+ * all -- from being widened during inference; without it, TypeScript's
+ * inference for a `Record` of heterogeneous generic entries does not
+ * reliably preserve that per-check shape once a callback property
+ * (`policy`) is also present. See `InferParsedValue` in types.ts for the
+ * related limitation this does not fully solve.
+ *
+ * `TChecks` is inferred from the plain, unwrapped `RepoContractConfig<TChecks>`
+ * position -- the `ValidatedCheckSchema<TChecks>` constraint on `checks` is
+ * intersected in afterward, computed from that already-inferred `TChecks`,
+ * rather than substituted in its place. Inferring `TChecks` directly from a
+ * mapped/conditional type over itself (as `ValidatedCheckSchema` is) loses
+ * the contextual typing every check's `policy` callback otherwise gets --
+ * another real, confirmed TypeScript inference limitation, distinct from
+ * the `output`-to-`policy` one above.
+ * @param config - the config to type-check and return unchanged.
+ * @returns the same `config` object, untouched and uncloned.
+ */
+export function defineRepoContract<const TChecks extends CheckSchema>(
+  config: RepoContractConfig<TChecks> & { readonly checks: ValidatedCheckSchema<TChecks> },
+): RepoContractConfig<TChecks> {
+  return config
+}

package/src/config/tokenize-command.ts

@@ -0,0 +1,214 @@
+import { InvalidCheckConfigError } from "../errors.js"
+
+/**
+ * Consumes a `\`-escape sequence starting at `run[i]`, if one applies here. A backslash escapes the
+ * next character (and is itself dropped) when unquoted or inside a double-quoted span; inside
+ * single quotes it is a literal character, exactly as in every POSIX shell -- so a Windows path in
+ * single quotes survives intact. A trailing backslash with nothing left to escape is not an escape
+ * and is kept literally by the caller.
+ * @param run - the full command string being tokenized.
+ * @param i - the index of the candidate backslash.
+ * @param quote - the current quote context (`"'"`, `'"'`, or `null` for unquoted).
+ * @returns the escaped character and the index just past the two-character sequence, or `undefined` when no escape applies at `i`.
+ */
+function consumeEscape(
+  run: string,
+  i: number,
+  quote: "'" | '"' | null,
+): { readonly value: string; readonly next: number } | undefined {
+  if (run[i] !== "\\" || quote === "'") return undefined
+  // No explicit `i + 1 < run.length` pre-check: a trailing backslash at
+  // end-of-string reads `run[i + 1]` as `undefined` (which `noUncheckedIndexedAccess`
+  // already types), and the `escaped === undefined` guard below returns
+  // `undefined` for exactly that case -- so the caller keeps the backslash
+  // literal. One guard, one behavior, nothing to mutation-suppress.
+  const escaped: string | undefined = run[i + 1]
+  if (escaped === undefined) return undefined
+  return { value: escaped, next: i + 2 }
+}
+
+// Single-character shell/multi-command operators rejected outright when they
+// appear unquoted. A literal newline (`\n`/`\r`) and the two-character `$(`
+// are handled separately in `rejectUnquotedOperator` -- every entry here is
+// exactly one character, matched by a single Set lookup rather than a chain
+// of per-character `if`s.
+const UNQUOTED_SHELL_OPERATORS: ReadonlySet<string> = new Set([";", "&", "|", "`", "<", ">"])
+
+/**
+ * Throws `InvalidCheckConfigError` when the unquoted character `char` at `run[i]` is a
+ * shell/multi-command operator repo-contract never interprets (`;`, `&`, `|`, a backtick, `<`, `>`,
+ * `$(`, or a literal newline). Returns normally when `char` is legitimate literal argv content --
+ * glob characters and a bare `$` deliberately included (see `tokenizeRunString`'s doc comment).
+ * @param char - the character under the cursor, already known defined by the caller.
+ * @param run - the full command string, needed only to look one character ahead for `$(`.
+ * @param i - the index of `char` within `run`.
+ * @param checkId - identifies which check's `run` was invalid, used in the thrown error message.
+ */
+function rejectUnquotedOperator(char: string, run: string, i: number, checkId: string): void {
+  const reject = (operator: string): never => {
+    throw new InvalidCheckConfigError(
+      checkId,
+      `run string contains an unquoted "${operator}" -- repo-contract never invokes a shell for ` +
+        `string-form "run", so shell operators are not interpreted. Use "run: [...]" (array ` +
+        `form) to pass "${operator}" as a literal argument, or set "shell: true" to opt into ` +
+        `real shell execution.`,
+    )
+  }
+
+  if (char === "\n" || char === "\r") reject("newline")
+  if (UNQUOTED_SHELL_OPERATORS.has(char)) reject(char)
+  if (char === "$" && run[i + 1] === "(") reject("$(")
+}
+
+/**
+ * Splits a `run` string into argv (executable + arguments) without invoking
+ * a shell -- no shell operator is ever executed, no glob is ever expanded by
+ * this package, no environment variable is ever substituted. The result is
+ * deterministic: the same input string always produces the same argv array.
+ *
+ * Quoting: `'...'` and `"..."` group whitespace into a single argument and
+ * are themselves stripped from the resulting token. `\` escapes the next
+ * character (and is itself stripped) when unquoted or inside a double-quoted
+ * span; inside single quotes it is a literal character, exactly as in every
+ * POSIX shell -- so a Windows path in single quotes survives intact.
+ * Unquoted whitespace (space, tab) separates tokens.
+ *
+ * Rejected outright (throws `InvalidCheckConfigError`, checkId identifies
+ * which check's `run` was invalid): any *unquoted* occurrence of a true
+ * shell/multi-command operator -- `;`, `&`, `|`, a backtick, `$(`, `<`, `>`,
+ * or a literal newline. A string containing one of these almost always
+ * reflects a mistaken assumption that shell interpretation is happening;
+ * the fix is either `run: [...]` (array form, bypasses tokenization
+ * entirely) or explicit `shell: true`.
+ *
+ * Deliberately NOT rejected: glob characters (`*`, `?`, `~`, `[`, `]`, `{`,
+ * `}`) and a bare `$`. These are common, legitimate literal argv content --
+ * many CLI tools (eslint, prettier, tsc) accept and internally expand glob
+ * patterns themselves, e.g. `eslint "src/**\/*.ts"` -- and since no shell is
+ * ever invoked here, they carry zero shell-injection risk regardless of
+ * where they appear in the string.
+ * @param run - the command string to tokenize.
+ * @param checkId - identifies which check's `run` was invalid, used in the thrown error message.
+ * @returns the tokenized argv (executable followed by its arguments).
+ */
+export function tokenizeRunString(run: string, checkId: string): readonly string[] {
+  const tokens: string[] = []
+  let current = ""
+  let hasCurrent = false
+  let quote: "'" | '"' | null = null
+  let i = 0
+
+  // Loosening the `i < run.length` bound to `i <= run.length` is
+  // behaviorally invisible: the one extra iteration it would permit reads
+  // `run[run.length]`, which is `undefined`, and is caught immediately below
+  // by the (itself unmutatable, for the same `noUncheckedIndexedAccess`
+  // reason) `char === undefined` check -- confirmed equivalent by exhaustive
+  // differential testing against a wide corpus of inputs, not assumed.
+  //
+  // `iterations` is a second, independent forward-progress bound: every loop
+  // pass that doesn't throw/break advances `i` by exactly 1 or 2, so no
+  // correct execution ever needs more than `run.length` passes -- a
+  // regression that makes `i` stand still or move backward (a `+=`
+  // accidentally becoming `-=`), or that wipes the loop body entirely,
+  // would otherwise hang forever instead of failing loudly. It is
+  // deliberately tracked in the `for` statement's own update/condition
+  // clauses rather than inside the loop body: those clauses sit outside the
+  // body's own `{ ... }` block, so they keep running (and keep bounding the
+  // loop) even under a mutation that replaces the entire body with `{}`,
+  // which a bound placed inside the body could not survive.
+  //
+  // Every mutation of this line's own clauses (loosening either half of the
+  // `&&`, swapping it for `||`, or reversing `iterations`' own direction) is
+  // itself equivalent as long as the *body* still advances `i` correctly:
+  // `i < run.length` alone already terminates the loop at the right point
+  // for correct code, with the `iterations` bound only ever mattering in
+  // combination with a genuine body regression -- confirmed empirically:
+  // mutating this line in isolation (leaving the body untouched) produces no
+  // observable difference. It exists precisely to convert the *body*
+  // mutations described above from an unkillable hang into a fast, visible
+  // test failure, not to be independently killable itself.
+  // Stryker disable next-line ConditionalExpression,EqualityOperator,LogicalOperator,AssignmentOperator,BlockStatement -- loosening i < run.length to i <= run.length is behaviorally invisible since the unmutatable char === undefined check right after already catches it, and the iterations bound is a second, independent forward-progress bound tracked in this line's own clauses (outside the body's braces) specifically so a body-emptying mutation can't produce an unkillable hang; every mutation of this line's own clauses is equivalent as long as the body still advances i correctly, confirmed empirically.
+  for (let iterations = 0; i < run.length && iterations <= run.length; iterations += 1) {
+    const char = run[i]
+    // Unreachable given the loop condition (`i < run.length` already
+    // guarantees `run[i]` is defined) -- kept only because
+    // `noUncheckedIndexedAccess` can't itself express that invariant.
+    // Stryker disable next-line ConditionalExpression -- unreachable given the loop's own i < run.length guard already ensures run[i] is defined; kept only because noUncheckedIndexedAccess can't itself express that invariant.
+    if (char === undefined) break
+
+    if (quote !== null) {
+      const escape = consumeEscape(run, i, quote)
+      if (escape !== undefined) {
+        current += escape.value
+        i = escape.next
+        continue
+      }
+      if (char === quote) {
+        quote = null
+        i += 1
+        continue
+      }
+      current += char
+      i += 1
+      continue
+    }
+
+    if (char === "'" || char === '"') {
+      quote = char
+      hasCurrent = true
+      i += 1
+      continue
+    }
+
+    // An unquoted backslash before a newline is a shell line-continuation.
+    // repo-contract never interprets one -- and it must be rejected *here*,
+    // before `consumeEscape` below, because `consumeEscape` would otherwise
+    // treat `\<newline>` as an ordinary escape: splice a literal newline into
+    // the token and advance the cursor past the newline, so the bare-newline
+    // rejection further down never runs.
+    const nextChar = run[i + 1]
+    if (char === "\\" && (nextChar === "\n" || nextChar === "\r")) {
+      throw new InvalidCheckConfigError(
+        checkId,
+        `run string contains an unquoted line continuation (a backslash before a newline) -- ` +
+          `repo-contract never invokes a shell for string-form "run". Use "run: [...]" (array ` +
+          `form), or set "shell: true" to opt into real shell execution.`,
+      )
+    }
+
+    const escape = consumeEscape(run, i, null)
+    if (escape !== undefined) {
+      current += escape.value
+      hasCurrent = true
+      i = escape.next
+      continue
+    }
+
+    if (char === " " || char === "\t") {
+      if (hasCurrent) {
+        tokens.push(current)
+        current = ""
+        hasCurrent = false
+      }
+      i += 1
+      continue
+    }
+
+    rejectUnquotedOperator(char, run, i, checkId)
+
+    current += char
+    hasCurrent = true
+    i += 1
+  }
+
+  if (quote !== null) {
+    throw new InvalidCheckConfigError(checkId, `run string has an unterminated ${quote} quote.`)
+  }
+  if (hasCurrent) tokens.push(current)
+
+  if (tokens.length === 0) {
+    throw new InvalidCheckConfigError(checkId, "run string is empty or contains only whitespace.")
+  }
+
+  return tokens
+}