@avi2dg/checks 0.2.0 → 0.4.0

package/README.md

@@ -5,8 +5,9 @@ Deterministic checks shared across my TypeScript repos. One package,
 Effect language-service block, the shared commitlint config, the shared
 dependency-cruiser base, the test-layout check with its bunfig preset,
 the commit-identity check with its workflow, the comment gate with its
-workflow and backtest, and the Effect error-channel plugin compiled to
-JavaScript.
+workflow and backtest, the Stryker mutation-testing preset with its
+no-regression comparator, the CI-wiring check, and the Effect
+error-channel plugin compiled to JavaScript.
 
 Published as `@avi2dg/checks` on the public npm registry.
 
@@ -64,6 +65,18 @@ cp node_modules/@avi2dg/checks/bunfig.toml bunfig.toml
 `commit-identity.ts` refuses a commit with an author other than the
 repository owner; see "Commit identity" below.
 
+A repo that runs mutation testing installs `@stryker-mutator/core` and
+`@hughescr/stryker-bun-runner`, then spreads the shipped preset in
+`stryker.conf.mjs`:
+
+```js
+import preset from "@avi2dg/checks/stryker.preset.js";
+
+export default {
+  ...preset,
+};
+```
+
 The registry version is pinned by the consumer's lockfile; bump
 `@avi2dg/checks` to adopt a new release.
 
@@ -92,7 +105,10 @@ file and the path to move it to when it does not:
 - `scripts.test` is exactly `bun test --randomize` and `scripts.lint` runs
   this check.
 - `bunfig.toml` carries every `[test]` key of the shipped preset with the
-  same value. Other tables, and extra `[test]` keys, are the repo's own.
+  same value, and `[test].pathIgnorePatterns` is always
+  `["**/tests/quarantine/**"]`: the check pins it itself, so this repo,
+  whose bunfig is the preset, cannot drift it either. Other tables, and
+  extra `[test]` keys, are the repo's own.
 
 The in-process half is what a mutation run can mutate; `tests/e2e/**` is
 excluded from a mutate scope by construction, because a subprocess kills
@@ -170,7 +186,15 @@ on:
     types: [opened, edited, synchronize, reopened]
 jobs:
   commitlint:
-    uses: avi2d/checks/.github/workflows/commitlint.yml@main
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: printf '%s' "$PR_TITLE (#0000)" > "$RUNNER_TEMP/pr-title"
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+      - run: ./node_modules/.bin/commitlint --config ./node_modules/@avi2dg/checks/commitlint.config.js --edit "$RUNNER_TEMP/pr-title"
 ```
 
 It lints the pull request title and nothing else. The title is the
@@ -221,10 +245,20 @@ on:
     types: [opened, edited, synchronize, reopened]
 jobs:
   commit-identity:
-    uses: avi2d/checks/.github/workflows/commit-identity.yml@main
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bunx checks-commit-identity "origin/$BASE_REF" "$HEAD_SHA"
+        env:
+          BASE_REF: ${{ github.event.pull_request.base.ref }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
 ```
 
-The workflow fetches the consumer's full history and ranges from the
+The checkout fetches the full history and the range starts at the
 fetched base branch, not the event's recorded base sha, which GitHub
 leaves stale once the base branch advances after the pull request opens.
 
@@ -258,9 +292,100 @@ on:
     types: [opened, edited, synchronize, reopened]
 jobs:
   comment-gate:
-    uses: avi2d/checks/.github/workflows/comment-gate.yml@main
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bunx checks-comment-gate "origin/$BASE_REF" "$HEAD_SHA"
+        env:
+          BASE_REF: ${{ github.event.pull_request.base.ref }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+```
+
+## CI wiring
+
+`checks-ci-wiring` fails when a command the repository's CI must run no
+longer runs on pull requests to the default branch. No local check sees
+that: a workflow whose lint step became a no-op leaves `bun run lint`
+green.
+
+The repository declares its gates once, in `package.json`, and `lint`
+runs the check:
+
+```json
+"ciWiring": {
+  "gates": ["bun run lint", "bun run typecheck", "bun run test"]
+},
+"scripts": {
+  "lint": "oxlint --type-aware && checks-lint-coverage && checks-test-layout && checks-ci-wiring"
+}
 ```
 
+It parses every `.github/workflows/*.yml` and `*.yaml` and looks, for
+each gate, for a `run:` step that is the gate command alone on one line,
+optionally followed by plain arguments: words, quoted strings, and
+`$VAR` or `${VAR}` expansions. `bun run lint --quiet` and
+`bunx checks-comment-gate "origin/$BASE_REF" "$HEAD_SHA"` count;
+`bun run lint:deps`, `echo bun run lint` and a step `name:` do not. A
+step whose script has a second line, or any `|`, `||`, `&&`, `;`, `&`,
+`$(...)`, backticks, `<` or `>` redirection, a comment or a leading
+`NAME=value`, never counts, because each can run the gate without its
+failure failing the step; the report names the gate and says to give it
+its own step with nothing else in it. A gate step counts only when:
+
+- its workflow triggers on `pull_request`, any `branches` or
+  `branches-ignore` filter there keeps the default branch, any `types`
+  filter keeps `opened` and `synchronize`, and it sets no `paths` or
+  `paths-ignore` filter, which lets some pull requests skip the gate;
+- neither the step nor its job sets `if: false` or
+  `continue-on-error: true`, bare or as `${{ false }}` and `${{ true }}`;
+- its job needs no job, directly or through a chain, that sets
+  `if: false`, unless a job on that chain has an `if:` calling
+  `always()`, `failure()` or `cancelled()`. GitHub prefixes every other
+  `if:`, including `true` and `success()`, with `success()`, so a job
+  whose needed job was skipped is skipped too.
+
+A job calling a local reusable workflow (`uses: ./.github/workflows/x.yml`)
+passes its own trigger and `if:` down to the called workflow's steps.
+A remote reusable workflow (`uses: owner/repo/...@ref`) is not a
+supported way to wire a gate: it is not read, so a gate must run as a
+`run:` step, such as `bunx checks-comment-gate`, in the repo's own
+workflows.
+
+The default branch is `main`; a repo with another one sets
+`"defaultBranch"` beside `"gates"`.
+
+It exits 1 naming each gap, with every step that runs the gate and why
+that step does not count:
+
+```
+ci-wiring: 1 of 8 gate(s) do not run on pull requests to main:
+  bun run lint
+    .github/workflows/release.yml job publish step 7: .github/workflows/release.yml does not trigger on pull_request
+```
+
+It exits 2 when `package.json` declares no gates, a gate is not one
+plain command, or a workflow does not parse. Whether a workflow is
+well formed is actionlint's question, not this one's.
+
+### Limits
+
+The check reads workflow files and never runs them, so it deliberately
+does not evaluate:
+
+- an `if:` expression other than a constant `true` or `false`, which
+  counts as running;
+- a `strategy.matrix` `include` or `exclude`, so a matrix that drops
+  every combination still counts as running its steps;
+- a remote reusable workflow (`uses: owner/repo/...@ref`), whose steps
+  are never read;
+- anything that happens at run time on the runner: what the gate
+  command itself does, the shell's options, and a step or job that
+  fails or times out before the gate step.
+
 ## Backtest
 
 `scripts/backtest.ts` reports what the comment check would have refused
@@ -277,6 +402,52 @@ comment text as a share of added lines.
 `generated/`, `vendor/`, `repos/`, `node_modules/` and `dist/` are out
 of reach, so the figures are authored code.
 
+## Mutation compare
+
+`checks-mutation-compare` gates a pull request on no-regression rather
+than an absolute threshold: the head mutation score may not fall below
+the score at the merge-base.
+
+```sh
+checks-mutation-compare <base-report> <head-report> [--advisory]
+```
+
+Both reports are Stryker `mutation.json` files. It prints the overall
+score of each report and the per-file scores that differ, and exits 1
+when the head score is below the base score. The score is Stryker's:
+`Killed` and `Timeout` over those plus `Survived` and `NoCoverage`, so
+`CompileError`, `RuntimeError`, `Ignored` and `Pending` mutants leave
+it. Every file in a report counts toward that report's score, including
+files present in only one of the two.
+
+`--advisory` prints the same verdict and always exits 0. That is how
+consumers run it for the first month; after that they drop the flag and
+it blocks.
+
+Enforcement runs on pull requests, comparing the head report against a
+report built at the merge-base:
+
+```yaml
+jobs:
+  mutation-compare:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bunx stryker run
+      - run: |
+          base="$(git merge-base HEAD origin/main)"
+          git worktree add /tmp/mutation-base "$base"
+          (cd /tmp/mutation-base && bun install --frozen-lockfile && bunx stryker run)
+      - run: bun run checks-mutation-compare --advisory /tmp/mutation-base/reports/mutation/mutation.json reports/mutation/mutation.json
+```
+
+The shared Stryker preset's `json` reporter writes
+`reports/mutation/mutation.json` in each worktree.
+
 ## Why it is shaped this way
 
 - `plugins` does not inherit through oxlint `extends`. `rules`,
@@ -307,12 +478,22 @@ of reach, so the figures are authored code.
   consumer's copy is compared key by key against the installed one
   instead. `[test] pathIgnorePatterns` is a real bunfig key, and an empty
   `--path-ignore-patterns` flag overrides the file's own list.
+- The Stryker preset is a JavaScript module, not JSON: Stryker 10 does
+  not resolve `extends` in a JSON config, but a `.mjs` config that
+  spreads an imported object consumes it. Keys the consumer sets after
+  the spread win.
 - Each runnable script ships a `checks-` bin entry, so consumer
   `package.json` scripts call the short name, which the package manager
   puts on `PATH` only there; a shell runs it through `bun run`, which
   never falls back to the registry the way `bunx` does. The `.ts` checks
   keep a `bun` shebang, which needs no build step and no `dist/`
   entry, unlike the oxlint plugin that node loads.
+- `checks-ci-wiring` runs inside `lint`, not in a workflow of its own:
+  deleting the step that runs a check is the violation it catches, so the
+  local `lint` is where it has to fail.
+- Workflows are parsed with `Bun.YAML`, which the `bun` shebang already
+  provides, so the check adds no dependency. It reads `on` as a string
+  key, not as the YAML 1.1 boolean.
 - `bun` counts as a built-in module. Nothing installed resolves it except
   `@types/bun`, which would otherwise make every runtime `bun` import look
   like a dev-only dependency.
@@ -346,7 +527,7 @@ a tag off `main` and reruns the build, `dist/` check, lint, typecheck
 and tests before it publishes:
 
 ```sh
-git tag v0.2.0 && git push origin v0.2.0
+git tag v0.4.0 && git push origin v0.4.0
 ```
 
 The `release` workflow publishes the tagged version through npm

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Deterministic checks shared across the captain's TypeScript repos",
   "license": "MIT",
   "repository": {
@@ -18,10 +18,13 @@
     "scripts/lint-coverage.sh",
     "scripts/test-layout.ts",
     "scripts/commit-identity.ts",
+    "scripts/mutation-compare.ts",
+    "scripts/ci-wiring.ts",
     "scripts/comments.ts",
     "scripts/comment-gate.ts",
     "scripts/backtest.ts",
     "oxlintrc.json",
+    "stryker.preset.js",
     "tsconfig.effect.json",
     "dist/index.js"
   ],
@@ -32,10 +35,13 @@
     "./scripts/lint-coverage.sh": "./scripts/lint-coverage.sh",
     "./scripts/test-layout.ts": "./scripts/test-layout.ts",
     "./scripts/commit-identity.ts": "./scripts/commit-identity.ts",
+    "./scripts/mutation-compare.ts": "./scripts/mutation-compare.ts",
+    "./scripts/ci-wiring.ts": "./scripts/ci-wiring.ts",
     "./scripts/comments.ts": "./scripts/comments.ts",
     "./scripts/comment-gate.ts": "./scripts/comment-gate.ts",
     "./scripts/backtest.ts": "./scripts/backtest.ts",
     "./oxlintrc.json": "./oxlintrc.json",
+    "./stryker.preset.js": "./stryker.preset.js",
     "./tsconfig.effect.json": "./tsconfig.effect.json",
     "./dist/index.js": "./dist/index.js"
   },
@@ -43,15 +49,29 @@
     "checks-lint-coverage": "scripts/lint-coverage.sh",
     "checks-test-layout": "scripts/test-layout.ts",
     "checks-commit-identity": "scripts/commit-identity.ts",
+    "checks-mutation-compare": "scripts/mutation-compare.ts",
+    "checks-ci-wiring": "scripts/ci-wiring.ts",
     "checks-comment-gate": "scripts/comment-gate.ts",
     "checks-backtest": "scripts/backtest.ts"
   },
   "scripts": {
     "build": "bun build effect-channel/index.ts --outdir dist --target node --format esm",
-    "lint": "oxlint --type-aware && ./scripts/lint-coverage.sh && bun scripts/test-layout.ts && bun scripts/commit-identity.ts HEAD && bun scripts/comment-gate.ts HEAD && depcruise --config .dependency-cruiser.cjs effect-channel scripts tests commitlint.config.js dependency-cruiser.config.js .dependency-cruiser.cjs",
+    "lint": "oxlint --type-aware && ./scripts/lint-coverage.sh && bun scripts/test-layout.ts && bun scripts/commit-identity.ts HEAD && bun scripts/comment-gate.ts HEAD && bun scripts/ci-wiring.ts && depcruise --config .dependency-cruiser.cjs effect-channel scripts tests commitlint.config.js dependency-cruiser.config.js stryker.preset.js .dependency-cruiser.cjs",
     "typecheck": "tsc --noEmit && effect-tsgo diagnostics --project tsconfig.json --format text --strict",
     "test": "bun test --randomize"
   },
+  "ciWiring": {
+    "gates": [
+      "bun run build",
+      "git diff --exit-code dist/",
+      "bun run lint",
+      "bun run typecheck",
+      "bun run test",
+      "./node_modules/.bin/commitlint",
+      "bun .checks/scripts/commit-identity.ts",
+      "bun .checks/scripts/comment-gate.ts"
+    ]
+  },
   "peerDependencies": {
     "@swc/core": "1.16.2",
     "dependency-cruiser": "18.4.0",

package/scripts/ci-wiring.ts

@@ -0,0 +1,327 @@
+#!/usr/bin/env bun
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export type Command = readonly string[];
+
+export type Gate = {
+  readonly command: string;
+  readonly words: Command;
+};
+
+export type Declaration = {
+  readonly gates: readonly Gate[];
+  readonly defaultBranch: string;
+};
+
+export type Workflow = {
+  readonly path: string;
+  readonly document: unknown;
+};
+
+export type BlockedInvocation = {
+  readonly location: string;
+  readonly blocker: string;
+};
+
+export type Gap = {
+  readonly gate: string;
+  readonly blocked: readonly BlockedInvocation[];
+};
+
+type RunStep = {
+  readonly location: string;
+  readonly blocker: string | undefined;
+  readonly script: string;
+};
+
+export class WiringError extends Error {}
+
+const WORKFLOWS = ".github/workflows";
+const DEFAULT_BRANCH = "main";
+// Without these a pull_request workflow never sees the commits a pull request pushes.
+const GATING_TYPES = ["opened", "synchronize"];
+const CONSTANTS = new Map([
+  ["true", true],
+  ["false", false],
+]);
+const STATUS_OVERRIDE = /\b(?:always|failure|cancelled)\s*\(/;
+const VARIABLE = /^\$(?:[A-Za-z_][A-Za-z0-9_]*|\{[A-Za-z_][A-Za-z0-9_]*\})/;
+const UNPLAIN = new Set(["|", "&", ";", "<", ">", "(", ")", "`", "\\", "#", "\n"]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function names(value: unknown): readonly string[] | undefined {
+  if (typeof value === "string") return [value];
+  if (!Array.isArray(value)) return undefined;
+  return value.filter((entry): entry is string => typeof entry === "string");
+}
+
+function expansion(text: string, from: number): number | undefined {
+  const match = VARIABLE.exec(text.slice(from));
+  return match === null ? undefined : from + match[0].length;
+}
+
+// A script counts only when it is one line of plain words: any shell control, redirection or
+// substitution can run the gate without its failure failing the step.
+function plainCommand(script: string): Command | undefined {
+  const line = script.trim();
+  const words: string[] = [];
+  let word: string | undefined;
+  for (let index = 0; index < line.length; index += 1) {
+    const char = line.charAt(index);
+    if (char === " " || char === "\t") {
+      if (word !== undefined) words.push(word);
+      word = undefined;
+    } else if (char === "'") {
+      const close = line.indexOf("'", index + 1);
+      if (close === -1) return undefined;
+      word = (word ?? "") + line.slice(index + 1, close);
+      index = close;
+    } else if (char === '"') {
+      let quoted = "";
+      for (index += 1; line.charAt(index) !== '"'; index += 1) {
+        const inner = line.charAt(index);
+        if (inner === "" || inner === "\\" || inner === "`") return undefined;
+        if (inner === "$") {
+          const end = expansion(line, index);
+          if (end === undefined) return undefined;
+          quoted += line.slice(index, end);
+          index = end - 1;
+        } else {
+          quoted += inner;
+        }
+      }
+      word = (word ?? "") + quoted;
+    } else if (char === "$") {
+      const end = expansion(line, index);
+      if (end === undefined) return undefined;
+      word = (word ?? "") + line.slice(index, end);
+      index = end - 1;
+    } else if (UNPLAIN.has(char)) {
+      return undefined;
+    } else {
+      word = (word ?? "") + char;
+    }
+  }
+  if (word !== undefined) words.push(word);
+  return words.length === 0 ? undefined : words;
+}
+
+function invokes(command: Command | undefined, gate: Command): boolean {
+  return command !== undefined && gate.length <= command.length && gate.every((word, index) => command[index] === word);
+}
+
+function mentions(script: string, gate: Command): boolean {
+  const tokens = script.split(/[\s|&;<>()`]+/);
+  return tokens.some((_, start) => invokes(tokens.slice(start), gate));
+}
+
+function constant(value: unknown): boolean | undefined {
+  if (typeof value === "boolean") return value;
+  if (typeof value !== "string") return undefined;
+  const expression = value.trim().replace(/^\$\{\{(.*)\}\}$/s, "$1").trim();
+  return CONSTANTS.get(expression);
+}
+
+function switchedOff(node: Readonly<Record<string, unknown>>, subject: string): string | undefined {
+  if (constant(node["if"]) === false) return `${subject} sets if: false`;
+  if (constant(node["continue-on-error"]) === true) return `${subject} sets continue-on-error: true`;
+  return undefined;
+}
+
+// Last match wins, as GitHub evaluates a branch filter, so one match anywhere is not enough.
+function selects(patterns: readonly string[], branch: string): boolean {
+  let selected = false;
+  for (const pattern of patterns) {
+    const excludes = pattern.startsWith("!");
+    if (new Bun.Glob(excludes ? pattern.slice(1) : pattern).match(branch)) selected = !excludes;
+  }
+  return selected;
+}
+
+function triggerBlocker(workflow: Workflow, branch: string): string | undefined {
+  const on = isRecord(workflow.document) ? workflow.document["on"] : undefined;
+  const events = isRecord(on) ? Object.keys(on) : (names(on) ?? []);
+  if (!events.includes("pull_request")) return `${workflow.path} does not trigger on pull_request`;
+
+  const filters = isRecord(on) ? on["pull_request"] : undefined;
+  if (!isRecord(filters)) return undefined;
+  const branches = names(filters["branches"]);
+  if (branches !== undefined && !selects(branches, branch)) {
+    return `${workflow.path} limits pull_request to branches other than ${branch}`;
+  }
+  const ignored = names(filters["branches-ignore"]);
+  if (ignored?.some((pattern) => new Bun.Glob(pattern).match(branch)) === true) {
+    return `${workflow.path} ignores pull_request to ${branch}`;
+  }
+  if (filters["paths"] !== undefined || filters["paths-ignore"] !== undefined) {
+    return `${workflow.path} filters pull_request by paths, so some pull requests skip the gate`;
+  }
+  const types = names(filters["types"]);
+  const missing = types === undefined ? [] : GATING_TYPES.filter((type) => !types.includes(type));
+  if (missing.length > 0) return `${workflow.path} limits pull_request to types without ${missing.join(", ")}`;
+  return undefined;
+}
+
+// GitHub prefixes any other if: with success(), so only a status function overrides a needed job's skip.
+function skippedBy(jobs: Readonly<Record<string, unknown>>, id: string, seen: readonly string[]): string | undefined {
+  const job = jobs[id];
+  if (!isRecord(job) || seen.includes(id)) return undefined;
+  if (constant(job["if"]) === false) return `job ${id} sets if: false`;
+  if (typeof job["if"] === "string" && STATUS_OVERRIDE.test(job["if"])) return undefined;
+  for (const need of names(job["needs"]) ?? []) {
+    const cause = skippedBy(jobs, need, [...seen, id]);
+    if (cause !== undefined) return cause;
+  }
+  return undefined;
+}
+
+function localCall(uses: unknown): string | undefined {
+  return typeof uses === "string" && uses.startsWith("./") ? uses.slice(2) : undefined;
+}
+
+function runSteps(workflows: readonly Workflow[], branch: string): readonly RunStep[] {
+  const documents = new Map(workflows.map((workflow) => [workflow.path, workflow.document]));
+  const steps: RunStep[] = [];
+
+  const visit = (
+    document: unknown,
+    location: string,
+    blocker: string | undefined,
+    walked: readonly string[],
+  ): void => {
+    const jobs = isRecord(document) ? document["jobs"] : undefined;
+    if (!isRecord(jobs)) return;
+    for (const [id, job] of Object.entries(jobs)) {
+      if (!isRecord(job)) continue;
+      const jobLocation = `${location} job ${id}`;
+      const skipped = skippedBy(jobs, id, []);
+      const jobBlocker =
+        blocker ??
+        switchedOff(job, `job ${id}`) ??
+        (skipped === undefined ? undefined : `job ${id} needs a job that never runs: ${skipped}`);
+      const called = localCall(job["uses"]);
+      if (called !== undefined && !walked.includes(called)) {
+        visit(documents.get(called), `${jobLocation} > ${called}`, jobBlocker, [...walked, called]);
+      }
+      const jobSteps = job["steps"];
+      if (!Array.isArray(jobSteps)) continue;
+      jobSteps.forEach((step: unknown, index) => {
+        if (!isRecord(step) || typeof step["run"] !== "string") return;
+        steps.push({
+          location: `${jobLocation} step ${index + 1}`,
+          blocker: jobBlocker ?? switchedOff(step, "the step"),
+          script: step["run"],
+        });
+      });
+    }
+  };
+
+  for (const workflow of workflows) {
+    visit(workflow.document, workflow.path, triggerBlocker(workflow, branch), [workflow.path]);
+  }
+  return steps;
+}
+
+export function findGaps(declaration: Declaration, workflows: readonly Workflow[]): readonly Gap[] {
+  const steps = runSteps(workflows, declaration.defaultBranch);
+  return declaration.gates.flatMap((gate) => {
+    const alone = `the step runs more than ${gate.command}; give it its own step with nothing else in it`;
+    const invoking = steps.flatMap(({ location, blocker, script }) => {
+      if (invokes(plainCommand(script), gate.words)) return [{ location, blocker }];
+      return mentions(script, gate.words) ? [{ location, blocker: blocker ?? alone }] : [];
+    });
+    if (invoking.some((step) => step.blocker === undefined)) return [];
+    const blocked = invoking.flatMap(({ location, blocker }) =>
+      blocker === undefined ? [] : [{ location, blocker }],
+    );
+    return [{ gate: gate.command, blocked }];
+  });
+}
+
+export function formatReport(declaration: Declaration, gaps: readonly Gap[]): string {
+  const target = `pull requests to ${declaration.defaultBranch}`;
+  if (gaps.length === 0) return `ci-wiring: ${declaration.gates.length} gate(s) run on ${target}`;
+  const lines = [`ci-wiring: ${gaps.length} of ${declaration.gates.length} gate(s) do not run on ${target}:`];
+  for (const gap of gaps) {
+    lines.push(`  ${gap.gate}`);
+    if (gap.blocked.length === 0) lines.push("    no run step invokes it");
+    for (const { location, blocker } of gap.blocked) lines.push(`    ${location}: ${blocker}`);
+  }
+  return lines.join("\n");
+}
+
+export function parseDeclaration(manifest: unknown, source: string): Declaration {
+  const configured = isRecord(manifest) && isRecord(manifest["ciWiring"]) ? manifest["ciWiring"] : {};
+  const listed = configured["gates"];
+  if (!Array.isArray(listed) || listed.length === 0) {
+    throw new WiringError(`ci-wiring: ${source} sets no ciWiring.gates, a non-empty array of commands`);
+  }
+  const gates = listed.map((command: unknown): Gate => {
+    const words = typeof command === "string" ? plainCommand(command) : undefined;
+    if (typeof command !== "string" || words === undefined) {
+      throw new WiringError(`ci-wiring: ${source} ciWiring gate ${JSON.stringify(command)} is not one plain command`);
+    }
+    return { command, words };
+  });
+  const defaultBranch = configured["defaultBranch"] ?? DEFAULT_BRANCH;
+  if (typeof defaultBranch !== "string" || defaultBranch === "") {
+    throw new WiringError(`ci-wiring: ${source} ciWiring.defaultBranch is not a branch name`);
+  }
+  return { gates, defaultBranch };
+}
+
+export function parseWorkflow(path: string, text: string): Workflow {
+  try {
+    return { path, document: Bun.YAML.parse(text) };
+  } catch (error) {
+    throw new WiringError(`ci-wiring: cannot parse ${path}: ${String(error)}`);
+  }
+}
+
+export function readDeclaration(root: string): Declaration {
+  const path = join(root, "package.json");
+  let manifest: unknown;
+  try {
+    manifest = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    throw new WiringError(`ci-wiring: cannot read ${path} as JSON`);
+  }
+  return parseDeclaration(manifest, path);
+}
+
+export function readWorkflows(root: string): readonly Workflow[] {
+  const directory = join(root, WORKFLOWS);
+  if (!existsSync(directory)) return [];
+  return readdirSync(directory)
+    .filter((name) => name.endsWith(".yml") || name.endsWith(".yaml"))
+    .sort()
+    .map((name) => parseWorkflow(`${WORKFLOWS}/${name}`, readFileSync(join(directory, name), "utf8")));
+}
+
+function repositoryRoot(): string {
+  const result = Bun.spawnSync(["git", "rev-parse", "--show-toplevel"], { stdout: "pipe", stderr: "pipe" });
+  if (!result.success) {
+    throw new WiringError(`ci-wiring: git rev-parse --show-toplevel: ${result.stderr.toString().trim()}`);
+  }
+  return result.stdout.toString().trim();
+}
+
+if (import.meta.main) {
+  try {
+    const root = repositoryRoot();
+    const declaration = readDeclaration(root);
+    const gaps = findGaps(declaration, readWorkflows(root));
+    if (gaps.length > 0) {
+      console.error(formatReport(declaration, gaps));
+      process.exit(1);
+    }
+    console.log(formatReport(declaration, gaps));
+  } catch (error) {
+    console.error(error instanceof WiringError ? error.message : `ci-wiring: ${String(error)}`);
+    process.exit(2);
+  }
+}

package/scripts/mutation-compare.ts

@@ -0,0 +1,173 @@
+#!/usr/bin/env bun
+import { readFile } from "node:fs/promises";
+
+export type Tally = {
+  readonly killed: number;
+  readonly total: number;
+};
+
+export type FileComparison = {
+  readonly path: string;
+  readonly base: Tally;
+  readonly head: Tally;
+};
+
+export type Comparison = {
+  readonly base: Tally;
+  readonly head: Tally;
+  readonly files: readonly FileComparison[];
+  readonly regression: boolean;
+};
+
+export type Options = {
+  readonly basePath: string;
+  readonly headPath: string;
+  readonly advisory: boolean;
+};
+
+export class ReportError extends Error {}
+
+const DETECTED = new Set(["Killed", "Timeout"]);
+const UNDETECTED = new Set(["Survived", "NoCoverage"]);
+const USAGE = "usage: mutation-compare.ts [--advisory] <base-report> <head-report>";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+export function parseReport(text: string): Map<string, readonly string[]> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new ReportError("mutation-compare: report is not valid JSON");
+  }
+  if (!isRecord(parsed) || !isRecord(parsed["files"])) {
+    throw new ReportError("mutation-compare: report has no files table");
+  }
+  const files = new Map<string, readonly string[]>();
+  for (const [path, entry] of Object.entries(parsed["files"])) {
+    if (!isRecord(entry) || !Array.isArray(entry["mutants"])) {
+      throw new ReportError(`mutation-compare: ${path} has no mutants list`);
+    }
+    const statuses: string[] = [];
+    for (const mutant of entry["mutants"]) {
+      if (!isRecord(mutant) || typeof mutant["status"] !== "string") {
+        throw new ReportError(`mutation-compare: ${path} carries a mutant without a status`);
+      }
+      statuses.push(mutant["status"]);
+    }
+    files.set(path, statuses);
+  }
+  return files;
+}
+
+function tally(statuses: readonly string[]): Tally {
+  let killed = 0;
+  let total = 0;
+  for (const status of statuses) {
+    if (DETECTED.has(status)) killed += 1;
+    if (DETECTED.has(status) || UNDETECTED.has(status)) total += 1;
+  }
+  return { killed, total };
+}
+
+const EMPTY: Tally = { killed: 0, total: 0 };
+
+export function compareReports(
+  baseFiles: ReadonlyMap<string, readonly string[]>,
+  headFiles: ReadonlyMap<string, readonly string[]>,
+): Comparison {
+  const paths = [...new Set([...baseFiles.keys(), ...headFiles.keys()])].sort();
+  const files = paths.map((path) => {
+    const baseStatuses = baseFiles.get(path);
+    const headStatuses = headFiles.get(path);
+    return {
+      path,
+      base: baseStatuses === undefined ? EMPTY : tally(baseStatuses),
+      head: headStatuses === undefined ? EMPTY : tally(headStatuses),
+    };
+  });
+  const base = tally([...baseFiles.values()].flat());
+  const head = tally([...headFiles.values()].flat());
+  return { base, head, files, regression: regressed(base, head) };
+}
+
+export function regressed(base: Tally, head: Tally): boolean {
+  if (base.total === 0) return head.total > 0 && head.killed < head.total;
+  if (head.total === 0) return false;
+  return head.killed * base.total < base.killed * head.total;
+}
+
+function points(count: Tally): number {
+  return count.total === 0 ? 100 : (100 * count.killed) / count.total;
+}
+
+function percent(count: Tally): string {
+  return count.total === 0 ? "n/a" : `${points(count).toFixed(2)}%`;
+}
+
+function describe(count: Tally): string {
+  return `${percent(count)} (${count.killed}/${count.total})`;
+}
+
+function deltaPoints(base: Tally, head: Tally): string {
+  const delta = points(head) - points(base);
+  return `${delta < 0 ? "-" : "+"}${Math.abs(delta).toFixed(2)}pp`;
+}
+
+export function formatComparison(comparison: Comparison, advisory: boolean): string {
+  const changed = comparison.files.filter(
+    (file) => file.base.killed !== file.head.killed || file.base.total !== file.head.total,
+  );
+  const unchanged = comparison.files.length - changed.length;
+  const lines = [
+    `mutation-compare: base ${describe(comparison.base)} head ${describe(comparison.head)} delta ${deltaPoints(comparison.base, comparison.head)}`,
+  ];
+  for (const file of changed) {
+    lines.push(`  ${file.path}: ${describe(file.base)} -> ${describe(file.head)}`);
+  }
+  if (unchanged > 0) lines.push(`  ${unchanged} unchanged file(s)`);
+  if (comparison.regression) {
+    lines.push(`mutation-compare: REGRESSION (${deltaPoints(comparison.base, comparison.head)})${advisory ? " in advisory mode, exit 0" : ""}`);
+  } else {
+    lines.push(`mutation-compare: no regression${advisory ? " (advisory mode, exit 0)" : ""}`);
+  }
+  return lines.join("\n");
+}
+
+export function parseArgs(argv: readonly string[]): Options {
+  let advisory = false;
+  const paths: string[] = [];
+  for (const arg of argv) {
+    if (arg === "--advisory") advisory = true;
+    else if (arg.startsWith("--")) throw new ReportError(`${USAGE}: unknown flag ${arg}`);
+    else paths.push(arg);
+  }
+  if (paths.length !== 2 || paths[0] === undefined || paths[1] === undefined) throw new ReportError(USAGE);
+  return { basePath: paths[0], headPath: paths[1], advisory };
+}
+
+export function exitFor(comparison: Comparison, advisory: boolean): number {
+  return comparison.regression && !advisory ? 1 : 0;
+}
+
+async function load(path: string): Promise<string> {
+  try {
+    return await readFile(path, "utf8");
+  } catch {
+    throw new ReportError(`mutation-compare: cannot read ${path}`);
+  }
+}
+
+if (import.meta.main) {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    const comparison = compareReports(parseReport(await load(options.basePath)), parseReport(await load(options.headPath)));
+    console.log(formatComparison(comparison, options.advisory));
+    process.exit(exitFor(comparison, options.advisory));
+  } catch (error) {
+    console.error(error instanceof ReportError ? error.message : `mutation-compare: ${String(error)}`);
+    process.exit(2);
+  }
+}

package/scripts/test-layout.ts

@@ -39,6 +39,9 @@ const BANNED_BUN_NAMES: readonly string[] = [
 const BANNED_GLOBAL_CALLS: readonly string[] = ["fetch"];
 
 export const REQUIRED_TEST_SCRIPT = "bun test --randomize";
+const REQUIRED_TEST_TABLE: Record<string, unknown> = {
+  pathIgnorePatterns: ["**/tests/quarantine/**"],
+};
 export const LAYOUT_CHECK_MARK = "scripts/test-layout.ts";
 export const LAYOUT_CHECK_BIN = "checks-test-layout";
 
@@ -236,9 +239,10 @@ export function bunfigViolations(consumer: unknown, preset: unknown): readonly V
   if (!isRecord(presetTest)) {
     return [{ file, line: undefined, message: "the shipped bunfig preset has no [test] table" }];
   }
+  const expected = { ...presetTest, ...REQUIRED_TEST_TABLE };
   const consumerTest = isRecord(consumer) ? consumer["test"] : undefined;
   const violations: Violation[] = [];
-  for (const [key, value] of Object.entries(presetTest)) {
+  for (const [key, value] of Object.entries(expected)) {
     const found = isRecord(consumerTest) ? consumerTest[key] : undefined;
     if (!Bun.deepEquals(found, value)) {
       violations.push({

package/stryker.preset.js

@@ -0,0 +1,13 @@
+export default {
+  packageManager: "npm",
+  plugins: ["@stryker-mutator/*", "@hughescr/stryker-bun-runner"],
+  testRunner: "bun",
+  bun: { timeout: 60000 },
+  inPlace: true,
+  tempDirName: "../.stryker-tmp",
+  coverageAnalysis: "perTest",
+  reporters: ["html", "json", "clear-text", "progress"],
+  timeoutMS: 60000,
+  concurrency: 8,
+  thresholds: { high: 85, low: 70, break: null },
+};