@avi2dg/checks 0.66.0 → 0.68.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.68.0
+
+Released 2026-11-06.
+
+### Features
+
+- **ci-wiring:** accept short shared refs for runner pick and setup [#49](https://github.com/avi2d/checks/pull/49)
+
+## 0.67.0
+
+Released 2026-11-06.
+
+### Features
+
+- **ci-wiring:** accept shared runner pick and setup action [#48](https://github.com/avi2d/checks/pull/48)
+
 ## 0.66.0
 
 Released 2026-11-05.

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

@@ -68,6 +68,11 @@ Any other expression refuses as unresolvable.
 A job on `push` or another trigger no fork reaches may still name self-hosted labels.
 In a private repository each mutation job carries exactly the labels the consumer declares in `package.json` under `checks.mutationRunner`.
 Every other job there carries exactly the hosted-default expression, or exactly one of the label sets the consumer declares under `checks.selfHostedRunners`.
+A job there also carries `runs-on: ${{ needs.<job>.outputs.runs-on }}` when the same workflow needs that job and that job calls the runner pick.
+The pick is the repository file `runner.yml` under `.github/workflows/` or `avi2d/workflows/.github/workflows/runner.yml` at a full SHA or at a version tag, `v<major>` or `v<major>.<minor>.<patch>`.
+A branch name or a missing ref is not the pick.
+A public repository still refuses that expression on a job a fork can reach.
+The resolved label cannot be shown to be a hosted runner before the run.
 A repository without those declarations fails each job they would pin until it declares them.
 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.
 
@@ -90,7 +95,9 @@ The fleet version is the version the kit ships in its own `.bun-version`.
 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.
+A step that uses `avi2d/workflows/setup` or `avi2d/workflows/actions/setup`, at any ref or none, reads `.bun-version`.
+The step fails the check when `.bun-version` is missing or differs from the fleet bun version.
+This rule skips a repository with no setup-bun step and no shared setup step.
 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.
 
@@ -133,8 +140,10 @@ Each refusal names the workflow file, the job and the limit.
 ## What it reads
 
 The bin reads `.github/workflows/*.yml`, `*.yaml`, the `scripts`, `private` and `checks` runners in `package.json` and the shell scripts those steps and scripts run from the working tree.
+It reads each shell script that a shell script it reads runs, until none is left.
 It lists the `*.ts` and `*.tsx` files `git ls-files` tracks to decide whether the night run applies.
 It reads each file a setup-bun step names for its version.
+It reads `.bun-version` for each step that uses the shared setup action.
 It reads the fleet pin from the kit's own `.bun-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.
@@ -149,7 +158,7 @@ It takes no arguments.
 | Code | Result |
 | --- | --- |
 | 0 | Every required command has a reachable step. |
-| 1 | A required command is missing or blocked, a job runs on the wrong runner, a workflow names a missing workflow or job, a setup-bun step drifts from the fleet bun version, a workflow that releases runs on a schedule outside a public npm package or more than once a day, a workflow other than a weekly public advisory scan runs on a schedule, a job can run for more than 60 minutes, or a repository that tracks TypeScript never runs `checks-lint --night`. |
+| 1 | A required command is missing or blocked, a job runs on the wrong runner, a workflow names a missing workflow or job, a bun setup step drifts from the fleet bun version, a workflow that releases runs on a schedule outside a public npm package or more than once a day, a workflow other than a weekly public advisory scan runs on a schedule, a job can run for more than 60 minutes, or a repository that tracks TypeScript never runs `checks-lint --night`. |
 | 2 | A workflow or `package.json` cannot be decoded, or the kit's own `.bun-version` is missing, unreadable or blank. |
 
 ## Sample output

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.66.0",
+  "version": "0.68.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "author": {
     "name": "avi2d",
@@ -81,6 +81,7 @@
     "src/delivery/mutation-job.ts",
     "src/delivery/job-timeout.ts",
     "src/delivery/runner-policy.ts",
+    "src/delivery/runner-pick.ts",
     "src/delivery/secrets.ts",
     "src/delivery/secrets-pack.ts",
     "src/delivery/pr-text.ts",

package/src/delivery/bun-pin.ts

@@ -17,12 +17,19 @@ export type BunPinFault = {
 
 const SETUP_BUN = /^oven-sh\/setup-bun(?:@(?<ref>.*))?$/i;
 const V2_REF = /^v2(?:\.\d+){0,2}$/;
+const SHARED_SETUP = /^avi2d\/workflows\/(?:actions\/)?setup(?:@.*)?$/i;
+const SETUP_VERSION_FILE = ".bun-version";
 
 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 sharedSetupUses(uses: unknown): string | undefined {
+  const text = typeof uses === "string" ? uses.trim() : "";
+  return SHARED_SETUP.test(text) ? text : undefined;
+}
+
 function isExpression(value: string): boolean {
   return value.includes("${{");
 }
@@ -106,6 +113,14 @@ 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`;
 }
 
+function sharedSetupFault(policy: BunPinPolicy, uses: string): string | undefined {
+  const version = nonEmpty(policy.files.get(SETUP_VERSION_FILE));
+  if (version === undefined) {
+    return `uses ${uses}, which reads ${SETUP_VERSION_FILE}, but the repository holds no ${SETUP_VERSION_FILE} file, want ${policy.fleet}`;
+  }
+  return version === policy.fleet ? undefined : `requests bun ${version} from ${SETUP_VERSION_FILE}, want ${policy.fleet}`;
+}
+
 export function findBunPinFaults(policy: BunPinPolicy, workflows: readonly Workflow[]): readonly BunPinFault[] {
   return workflows.flatMap((workflow) => {
     const at = locate(workflow.path, workflow.text.split("\n"));
@@ -113,17 +128,25 @@ export function findBunPinFaults(policy: BunPinPolicy, workflows: readonly Workf
       const steps = Array.isArray(job["steps"]) ? job["steps"] : [];
       return steps.flatMap((step: unknown, index: number) => {
         if (!isRecord(step)) return [];
+        const atStep = (fault: string) => [
+          { location: at(["jobs", id, "steps", index, "uses"], String(step["uses"]), `job ${id} step ${index + 1}`), fault },
+        ];
         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 }];
+        if (ref !== undefined) {
+          const fault = V2_REF.test(ref) ? bunPinFault(policy, step) : unknownRefFault(ref);
+          return fault === undefined ? [] : atStep(fault);
+        }
+        const sharedUses = sharedSetupUses(step["uses"]);
+        if (sharedUses === undefined) return [];
+        const fault = sharedSetupFault(policy, sharedUses);
+        return fault === undefined ? [] : atStep(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");
+  return [`ci-wiring: ${faults.length} bun setup 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[] {
@@ -139,11 +162,17 @@ function versionFileKeys(job: Readonly<Record<string, unknown>>): readonly strin
   return keys;
 }
 
+function usesSharedSetup(job: Readonly<Record<string, unknown>>): boolean {
+  const steps = Array.isArray(job["steps"]) ? job["steps"] : [];
+  return steps.some((step) => isRecord(step) && sharedSetupUses(step["uses"]) !== undefined);
+}
+
 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);
+      if (usesSharedSetup(job)) wanted.add(SETUP_VERSION_FILE);
     }
   }
   return wanted;

package/src/delivery/runner-pick.ts

@@ -0,0 +1,29 @@
+import { names, type Workflow } from "./workflow-references.ts";
+
+const NEEDS_RUNS_ON = /^\$\{\{\s*needs\.([\w-]+)\.outputs\.runs-on\s*\}\}$/i;
+const SHARED_RUNNER = /^[Aa][Vv][Ii]2[Dd]\/[Ww][Oo][Rr][Kk][Ff][Ll][Oo][Ww][Ss]\/\.github\/workflows\/runner\.yml@(?:[0-9a-fA-F]{40}|v\d+(?:\.\d+\.\d+)?)$/;
+const LOCAL_RUNNER = ".github/workflows/runner.yml";
+
+function callsRunnerPick(uses: unknown, workflows: readonly Workflow[]): boolean {
+  if (typeof uses !== "string") return false;
+  const target = uses.trim();
+  if (target.startsWith("./")) {
+    const path = target.slice(2);
+    return path === LOCAL_RUNNER && workflows.some((workflow) => workflow.path === path);
+  }
+  return SHARED_RUNNER.test(target);
+}
+
+// GitHub fills needs.<job> only for jobs the current job needs.
+export function readsRunnerPick(
+  job: Readonly<Record<string, unknown>>,
+  runsOn: unknown,
+  jobs: ReadonlyMap<string, Readonly<Record<string, unknown>>>,
+  workflows: readonly Workflow[],
+): boolean {
+  if (typeof runsOn !== "string") return false;
+  const need = NEEDS_RUNS_ON.exec(runsOn.trim())?.[1];
+  if (need === undefined) return false;
+  if (!(names(job["needs"]) ?? []).includes(need)) return false;
+  return callsRunnerPick(jobs.get(need)?.["uses"], workflows);
+}

package/src/delivery/runner-policy.ts

@@ -1,5 +1,6 @@
 import { Effect, FileSystem, Path, Schema } from "effect";
 import { runsMutation, within, type Run } from "./mutation-job.ts";
+import { readsRunnerPick } from "./runner-pick.ts";
 import { isRecord, names, workflowJobs, workflowTitle, type Workflow } from "./workflow-references.ts";
 
 export type RunnerConfig = {
@@ -314,11 +315,20 @@ function watchedWorkflows(workflow: Workflow): readonly string[] {
   return isRecord(watched) ? (names(watched["workflows"]) ?? []) : [];
 }
 
-function runnerFault(job: Readonly<Record<string, unknown>>, runsOn: unknown, mutation: boolean, policy: RunnerPolicy, reachable: boolean): string | undefined {
+function runnerFault(
+  job: Readonly<Record<string, unknown>>,
+  runsOn: unknown,
+  mutation: boolean,
+  policy: RunnerPolicy,
+  reachable: boolean,
+  jobs: ReadonlyMap<string, Readonly<Record<string, unknown>>>,
+  workflows: readonly Workflow[],
+): string | undefined {
   if (policy.visibility === "public" && reachable) {
     const fault = publicFault(job, runsOn, policy.runners);
     if (fault !== undefined) return fault;
   }
+  if (readsRunnerPick(job, runsOn, jobs, workflows)) return undefined;
   return mutation ? mutationFault(runsOn, policy.runners.mutation, policy.visibility, reachable) : otherFault(runsOn, policy.runners, policy.visibility);
 }
 
@@ -359,14 +369,16 @@ export function findRunnerFaults(policy: RunnerPolicy, workflows: readonly Workf
       }
     }
   }
-  return workflows.flatMap((workflow) =>
-    workflowJobs(workflow).flatMap(([id, job]) => {
+  return workflows.flatMap((workflow) => {
+    const entries = workflowJobs(workflow);
+    const jobs = new Map(entries);
+    return entries.flatMap(([id, job]) => {
       if (job["runs-on"] === undefined) return [];
       const mutation = jobRuns(workflow, job).some((run) => runsMutation(run, policy.scripts, (file) => policy.files?.get(file)));
-      const fault = runnerFault(job, job["runs-on"], mutation, policy, reachable.get(workflow.path) ?? forkReachable(workflow));
+      const fault = runnerFault(job, job["runs-on"], mutation, policy, reachable.get(workflow.path) ?? forkReachable(workflow), jobs, workflows);
       return fault === undefined ? [] : [{ location: workflow.path + " job " + id, fault }];
-    }),
-  );
+    });
+  });
 }
 
 export function formatRunnerReport(faults: readonly RunnerFault[]): string {