@avi2dg/checks 0.53.0 → 0.54.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.54.0
+
+Released 2026-10-27.
+
+### Features
+
+- **delivery:** fail fast when the release cannot run [#8](https://github.com/avi2d/checks/pull/8)
+
 ## 0.53.0
 
 Released 2026-10-26.

package/docs/bins.md

@@ -52,6 +52,7 @@ These bins run on their own:
 - [`checks-release-notes`](gates/checks-release-notes.md) writes one `CHANGELOG.md` section to a file for a GitHub release.
 - [`checks-release-report`](gates/checks-release-report.md) tells whether the history holds unreleased features or fixes since the last tag.
 - [`checks-release-pr`](gates/checks-release-pr.md) opens or refreshes the pull request that releases the next version, and dispatches its checks.
+- [`checks-release-preflight`](gates/checks-release-preflight.md) refuses the release before it starts when the version disagrees with the last tag or the run lacks the trusted publisher prerequisites.
 - [`checks-release-publish`](gates/checks-release-publish.md) publishes the version `package.json` holds to npm, unless npm already holds it or a newer version.
 - [`checks-release-push`](gates/checks-release-push.md) releases a package's next version onto its branch once the checks pass, tags it and dispatches the release workflow on the tag.
 - [`checks-release-tag`](gates/checks-release-tag.md) tags a landed release commit with its version and dispatches the release workflow on the tag.

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

@@ -60,7 +60,22 @@ permissions:
   contents: read
   id-token: write
 jobs:
+  preflight:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
+      - run: bun install --frozen-lockfile
+      - name: fail fast when the release cannot run
+        run: ./node_modules/.bin/checks-release-preflight release.yml
   publish:
+    needs: preflight
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
@@ -113,7 +128,22 @@ on:
 permissions:
   contents: read
 jobs:
+  preflight:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
+      - run: bun install --frozen-lockfile
+      - name: fail fast when the release cannot run
+        run: ./node_modules/.bin/checks-release-preflight release.yml
   github-release:
+    needs: preflight
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -139,6 +169,9 @@ jobs:
         run: gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file "$RUNNER_TEMP/release-notes.md"
 ```
 
+A `preflight` job runs `checks-release-preflight` before the publish step, so a release whose version disagrees with the last tag or whose run lacks the trusted publisher prerequisites fails before the build.
+An untagged bump also fails earlier, since `checks-release-pr` and `checks-release-push` refuse to plan a release the last tag does not name.
+The approval setting has no read only check under the release token, so `checks-release-pr` fails while opening the pull request when the setting is off.
 A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}` on each job in either workflow, as [checks-ci-wiring](checks-ci-wiring.md#runners) requires.
 A release is one commit that holds only the version bump and the built changelog.
 A package repository lands it on every push to `main` through [checks-release-push](checks-release-push.md), which tags it and dispatches this workflow on the tag.

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

@@ -116,6 +116,8 @@ jobs:
         with:
           bun-version-file: .bun-version
       - run: bun install --frozen-lockfile
+      - name: fail fast when the release cannot plan
+        run: ./node_modules/.bin/checks-release-preflight release.yml
       - name: open or refresh the release pull request
         env:
           GH_TOKEN: ${{ github.token }}
@@ -141,6 +143,7 @@ jobs:
         run: ./node_modules/.bin/checks-release-tag release.yml
 ```
 
+The `pull-request` job runs `checks-release-preflight` before planning, so a version the last tag does not name fails before `checks-release-pr` builds.
 A public repository keeps `runs-on: ubuntu-latest`.
 A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}` on both jobs, as [checks-ci-wiring](checks-ci-wiring.md#runners) requires of every job but a mutation job.
 A repository whose build needs more than Bun adds the steps its `.github/workflows/ci.yml` runs before `bun run build` to both jobs, and nothing after it.

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

@@ -0,0 +1,94 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-release-preflight
+
+`checks-release-preflight` fails a release fast when local checks rule it out.
+A version the last tag does not name and a run missing the trusted publisher prerequisites fail before the build.
+A wrong trusted publisher setting on npm itself surfaces only at the publish step, through the publish refusal.
+
+## What it checks
+
+It reads the version `package.json` holds and the last `v*` tag.
+It refuses when the last tag names another version, since an untagged bump means a release landed that nothing published.
+It reads the release workflow its argument names.
+A workflow that publishes nothing to npm needs no trusted publisher, so that check passes it without reading the repository.
+Only a step whose run command invokes the publish counts as publishing.
+A comment, a job name or any other text that names the publish never counts.
+When the workflow publishes to npm, it compares the repository `package.json` names with the repository the run is in.
+It refuses when the two differ, since the run then cannot present the trusted publisher npm holds.
+It refuses when a publishing job holds no `id-token: write`, since the run then mints no OIDC token for the trusted publisher npm holds.
+A job with its own permissions replaces the workflow permissions, so a workflow grant alone never passes a publishing job that lists its own permissions without the token, and a grant on another job never passes the publishing job.
+The bin checks these prerequisites from local files only.
+The trusted publisher setting itself cannot be verified without an npm credential, so a wrong setting surfaces at the publish step through the publish refusal.
+
+## What it reads
+
+It reads `package.json` and `.github/workflows/<workflow>` from the checkout.
+It reads the `v*` tags from the checkout, so the checkout fetches the whole history.
+It reads the run repository from `GITHUB_REPOSITORY`.
+It makes no network call and takes no token.
+
+## Arguments
+
+```sh
+checks-release-preflight <workflow>
+```
+
+The argument names the release workflow file under `.github/workflows/`, such as `release.yml`.
+
+## Exit codes
+
+| Code | Result |
+| --- | --- |
+| 0 | Every check passes. |
+| 2 | The arguments do not parse, a check refuses the release, or a read fails. |
+
+## Sample output
+
+A release that agrees on every check prints two lines.
+
+```text
+release-preflight: package.json holds 0.4.0, which matches v0.4.0
+release-preflight: package.json names acme/widget and release.yml grants the publishing job id-token: write, so the run holds the prerequisites for npm's trusted publisher for @acme/widget
+```
+
+A manifest bumped past the last tag refuses with the fix.
+
+```text
+checks-release-preflight: package.json holds 0.7.0, but the last release tag is v0.6.0, so v0.7.0 is untagged; rerun the release that bumped it, whose refusal says what to fix, or return package.json to 0.6.0
+```
+
+A run in another repository than the manifest names refuses with both sides.
+
+```text
+checks-release-preflight: package.json names the repository other/widget, but the run is in acme/widget, so the run cannot present npm's trusted publisher for @acme/widget; point repository.url at acme/widget, the repository the run publishes from
+```
+
+A publishing job with no token refuses with where to grant it.
+
+```text
+checks-release-preflight: .github/workflows/release.yml grants the publishing job no id-token: write, so the run mints no OIDC token for npm's trusted publisher; grant id-token: write where the release job runs
+```
+
+## When it runs
+
+The release planning boundary runs it before `checks-release-pr` plans and before `checks-release-push` plans a new release, and the `preflight` job of the release workflow keeps it as the prerequisite of the job that publishes.
+A checkout whose `HEAD` already holds the release commit skips it, so `checks-release-push` recovers the missing tag.
+A version the last tag does not name and a run missing the trusted publisher prerequisites then fail before the build, the lint, the typecheck and the suite.
+A wrong trusted publisher setting on npm itself surfaces only at the publish step, through the publish refusal.
+
+## Operator check
+
+No endpoint the release token may read exposes the approval setting, so the bin never checks it.
+Turn on **Allow GitHub Actions to create and approve pull requests** under the repository Actions settings before the daily release plans.
+`checks-release-pr` fails while opening the pull request when the setting is off.
+
+## Related topics
+
+- [checks-release-notes](checks-release-notes.md)
+- [checks-release-publish](checks-release-publish.md)
+- [checks-release-push](checks-release-push.md)
+- [checks-release-pr](checks-release-pr.md)
+- [checks-release-tag](checks-release-tag.md)

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

@@ -120,12 +120,21 @@ jobs:
         with:
           bun-version-file: .bun-version
       - run: bun install --frozen-lockfile
+      - name: fail fast when the release cannot plan
+        run: |
+          if git log -1 --format=%s HEAD | grep -qE '^chore: release [0-9]+\.[0-9]+\.[0-9]+( \(#[0-9]+\))?$'; then
+            echo "HEAD already holds the release commit, so release-push recovers its tag instead of planning"
+          else
+            ./node_modules/.bin/checks-release-preflight release.yml
+          fi
       - name: release what main holds once its checks pass
         env:
           GH_TOKEN: ${{ github.token }}
         run: ./node_modules/.bin/checks-release-push release.yml ci.yml
 ```
 
+The step before it runs `checks-release-preflight`, so a run missing the trusted publisher prerequisites fails before planning.
+A checkout whose `HEAD` already holds the release commit skips that step, so a rerun after a failed tag push recovers the tag.
 The push the workflow token makes starts no run, so landing the release commit never starts the workflow again.
 The concurrency group holds from reading the branch until the release workflow it dispatched finishes, so releases cut by release-push publish one at a time, and a queued run the group cancels had cut nothing.
 That hold ends early in two cases.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "author": {
     "name": "avi2d",
@@ -41,6 +41,7 @@
     "src/delivery/release.ts",
     "src/delivery/release-commit.ts",
     "src/delivery/release-pr.ts",
+    "src/delivery/release-preflight.ts",
     "src/delivery/release-publish.ts",
     "src/delivery/release-push.ts",
     "src/delivery/release-tag.ts",
@@ -164,6 +165,7 @@
     "checks-release-notes": "src/delivery/release-notes.ts",
     "checks-release-report": "src/delivery/release-report.ts",
     "checks-release-pr": "src/delivery/release-pr.ts",
+    "checks-release-preflight": "src/delivery/release-preflight.ts",
     "checks-release-publish": "src/delivery/release-publish.ts",
     "checks-release-push": "src/delivery/release-push.ts",
     "checks-release-tag": "src/delivery/release-tag.ts",

package/src/delivery/release-preflight.ts

@@ -0,0 +1,177 @@
+#!/usr/bin/env bun
+import { Config, Console, Effect, FileSystem, Option, Path, Schema } from "effect";
+import { lastTag } from "./release.ts";
+import { refused } from "./release-commit.ts";
+import { fromProgram, shellWords, type Command } from "./shell-command.ts";
+import { git } from "../core/git.ts";
+import { runMain, Usage } from "../core/main.ts";
+
+const LABEL = "release-preflight";
+const USAGE = "usage: release-preflight.ts <release-workflow>";
+const MANIFEST = "package.json";
+const WORKFLOWS = ".github/workflows";
+
+const Manifest = Schema.Struct({
+  name: Schema.String,
+  version: Schema.String,
+  repository: Schema.optional(Schema.Union([Schema.String, Schema.Struct({ url: Schema.optional(Schema.String) })])),
+});
+
+const decodeManifest = Schema.decodeUnknownEffect(Schema.fromJsonString(Manifest));
+
+const GITHUB_HTTPS = /^(?:git\+)?https:\/\/github\.com\/([^/]+?)\/([^/]+?)(?:\.git)?\/?$/;
+const GITHUB_SCP = /^git@github\.com:([^/]+?)\/([^/]+?)(?:\.git)?\/?$/;
+
+export function ownerRepoOf(url: string): string | undefined {
+  const match = GITHUB_HTTPS.exec(url) ?? GITHUB_SCP.exec(url);
+  return match === null ? undefined : `${match[1]}/${match[2]}`;
+}
+
+const PUBLISH_BINS = ["checks-release-publish"];
+const PUBLISH_SOURCES = ["release-publish.ts"];
+
+function isPublishPath(word: string, files: readonly string[]): boolean {
+  return files.some((file) => word === file || word.endsWith(`/${file}`));
+}
+
+function publishesInvocation(words: Command): boolean {
+  const [head = "", ...rest] = fromProgram(words);
+  if (head === "npm" && rest[0] === "publish") return true;
+  if (isPublishPath(head, PUBLISH_BINS)) return true;
+  return head === "bun" && rest.some((word) => isPublishPath(word, PUBLISH_SOURCES));
+}
+
+export function publishesToNpm(command: string): boolean {
+  return shellWords(command).some((words) => publishesInvocation(words.map(({ text }) => text)));
+}
+
+const FlexiblePermissions = Schema.Union([Schema.String, Schema.Record(Schema.String, Schema.Unknown)]);
+type FlexiblePermissions = typeof FlexiblePermissions.Type;
+
+const WorkflowDocument = Schema.Struct({
+  permissions: Schema.optional(FlexiblePermissions),
+  jobs: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+});
+const StepDocument = Schema.Struct({ run: Schema.optional(Schema.String) });
+const JobDocument = Schema.Struct({
+  permissions: Schema.optional(FlexiblePermissions),
+  steps: Schema.optional(Schema.Array(Schema.Unknown)),
+});
+
+const decodeDocument = Schema.decodeUnknownOption(WorkflowDocument);
+const decodeJob = Schema.decodeUnknownOption(JobDocument);
+const decodeStep = Schema.decodeUnknownOption(StepDocument);
+
+function grantsOidcValue(permissions: FlexiblePermissions | undefined): boolean {
+  return permissions === "write-all" || (typeof permissions === "object" && permissions["id-token"] === "write");
+}
+
+function runsOf(job: unknown): string[] {
+  const decoded = decodeJob(job);
+  if (Option.isNone(decoded) || decoded.value.steps === undefined) return [];
+  return decoded.value.steps.flatMap((step) => {
+    const decodedStep = decodeStep(step);
+    return Option.isNone(decodedStep) || decodedStep.value.run === undefined ? [] : [decodedStep.value.run];
+  });
+}
+
+function jobPublishes(job: unknown): boolean {
+  return runsOf(job).some(publishesToNpm);
+}
+
+function documentPublishes(document: unknown): boolean {
+  const decoded = decodeDocument(document);
+  if (Option.isNone(decoded) || decoded.value.jobs === undefined) return false;
+  return Object.values(decoded.value.jobs).some(jobPublishes);
+}
+
+export function grantsOidc(document: unknown): boolean {
+  const decoded = decodeDocument(document);
+  if (Option.isNone(decoded)) return false;
+  const jobs = decoded.value.jobs;
+  if (jobs === undefined) return false;
+  const publishing = Object.values(jobs).filter(jobPublishes);
+  if (publishing.length === 0) return false;
+  return publishing.every((job) => {
+    const decodedJob = decodeJob(job);
+    if (Option.isNone(decodedJob)) return false;
+    const own = decodedJob.value.permissions;
+    return grantsOidcValue(own === undefined ? decoded.value.permissions : own);
+  });
+}
+
+const readManifest = Effect.fn("readManifest")(function* (root: string) {
+  const file = (yield* Path.Path).join(root, MANIFEST);
+  return yield* (yield* FileSystem.FileSystem).readFileString(file).pipe(
+    Effect.flatMap(decodeManifest),
+    Effect.mapError((cause) => refused(`${MANIFEST}: ${cause.message}`)),
+  );
+});
+
+const checkTag = Effect.fn("checkTag")(function* (root: string) {
+  if ((yield* git(["rev-parse", "--is-shallow-repository"], root)).trim() === "true") {
+    return yield* refused("the checkout is shallow, so the tag it sees may not be the last one; fetch all of it");
+  }
+  const { version } = yield* readManifest(root);
+  const since = yield* lastTag(root);
+  if (since !== undefined && since !== `v${version}`) {
+    return yield* refused(
+      `${MANIFEST} holds ${version}, but the last release tag is ${since}, so v${version} is untagged; rerun the release that bumped it, whose refusal says what to fix, or return ${MANIFEST} to ${since.slice(1)}`,
+    );
+  }
+  yield* Console.log(`${LABEL}: ${MANIFEST} holds ${version}, which ${since === undefined ? "has no release tag yet" : `matches ${since}`}`);
+});
+
+const checkPublisher = Effect.fn("checkPublisher")(function* (root: string, workflow: string) {
+  const path = (yield* Path.Path).join(root, WORKFLOWS, workflow);
+  const text = yield* (yield* FileSystem.FileSystem).readFileString(path).pipe(
+    Effect.mapError(() => refused(`${WORKFLOWS}/${workflow} is missing, so the run cannot show the prerequisites npm's trusted publisher needs`)),
+  );
+  const document = yield* Effect.try({
+    try: () => Bun.YAML.parse(text),
+    catch: () => refused(`${WORKFLOWS}/${workflow} does not parse, so the run cannot show the prerequisites npm's trusted publisher needs`),
+  });
+  if (!documentPublishes(document)) {
+    yield* Console.log(`${LABEL}: ${workflow} publishes nothing to npm, so no trusted publisher has to match`);
+    return;
+  }
+  const repository = yield* Config.String("GITHUB_REPOSITORY").pipe(Config.withDefault(""));
+  if (repository === "") return yield* refused("GITHUB_REPOSITORY is not set, so the run has no repository to match; run this in the release workflow");
+  const { name, repository: field } = yield* readManifest(root);
+  const raw = typeof field === "string" ? field : field?.url;
+  if (raw === undefined) {
+    return yield* refused(
+      `${MANIFEST} has no repository, so the run holds no repository for npm's trusted publisher to allow; point repository.url at ${repository}`,
+    );
+  }
+  const held = ownerRepoOf(raw);
+  if (held === undefined) {
+    return yield* refused(
+      `${MANIFEST} names the repository ${raw}, which is no GitHub owner and name, so the run holds no repository for npm's trusted publisher to allow; point repository.url at ${repository}`,
+    );
+  }
+  if (held.toLowerCase() !== repository.toLowerCase()) {
+    return yield* refused(
+      `${MANIFEST} names the repository ${held}, but the run is in ${repository}, so the run cannot present npm's trusted publisher for ${name}; point repository.url at ${repository}, the repository the run publishes from`,
+    );
+  }
+  if (!grantsOidc(document)) {
+    return yield* refused(
+      `${WORKFLOWS}/${workflow} grants the publishing job no id-token: write, so the run mints no OIDC token for npm's trusted publisher; grant id-token: write where the release job runs`,
+    );
+  }
+  yield* Console.log(
+    `${LABEL}: ${MANIFEST} names ${repository} and ${workflow} grants the publishing job id-token: write, so the run holds the prerequisites for npm's trusted publisher for ${name}`,
+  );
+});
+
+const releasePreflight = Effect.gen(function* () {
+  const [workflow, ...extra] = process.argv.slice(2);
+  if (workflow === undefined || extra.length > 0) return yield* new Usage({ message: USAGE });
+  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
+  yield* checkTag(root);
+  yield* checkPublisher(root, workflow);
+  return true;
+});
+
+if (import.meta.main) runMain("checks-release-preflight", releasePreflight);