@avi2dg/checks 0.41.0 → 0.42.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.42.0
+
+Released 2026-10-14.
+
+### Features
+
+- **delivery:** fail a setup-bun step whose Bun version drifts from the fleet pin [#156](https://github.com/avi2d/checks/pull/156)
+
+## 0.41.1
+
+Released 2026-10-14.
+
+### Fixes
+
+- **delivery:** refuse workflow references to missing workflows or jobs in ci-wiring [#153](https://github.com/avi2d/checks/pull/153)
+
 ## 0.41.0
 
 Released 2026-10-12.

package/README.md

@@ -10,7 +10,7 @@ Each repository owns its workflows and native tool configs, as [Native settings]
 <!-- generated prerequisites: bun run build writes it from package.json, .bun-version and scripts/doc-blocks.ts -->
 
 - A git repository, whose history the range gates read.
-- Bun 1.4.2, which runs every bin.
+- Bun 1.4.3, which runs every bin.
 - The peer dependencies, at the exact versions the kit pins:
   - `@effect/tsgo` 0.45.0
   - `@swc/core` 1.16.2
@@ -96,6 +96,8 @@ To consume the kit from a repository:
    "test": "checks-test"
    ```
 
+1. Write the Bun version [Before you begin](#before-you-begin) names to `.bun-version`, which [checks-ci-wiring](docs/gates/checks-ci-wiring.md#bun-version) holds every setup-bun step to.
+
 1. Run the scripts on every pull request in `.github/workflows/ci.yml`, fetching the whole history the range needs:
 
    ```yaml
@@ -109,6 +111,8 @@ To consume the kit from a repository:
            with:
              fetch-depth: 0
          - uses: oven-sh/setup-bun@v2
+           with:
+             bun-version-file: .bun-version
          - run: bun install --frozen-lockfile
          - run: bun run build
          - run: git diff --exit-code

package/docs/gates/checks-advisories.md

@@ -115,6 +115,8 @@ jobs:
     steps:
       - uses: actions/checkout@v5
       - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
       - run: bun install --frozen-lockfile
       - run: ./node_modules/.bin/checks-advisories --all
 ```

package/docs/gates/checks-ci-wiring.md

@@ -21,6 +21,14 @@ The check follows local reusable workflows but not remote reusable workflows.
 It refuses a step or job with `if: false` or `continue-on-error: true`.
 It also refuses a workflow that does not trigger on both `opened` and `synchronize` pull requests to the target branch.
 A path filter cannot cover every pull request and therefore cannot satisfy the check.
+It refuses a reference to a workflow or job the repository does not hold.
+Each literal `checks-release-pr` and `checks-release-tag` argument names a workflow file, so every one must match a file under `.github/workflows/`.
+An argument built from a variable or an expression is known only when the job runs, so the check passes over it.
+Each `on.workflow_run.workflows` entry names a workflow by its `name`, so every one must match a name in the repository.
+A workflow without a `name` answers to its path from the repository root.
+A local reusable `uses` must name a file under `.github/workflows/` that the repository holds.
+Each `needs` entry names a job in the same workflow, so every one must match a job id in that file.
+Each refusal names the file, the line and the missing workflow or job.
 
 ### Runners
 
@@ -41,9 +49,33 @@ In a private repository each mutation job carries exactly the labels `[self-host
 A public repository may keep `runs-on: ubuntu-latest` on every job, because a pull request from a fork runs its own code on the runner.
 The check knows a repository is private only from GitHub's event, so a run outside CI judges only the rules that hold in either.
 
+### Bun version
+
+It also judges every step that uses `oven-sh/setup-bun`.
+A step at ref `v2`, `v2.<minor>` or `v2.<minor>.<patch>` resolves its effective version in the order setup-bun v2 reads it.
+A step at any other ref or at none fails, because the check knows only setup-bun v2's version resolution.
+An input name matches in any case, as GitHub reads it.
+The step input `with.bun-version` wins when it names a version, and an unquoted number counts as the text GitHub passes.
+Else the file the step input `with.bun-version-file` names decides by its basename, when it yields a version.
+A `package.json` file reads `packageManager` after `bun@`, and reads `engines.bun` only when `packageManager` is absent or holds no `bun@`.
+A `.tool-versions` file reads the rest of the first line that starts with `bun`.
+A `.bun-version` or `.bumrc` file reads the whole trimmed file.
+Else the `package.json` at the workspace root reads the same way.
+Else setup-bun installs latest.
+A blank version counts as none.
+A repository passes by writing the fleet version to `.bun-version` and naming that file in each step's `with.bun-version-file`.
+The step fails the check when the version is missing or differs from the fleet bun version.
+A range fails because it differs from the fleet version.
+A version built from an expression fails because it cannot be shown equal before the run.
+This rule skips a repository with no setup-bun step.
+The fleet bun version equals the dotfiles mise pin.
+A bump moves both together, so a kit release that moves the fleet version turns each consumer red until its pin follows.
+Each refusal names the workflow file and line, the version found and where it was read, and the fleet version.
+
 ## What it reads
 
 The bin reads `.github/workflows/*.yml`, `*.yaml`, the `scripts` in `package.json` and the shell scripts those steps and scripts run from the working tree.
+It reads each file a setup-bun step names for its version.
 It reads the target branch from `GITHUB_BASE_REF`, then from `refs/remotes/origin/HEAD` and then from the event file `GITHUB_EVENT_PATH` names.
 It reads whether the repository is private from `repository.private` in that event file.
 It parses the workflows with `Bun.YAML` without executing them.
@@ -57,7 +89,7 @@ It takes no arguments.
 | Code | Result |
 | --- | --- |
 | 0 | Every required command has a reachable step. |
-| 1 | A required command is missing or blocked, or a job runs on the wrong runner. |
+| 1 | A required command is missing or blocked, a job runs on the wrong runner, a workflow names a missing workflow or job, or a setup-bun step drifts from the fleet bun version. |
 | 2 | A workflow or `package.json` cannot be decoded. |
 
 ## Sample output
@@ -77,6 +109,13 @@ ci-wiring: 1 job(s) run on the wrong runner:
   .github/workflows/mutation-compare.yml job mutation-compare: a mutation job reads CI_RUNS_ON, so an override moves its full sweeps off winbox; set runs-on: [self-hosted, Linux, X64, winbox]
 ```
 
+A reference to a missing workflow produces a report like this:
+
+```
+ci-wiring: 1 reference(s) name a missing workflow or job:
+  .github/workflows/daily-release.yml line 31: names missing workflow commitlint.yml
+```
+
 ## When it runs
 
 `checks-lint` runs it in every repository.

package/docs/gates/checks-flake.md

@@ -67,6 +67,8 @@ jobs:
     steps:
       - uses: actions/checkout@v5
       - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
       - run: bun install --frozen-lockfile
       - run: bunx checks-flake --runs 10 --report flake-report.json
       - uses: actions/upload-artifact@v4

package/docs/gates/checks-mutation-compare.md

@@ -92,6 +92,8 @@ jobs:
         with:
           fetch-depth: 0
       - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
       - run: bun install --frozen-lockfile
       - run: bunx stryker run
       - run: |

package/docs/gates/checks-release-notes.md

@@ -69,6 +69,8 @@ jobs:
       - name: ref is a tag
         run: test "$GITHUB_REF_TYPE" = tag
       - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
       - run: bun install --frozen-lockfile
       - run: bun run build
       - run: git diff --exit-code
@@ -89,6 +91,8 @@ jobs:
         with:
           fetch-depth: 0
       - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
       - run: bun install --frozen-lockfile
       - name: extract release notes
         run: ./node_modules/.bin/checks-release-notes "${GITHUB_REF_NAME#v}" "$RUNNER_TEMP/release-notes.md"
@@ -120,6 +124,8 @@ jobs:
       - name: ref is a tag
         run: test "$GITHUB_REF_TYPE" = tag
       - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
       - run: bun install --frozen-lockfile
       - run: bun run build
       - run: git diff --exit-code

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "license": "MIT",
   "repository": {
@@ -51,6 +51,8 @@
     "src/testing/subsumed-tests.ts",
     "src/delivery/ci-wiring.ts",
     "src/delivery/shell-command.ts",
+    "src/delivery/workflow-references.ts",
+    "src/delivery/bun-pin.ts",
     "src/delivery/mutation-job.ts",
     "src/delivery/secrets.ts",
     "src/delivery/gitleaks.ts",

package/src/delivery/bun-pin.ts

@@ -0,0 +1,174 @@
+import { Effect, FileSystem, Path, Schema } from "effect";
+import { within } from "./mutation-job.ts";
+import { isRecord, locate, workflowJobs, type Workflow } from "./workflow-references.ts";
+
+export const FLEET_BUN_VERSION = "1.4.3";
+const ROOT_MANIFEST = "package.json";
+
+export type BunPinPolicy = {
+  readonly files: ReadonlyMap<string, string>;
+  readonly manifests: ReadonlyMap<string, unknown>;
+};
+
+export type BunPinFault = {
+  readonly location: string;
+  readonly fault: string;
+};
+
+const SETUP_BUN = /^oven-sh\/setup-bun(?:@(?<ref>.*))?$/i;
+const V2_REF = /^v2(?:\.\d+){0,2}$/;
+
+function setupBunRef(uses: unknown): string | undefined {
+  const match = typeof uses === "string" ? SETUP_BUN.exec(uses.trim()) : null;
+  return match === null ? undefined : (match.groups?.["ref"] ?? "");
+}
+
+function isExpression(value: string): boolean {
+  return value.includes("${{");
+}
+
+function baseName(name: string): string {
+  return name.slice(name.lastIndexOf("/") + 1);
+}
+
+function actionInput(step: Readonly<Record<string, unknown>>, name: string): string {
+  const inputs = isRecord(step["with"]) ? step["with"] : {};
+  const value = Object.entries(inputs).find(([key]) => key.toLowerCase() === name)?.[1];
+  return typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? String(value).trim() : "";
+}
+
+function nonEmpty(version: string | undefined): string | undefined {
+  const trimmed = version?.trim();
+  return trimmed === "" ? undefined : trimmed;
+}
+
+function manifestBunVersion(manifest: unknown): string | undefined {
+  if (!isRecord(manifest)) return undefined;
+  const manager = manifest["packageManager"];
+  const engines = manifest["engines"];
+  const engine = isRecord(engines) ? engines["bun"] : undefined;
+  const version = manager === undefined || manager === null ? engine : typeof manager === "string" ? (manager.split("bun@")[1] ?? engine) : undefined;
+  return typeof version === "string" ? nonEmpty(version) : undefined;
+}
+
+const FILE_READERS = new Map<string, (text: string) => string | undefined>([
+  [".tool-versions", (text) => /^bun\s*(?<version>.*?)$/m.exec(text)?.groups?.["version"]],
+  [".bumrc", (text) => text],
+  [".bun-version", (text) => text],
+]);
+
+function fileBunVersion(policy: BunPinPolicy, key: string): string | undefined {
+  if (baseName(key) === "package.json") return manifestBunVersion(policy.manifests.get(key));
+  const text = policy.files.get(key);
+  const read = FILE_READERS.get(baseName(key));
+  return text === undefined || read === undefined ? undefined : nonEmpty(read(text));
+}
+
+type BunPinRequest = {
+  readonly version: string | undefined;
+  readonly source: string;
+  readonly expression: string | undefined;
+};
+
+function rootRequest(policy: BunPinPolicy, consulted: string): BunPinRequest {
+  const version = manifestBunVersion(policy.manifests.get(ROOT_MANIFEST));
+  return { version, source: version === undefined ? consulted : ROOT_MANIFEST, expression: undefined };
+}
+
+function bunPinRequest(policy: BunPinPolicy, step: Readonly<Record<string, unknown>>): BunPinRequest {
+  const pinned = actionInput(step, "bun-version");
+  if (pinned !== "") {
+    return isExpression(pinned)
+      ? { version: undefined, source: "with.bun-version", expression: pinned }
+      : { version: pinned, source: "with.bun-version", expression: undefined };
+  }
+  const file = actionInput(step, "bun-version-file");
+  if (file === "") return rootRequest(policy, ROOT_MANIFEST);
+  const source = `with.bun-version-file ${file}`;
+  if (isExpression(file)) return { version: undefined, source, expression: file };
+  const key = within("", file);
+  const version = key === undefined ? undefined : fileBunVersion(policy, key);
+  return version === undefined ? rootRequest(policy, `${source} or ${ROOT_MANIFEST}`) : { version, source, expression: undefined };
+}
+
+function bunPinFault(policy: BunPinPolicy, step: Readonly<Record<string, unknown>>): string | undefined {
+  const request = bunPinRequest(policy, step);
+  if (request.expression !== undefined) {
+    return `requests bun ${request.expression} from ${request.source}, which cannot be shown equal to ${FLEET_BUN_VERSION} before the run`;
+  }
+  if (request.version === undefined) {
+    return `pins no bun version from ${request.source}, so setup-bun installs latest, want ${FLEET_BUN_VERSION}`;
+  }
+  return request.version === FLEET_BUN_VERSION ? undefined : `requests bun ${request.version} from ${request.source}, want ${FLEET_BUN_VERSION}`;
+}
+
+function unknownRefFault(ref: string): string {
+  return `uses oven-sh/setup-bun at ${ref === "" ? "no ref" : ref}, but the check knows only setup-bun v2's version resolution, so the step must use oven-sh/setup-bun@v2`;
+}
+
+export function findBunPinFaults(policy: BunPinPolicy, workflows: readonly Workflow[]): readonly BunPinFault[] {
+  return workflows.flatMap((workflow) => {
+    const at = locate(workflow.path, workflow.text.split("\n"));
+    return workflowJobs(workflow).flatMap(([id, job]) => {
+      const steps = Array.isArray(job["steps"]) ? job["steps"] : [];
+      return steps.flatMap((step: unknown, index: number) => {
+        if (!isRecord(step)) return [];
+        const ref = setupBunRef(step["uses"]);
+        if (ref === undefined) return [];
+        const fault = V2_REF.test(ref) ? bunPinFault(policy, step) : unknownRefFault(ref);
+        return fault === undefined ? [] : [{ location: at(["jobs", id, "steps", index, "uses"], String(step["uses"]), `job ${id} step ${index + 1}`), fault }];
+      });
+    });
+  });
+}
+
+export function formatBunPinReport(faults: readonly BunPinFault[]): string {
+  return [`ci-wiring: ${faults.length} setup-bun step(s) drift from the fleet bun version:`, ...faults.map(({ location, fault }) => `  ${location}: ${fault}`)].join("\n");
+}
+
+function versionFileKeys(job: Readonly<Record<string, unknown>>): readonly string[] {
+  const steps = Array.isArray(job["steps"]) ? job["steps"] : [];
+  const keys: string[] = [];
+  for (const step of steps) {
+    if (!isRecord(step) || !V2_REF.test(setupBunRef(step["uses"]) ?? "")) continue;
+    const file = actionInput(step, "bun-version-file");
+    if (file === "" || isExpression(file)) continue;
+    const key = within("", file);
+    if (key !== undefined) keys.push(key);
+  }
+  return keys;
+}
+
+function wantedBunPinFiles(workflows: readonly Workflow[]): ReadonlySet<string> {
+  const wanted = new Set<string>([ROOT_MANIFEST]);
+  for (const workflow of workflows) {
+    for (const [, job] of workflowJobs(workflow)) {
+      for (const key of versionFileKeys(job)) wanted.add(key);
+    }
+  }
+  return wanted;
+}
+
+const readJsonFile = Effect.fn("readJsonFile")(function* (file: string) {
+  return yield* (yield* FileSystem.FileSystem).readFileString(file).pipe(
+    Effect.flatMap(Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown))),
+    Effect.orElseSucceed((): undefined => undefined),
+  );
+});
+
+export const readBunPinPolicy = Effect.fn("readBunPinPolicy")(function* (root: string, workflows: readonly Workflow[]) {
+  const path = yield* Path.Path;
+  const fs = yield* FileSystem.FileSystem;
+  const files = new Map<string, string>();
+  const manifests = new Map<string, unknown>();
+  for (const name of wantedBunPinFiles(workflows)) {
+    if (baseName(name) === "package.json") {
+      const parsed: unknown = yield* readJsonFile(path.join(root, name));
+      if (parsed !== undefined) manifests.set(name, parsed);
+    } else {
+      const text = yield* fs.readFileString(path.join(root, name)).pipe(Effect.orElseSucceed((): undefined => undefined));
+      if (text !== undefined) files.set(name, text);
+    }
+  }
+  return { files, manifests };
+});

package/src/delivery/ci-wiring.ts

@@ -3,8 +3,13 @@ import { Config, Console, Effect, FileSystem, Path, Schema } from "effect";
 import { defaultBranch, git } from "../core/git.ts";
 import { runMain } from "../core/main.ts";
 import { ENTRY_POINT, KIT_GATES, type KitGate } from "../core/gates.ts";
+import { findBunPinFaults, formatBunPinReport, readBunPinPolicy } from "./bun-pin.ts";
 import { readShellFiles, runsMutation, within, type Run } from "./mutation-job.ts";
 import { invokes, mentions, plainCommand, type Command } from "./shell-command.ts";
+import { findMissingWorkflows, formatMissingReport, isRecord, names, workflowJobs, type Workflow } from "./workflow-references.ts";
+
+export { FLEET_BUN_VERSION, findBunPinFaults, formatBunPinReport } from "./bun-pin.ts";
+export type { BunPinFault, BunPinPolicy } from "./bun-pin.ts";
 
 export type { Command };
 
@@ -20,11 +25,6 @@ export type Declaration = {
   readonly lintGates: readonly KitGate[];
 };
 
-export type Workflow = {
-  readonly path: string;
-  readonly document: unknown;
-};
-
 export type BlockedInvocation = {
   readonly location: string;
   readonly blocker: string;
@@ -84,16 +84,6 @@ const MUTATION_RUNNER = ["self-hosted", "Linux", "X64", "winbox"];
 const HOSTED_DEFAULT = "${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}";
 const EventRepository = Schema.fromJsonString(Schema.Struct({ repository: Schema.Struct({ private: Schema.Boolean }) }));
 
-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 constant(value: unknown): boolean | undefined {
   if (typeof value === "boolean") return value;
   if (typeof value !== "string") return undefined;
@@ -311,11 +301,6 @@ function jobRuns(workflow: Workflow, job: Readonly<Record<string, unknown>>): re
   return steps.flatMap((step: unknown) => (isRecord(step) && typeof step["run"] === "string" ? [{ script: step["run"], dir: stepDirectory(step["working-directory"], dir) }] : []));
 }
 
-function workflowJobs(workflow: Workflow): readonly (readonly [string, Readonly<Record<string, unknown>>])[] {
-  const jobs = isRecord(workflow.document) ? workflow.document["jobs"] : undefined;
-  return isRecord(jobs) ? Object.entries(jobs).flatMap(([id, job]) => (isRecord(job) ? [[id, job] as const] : [])) : [];
-}
-
 export function findRunnerFaults(policy: RunnerPolicy, workflows: readonly Workflow[]): readonly RunnerFault[] {
   return workflows.flatMap((workflow) =>
     workflowJobs(workflow).flatMap(([id, job]) => {
@@ -333,7 +318,7 @@ export function formatRunnerReport(faults: readonly RunnerFault[]): string {
 
 export const parseWorkflow = (path: string, text: string): Effect.Effect<Workflow, WiringError> =>
   Effect.try({
-    try: () => ({ path, document: Bun.YAML.parse(text) }),
+    try: () => ({ path, document: Bun.YAML.parse(text), text }),
     catch: (error) => new WiringError({ message: `cannot parse ${path}: ${String(error)}` }),
   });
 
@@ -386,11 +371,15 @@ const wiring = Effect.gen(function* () {
   const gaps = findGaps(declaration, workflows);
   const gapReport = formatReport(declaration, gaps);
   yield* gaps.length > 0 ? Console.error(gapReport) : Console.log(gapReport);
+  const missing = findMissingWorkflows(workflows);
+  if (missing.length > 0) yield* Console.error(formatMissingReport(missing));
   const scripts = yield* readScripts(root);
   const runs = workflows.flatMap((workflow) => workflowJobs(workflow).flatMap(([, job]) => jobRuns(workflow, job)));
   const faults = findRunnerFaults({ visibility: yield* readVisibility, scripts, files: yield* readShellFiles(root, scripts, runs) }, workflows);
   if (faults.length > 0) yield* Console.error(formatRunnerReport(faults));
-  return gaps.length === 0 && faults.length === 0;
+  const bunFaults = findBunPinFaults(yield* readBunPinPolicy(root, workflows), workflows);
+  if (bunFaults.length > 0) yield* Console.error(formatBunPinReport(bunFaults));
+  return gaps.length === 0 && faults.length === 0 && missing.length === 0 && bunFaults.length === 0;
 });
 
 if (import.meta.main) runMain("ci-wiring", wiring);

package/src/delivery/workflow-references.ts

@@ -0,0 +1,203 @@
+import { fromProgram, shellCommands, type Command } from "./shell-command.ts";
+
+export type Workflow = {
+  readonly path: string;
+  readonly document: unknown;
+  readonly text: string;
+};
+
+export type MissingReference = {
+  readonly location: string;
+  readonly fault: string;
+};
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function workflowJobs(workflow: Workflow): readonly (readonly [string, Readonly<Record<string, unknown>>])[] {
+  const jobs = isRecord(workflow.document) ? workflow.document["jobs"] : undefined;
+  return isRecord(jobs) ? Object.entries(jobs).flatMap(([id, job]) => (isRecord(job) ? [[id, job] as const] : [])) : [];
+}
+
+export 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");
+}
+
+type Key = string | number;
+
+type Locator = (keys: readonly Key[], needle: string, fallback: string) => string;
+
+// Lines from..to hold the node, and its child keys start at column.
+type Node = { readonly from: number; readonly to: number; readonly column: number };
+
+const WORKFLOWS = ".github/workflows";
+const RELEASE_BINS = ["checks-release-pr", "checks-release-tag"];
+const RELEASE_SOURCES = ["release-pr.ts", "release-tag.ts"];
+const REUSABLE_PREFIX = "./.github/workflows/";
+// GitHub substitutes an expression into the script before the shell reads it.
+const EXPRESSION = /\$\{\{[\s\S]*?\}\}/g;
+
+function isPathTo(word: string, files: readonly string[]): boolean {
+  return files.some((file) => word.endsWith(`/${file}`));
+}
+
+function releaseArguments(program: Command): readonly string[] {
+  const [head, target] = program;
+  if (head !== undefined && (RELEASE_BINS.includes(head) || isPathTo(head, RELEASE_BINS))) return program.slice(1);
+  if (head === "bun" && target !== undefined && (RELEASE_SOURCES.includes(target) || isPathTo(target, [...RELEASE_SOURCES, ...RELEASE_BINS]))) {
+    return program.slice(2);
+  }
+  return [];
+}
+
+function literalTargets(run: string): readonly string[] {
+  return shellCommands(run.replace(EXPRESSION, "$EXPRESSION"))
+    .flatMap((command) => releaseArguments(fromProgram(command)))
+    .filter((target) => !target.includes("$"));
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function indentOf(line: string): number {
+  return line.length - line.trimStart().length;
+}
+
+function meaningful(line: string): boolean {
+  const text = line.trim();
+  return text !== "" && !text.startsWith("#");
+}
+
+function belongs(line: string, column: number): boolean {
+  return !meaningful(line) || indentOf(line) > column || (indentOf(line) === column && line.trim().startsWith("-"));
+}
+
+function firstBodyLine(lines: readonly string[], from: number, to: number): string | undefined {
+  return lines.slice(from + 1, to).find(meaningful);
+}
+
+function child(lines: readonly string[], node: Node, key: string): Node | undefined {
+  const pattern = new RegExp(`^(\\s*(?:-\\s+)?)["']?${escapeRegExp(key)}["']?\\s*:(\\s|$)`);
+  for (let at = node.from; at < node.to; at += 1) {
+    if (pattern.exec(lines[at] ?? "")?.[1]?.length !== node.column) continue;
+    let to = at + 1;
+    while (to < node.to && belongs(lines[to] ?? "", node.column)) to += 1;
+    const body = firstBodyLine(lines, at, to);
+    return { from: at, to, column: body === undefined ? -1 : indentOf(body) };
+  }
+  return undefined;
+}
+
+function items(lines: readonly string[], node: Node): readonly Node[] {
+  const column = indentOf(firstBodyLine(lines, node.from, node.to) ?? "");
+  const starts: number[] = [];
+  for (let at = node.from + 1; at < node.to; at += 1) {
+    const line = lines[at] ?? "";
+    if (meaningful(line) && indentOf(line) === column && line.trim().startsWith("-")) starts.push(at);
+  }
+  return starts.map((from, index) => {
+    const to = starts[index + 1] ?? node.to;
+    const inline = /^\s*-\s+(?=\S)/.exec(lines[from] ?? "");
+    return { from, to, column: inline === null ? indentOf(firstBodyLine(lines, from, to) ?? "") : inline[0].length };
+  });
+}
+
+function nodeAt(lines: readonly string[], keys: readonly Key[]): Node | undefined {
+  return keys.reduce<Node | undefined>(
+    (node, key) => (node === undefined ? undefined : typeof key === "number" ? items(lines, node)[key] : child(lines, node, key)),
+    { from: 0, to: lines.length, column: 0 },
+  );
+}
+
+export function locate(path: string, lines: readonly string[]): Locator {
+  const used = new Map<string, number>();
+  return (keys, needle, fallback) => {
+    const node = nodeAt(lines, keys);
+    if (node === undefined) return `${path} ${fallback}`;
+    const hits = lines.slice(node.from, node.to).flatMap((line, offset) => (line.includes(needle) ? [node.from + offset] : []));
+    const at = hits.find((line) => line > (used.get(needle) ?? -1)) ?? hits[0] ?? node.from;
+    used.set(needle, at);
+    return `${path} line ${at + 1}`;
+  };
+}
+
+function workflowTitle(document: unknown): string | undefined {
+  return isRecord(document) && typeof document["name"] === "string" ? document["name"] : undefined;
+}
+
+function missingNeeds(jobs: Readonly<Record<string, unknown>>, at: Locator): readonly MissingReference[] {
+  return Object.entries(jobs).flatMap(([id, job]) => {
+    if (!isRecord(job)) return [];
+    return (names(job["needs"]) ?? []).flatMap((need) =>
+      need in jobs ? [] : [{ location: at(["jobs", id, "needs"], need, `job ${id}`), fault: `job ${id} needs missing job ${need}` }],
+    );
+  });
+}
+
+function missingTarget(uses: string, paths: ReadonlySet<string>, at: Locator, keys: readonly Key[], fallback: string): MissingReference | undefined {
+  return uses.startsWith(REUSABLE_PREFIX) && !paths.has(uses.slice(2))
+    ? { location: at(keys, uses, fallback), fault: `names missing workflow ${uses.slice(2)}` }
+    : undefined;
+}
+
+function missingJobRefs(id: string, job: unknown, paths: ReadonlySet<string>, at: Locator): readonly MissingReference[] {
+  if (!isRecord(job)) return [];
+  const missing: MissingReference[] = [];
+  if (typeof job["uses"] === "string") {
+    const called = missingTarget(job["uses"], paths, at, ["jobs", id, "uses"], `job ${id}`);
+    if (called !== undefined) missing.push(called);
+  }
+  const steps = job["steps"];
+  if (!Array.isArray(steps)) return missing;
+  steps.forEach((step: unknown, index) => {
+    if (!isRecord(step)) return;
+    const fallback = `job ${id} step ${index + 1}`;
+    if (typeof step["uses"] === "string") {
+      const used = missingTarget(step["uses"], paths, at, ["jobs", id, "steps", index, "uses"], fallback);
+      if (used !== undefined) missing.push(used);
+    }
+    if (typeof step["run"] !== "string") return;
+    for (const target of literalTargets(step["run"])) {
+      if (!paths.has(`${WORKFLOWS}/${target}`)) {
+        missing.push({ location: at(["jobs", id, "steps", index, "run"], target, fallback), fault: `names missing workflow ${target}` });
+      }
+    }
+  });
+  return missing;
+}
+
+// GitHub names a workflow without a name by its path from the repository root.
+export function findMissingWorkflows(workflows: readonly Workflow[]): readonly MissingReference[] {
+  const paths = new Set(workflows.map((workflow) => workflow.path));
+  const titles = new Set(workflows.map((workflow) => workflowTitle(workflow.document) ?? workflow.path));
+  return workflows.flatMap((workflow) => {
+    const missing: MissingReference[] = [];
+    const at = locate(workflow.path, workflow.text.split("\n"));
+    const jobs = isRecord(workflow.document) ? workflow.document["jobs"] : undefined;
+    if (isRecord(jobs)) {
+      missing.push(...missingNeeds(jobs, at));
+      for (const [id, job] of Object.entries(jobs)) missing.push(...missingJobRefs(id, job, paths, at));
+    }
+    const on = isRecord(workflow.document) ? workflow.document["on"] : undefined;
+    const watched = isRecord(on) ? on["workflow_run"] : undefined;
+    if (isRecord(watched)) {
+      for (const entry of names(watched["workflows"]) ?? []) {
+        if (!titles.has(entry)) {
+          missing.push({ location: at(["on", "workflow_run", "workflows"], entry, "on workflow_run"), fault: `names missing workflow ${entry}` });
+        }
+      }
+    }
+    return missing;
+  });
+}
+
+export function formatMissingReport(faults: readonly MissingReference[]): string {
+  return [
+    `ci-wiring: ${faults.length} reference(s) name a missing workflow or job:`,
+    ...faults.map(({ location, fault }) => `  ${location}: ${fault}`),
+  ].join("\n");
+}