@avi2dg/checks 0.3.0 → 0.5.0

package/README.md

@@ -6,8 +6,8 @@ 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, the Stryker mutation-testing preset with its
-no-regression comparator, and the Effect error-channel plugin compiled
-to JavaScript.
+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.
 
@@ -80,6 +80,48 @@ export default {
 The registry version is pinned by the consumer's lockfile; bump
 `@avi2dg/checks` to adopt a new release.
 
+## Effect rules
+
+The base config loads the `effect-channel` plugin and turns on
+`effect-channel/no-error-channel-escape`, which refuses `Effect.ignore`,
+`Effect.ignoreCause`, the `Effect.catchCause` family, and an
+`Effect.catch` whose handler takes no error or names it `_`.
+
+Two more rules ship off, because a repository writes only some of its
+paths in Effect: code a host loads without `node_modules`, such as a
+hook bundle or this oxlint plugin, cannot import it.
+
+- `effect-channel/no-throw` refuses a `throw` statement.
+- `effect-channel/no-try-catch` refuses a `try` statement with a
+  `catch` clause. `try`/`finally` stays allowed.
+
+Each refusal says what to write instead: a `Schema.TaggedError` failed
+through `Effect.fail`, a throwing call wrapped in `Effect.try` or
+`Effect.tryPromise`, and recovery by tag with `Effect.catchTag`.
+
+A repository turns them on for the paths it writes in Effect through an
+`overrides` entry in its root `.oxlintrc.json`:
+
+```json
+{
+  "extends": ["./node_modules/@avi2dg/checks/oxlintrc.json"],
+  "plugins": ["typescript", "oxc", "eslint", "import"],
+  "overrides": [
+    {
+      "files": ["src/**"],
+      "rules": {
+        "effect-channel/no-throw": "error",
+        "effect-channel/no-try-catch": "error"
+      }
+    }
+  ]
+}
+```
+
+oxlint resolves `files` against the directory of the config that holds
+the override, so a config passed with `-c` from outside the repository
+matches nothing and reports nothing.
+
 ## Test layout
 
 `checks-test-layout` fails unless the repo holds this shape, and names the
@@ -105,7 +147,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
@@ -183,7 +228,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
@@ -234,10 +287,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.
 
@@ -271,9 +334,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
@@ -376,6 +530,12 @@ The shared Stryker preset's `json` reporter writes
   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.
@@ -409,7 +569,7 @@ a tag off `main` and reruns the build, `dist/` check, lint, typecheck
 and tests before it publishes:
 
 ```sh
-git tag v0.3.0 && git push origin v0.3.0
+git tag v0.5.0 && git push origin v0.5.0
 ```
 
 The `release` workflow publishes the tagged version through npm

package/dist/index.js

@@ -69,10 +69,52 @@ var rule = {
 };
 var no_error_channel_escape_default = rule;
 
+// effect-channel/no-throw.ts
+var rule2 = {
+  meta: {
+    type: "problem",
+    docs: { description: "Disallow throw, which fails outside Effect's error channel" }
+  },
+  create(context) {
+    return {
+      ThrowStatement(node) {
+        context.report({
+          node,
+          message: "throw escapes the error channel: no type records the failure, so no caller has to answer for it. Define the failure with Schema.TaggedError and fail with it through Effect.fail, so it stays in E for Effect.catchTag to handle"
+        });
+      }
+    };
+  }
+};
+var no_throw_default = rule2;
+
+// effect-channel/no-try-catch.ts
+var rule3 = {
+  meta: {
+    type: "problem",
+    docs: { description: "Disallow a try statement with a catch clause, which recovers outside Effect's error channel" }
+  },
+  create(context) {
+    return {
+      CatchClause(node) {
+        context.report({
+          node,
+          message: "catch recovers outside the error channel: it takes whatever was thrown as unknown, bugs included. Wrap the throwing call in Effect.try or Effect.tryPromise, whose catch maps the cause to a Schema.TaggedError, and recover by tag with Effect.catchTag"
+        });
+      }
+    };
+  }
+};
+var no_try_catch_default = rule3;
+
 // effect-channel/index.ts
 var plugin = {
   meta: { name: "effect-channel" },
-  rules: { "no-error-channel-escape": no_error_channel_escape_default }
+  rules: {
+    "no-error-channel-escape": no_error_channel_escape_default,
+    "no-throw": no_throw_default,
+    "no-try-catch": no_try_catch_default
+  }
 };
 var effect_channel_default = plugin;
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Deterministic checks shared across the captain's TypeScript repos",
   "license": "MIT",
   "repository": {
@@ -19,6 +19,7 @@
     "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",
@@ -35,6 +36,7 @@
     "./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",
@@ -48,15 +50,28 @@
     "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 stryker.preset.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/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({