@avi2dg/checks 0.22.0 → 0.24.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.24.0
+
+Released 2026-09-27.
+
+### Features
+
+- **scripts:** ship checks-changelog, checks-release-notes and checks-release-report bins [#77](https://github.com/avi2d/checks/pull/77)
+
+### Fixes
+
+- **scripts:** make checks-vendor re-freeze a cached tree whose owner write bit came back [#76](https://github.com/avi2d/checks/pull/76)
+
+## 0.23.0
+
+Released 2026-09-26.
+
+### Breaking changes
+
+- move cognitive-complexity into its own readability oxlint plugin [#74](https://github.com/avi2d/checks/pull/74)
+
 ## 0.22.0
 
 Released 2026-09-26.

package/CONTRIBUTING.md

@@ -26,8 +26,8 @@ Each generated file is committed, and lint, the suite or CI's diff after the bui
 
 To regenerate after an edit:
 
-1. After editing `effect-channel/` or the templates in `scripts/doc-templates.ts`, run `bun run build`.
-   It rewrites `dist/index.js` and `templates/`.
+1. After editing `effect-channel/`, `readability/` or the templates in `scripts/doc-templates.ts`, run `bun run build`.
+   It rewrites `dist/` and `templates/`.
 1. After editing anything a generated block names as its source in its opening marker, run `bun run build`, which rewrites every generated block.
 1. Commit what the command rewrote in the same commit as the edit.
 
@@ -68,8 +68,9 @@ To place a change:
    | Path | What it holds |
    | --- | --- |
    | `scripts/` | every bin, and the modules they share |
-   | `effect-channel/` | the oxlint plugin with the Effect error-channel and cognitive complexity rules |
-   | `dist/` | the committed oxlint plugin bundle |
+   | `effect-channel/` | the oxlint plugin with the Effect error-channel rules |
+   | `readability/` | the oxlint plugin with the readability rules |
+   | `dist/` | the committed oxlint plugin bundles |
    | `presets/` | the Effect rule blocks consumers copy into native configs |
    | `templates/` | one template per kind of doc file, which `bun run build` renders |
    | `CHANGELOG.md` | every release, which `bun run build` writes from the conventional commits |
@@ -83,7 +84,7 @@ To place a change:
    A new bin gets its page under `docs/gates/`, and the suite fails until it has one.
 
 This repository holds itself to the kit, with two exceptions of its own.
-Its `.dependency-cruiser.cjs` redeclares `no-orphans` with the plugin entry added to its `pathNot`.
+Its `.dependency-cruiser.cjs` redeclares `no-orphans` with each plugin entry added to its `pathNot`.
 Its `.oxlintrc.json` lifts `effect-channel/no-throw` from `scripts/comment-matchers.ts`, whose synchronous `refused()` a host loads without `node_modules`.
 
 ## Related topics

package/README.md

@@ -126,6 +126,9 @@ These bins run on their own:
 - [`checks-mutation-compare`](docs/gates/checks-mutation-compare.md) holds every mutant in a pull request to no regression.
 - [`checks-subsumed-tests`](docs/gates/checks-subsumed-tests.md) lists each test another test subsumes in a mutation run.
 - [`checks-backtest`](docs/gates/checks-backtest.md) reports what the comment check would have refused in recent history.
+- [`checks-changelog`](docs/gates/checks-changelog.md) writes the pending release into `CHANGELOG.md` from the conventional commits since the last release.
+- [`checks-release-notes`](docs/gates/checks-release-notes.md) writes one `CHANGELOG.md` section to a file for a GitHub release.
+- [`checks-release-report`](docs/gates/checks-release-report.md) tells whether the history holds unreleased features or fixes since the last tag.
 - [`checks-vendor`](docs/gates/checks-vendor.md) pins each library its `prepare` arguments name to a shared read-only clone and links it under `repos/`.
 
 `checks-lint` has [its own page](docs/gates/checks-lint.md), which says which range it resolves.
@@ -164,7 +167,7 @@ Every path is relative to the installed package, `node_modules/@avi2dg/checks/`.
 | `oxlintrc.json` | the oxlint base config `.oxlintrc.json` extends |
 | `stryker.preset.js` | the Stryker mutation-testing preset |
 | `tsconfig.effect.json` | the tsconfig fragment with the Effect language-service block |
-| `dist/` | the compiled oxlint plugin with the Effect error-channel and cognitive complexity rules |
+| `dist/` | the compiled oxlint plugins, one per purpose |
 
 <!-- end generated shipped -->
 

package/dist/effect-channel/index.js

@@ -0,0 +1,122 @@
+// effect-channel/no-error-channel-escape.ts
+var EFFECT_SOURCES = new Set(["effect", "effect/Effect"]);
+var INSTEAD = {
+  drops: "it drops the failure and the success together, so no caller can tell one from the other. Handle the error by tag, or keep it as a value with Effect.result or Effect.exit",
+  swallows: "a Cause is the typed error plus defects plus interruption, so this swallows the bugs and the cancellations along with it. Catch the errors you named, with Effect.catchTag or Effect.catchTags",
+  blind: "the handler cannot see what it is recovering from, so every error in the channel collapses into one fallback. Name the errors with Effect.catchTag, or take the error and use it"
+};
+var REFUSED = new Map([
+  ["ignore", INSTEAD.drops],
+  ["ignoreCause", INSTEAD.drops],
+  ["catchCause", INSTEAD.swallows],
+  ["catchCauseIf", INSTEAD.swallows],
+  ["catchCauseFilter", INSTEAD.swallows]
+]);
+var blindToTheError = (handler) => {
+  if (!handler)
+    return false;
+  if (handler.type !== "ArrowFunctionExpression" && handler.type !== "FunctionExpression")
+    return false;
+  return handler.params.every((param) => param.type === "Identifier" && /^_+$/.test(param.name));
+};
+var rule = {
+  meta: {
+    type: "problem",
+    docs: { description: "Disallow the combinators that erase Effect's error channel" }
+  },
+  create(context) {
+    const effect = new Set;
+    const named = (node) => {
+      if (!node || node.type !== "MemberExpression" || node.computed)
+        return null;
+      if (node.object.type !== "Identifier" || !effect.has(node.object.name))
+        return null;
+      return node.property.type === "Identifier" ? node.property.name : null;
+    };
+    const refuse = (node, combinator, instead) => {
+      context.report({ node, message: `Effect.${combinator} erases the error channel: ${instead}` });
+    };
+    return {
+      ImportDeclaration(node) {
+        if (!EFFECT_SOURCES.has(node.source.value))
+          return;
+        const module = node.source.value === "effect/Effect";
+        for (const specifier of node.specifiers) {
+          if (specifier.type === "ImportSpecifier") {
+            if (specifier.imported.type === "Identifier" && specifier.imported.name === "Effect")
+              effect.add(specifier.local.name);
+          } else if (module)
+            effect.add(specifier.local.name);
+        }
+      },
+      MemberExpression(node) {
+        const combinator = named(node);
+        if (combinator === null)
+          return;
+        const instead = REFUSED.get(combinator);
+        if (instead !== undefined)
+          refuse(node, combinator, instead);
+      },
+      CallExpression(node) {
+        if (named(node.callee) !== "catch")
+          return;
+        if (!blindToTheError(node.arguments[node.arguments.length - 1]))
+          return;
+        refuse(node, "catch", INSTEAD.blind);
+      }
+    };
+  }
+};
+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,
+    "no-throw": no_throw_default,
+    "no-try-catch": no_try_catch_default
+  }
+};
+var effect_channel_default = plugin;
+export {
+  effect_channel_default as default
+};

package/dist/{index.js → readability/index.js}

@@ -1,4 +1,4 @@
-// effect-channel/cognitive-nodes.ts
+// readability/cognitive-nodes.ts
 var CONTROL_TYPES = ["IfStatement", "ConditionalExpression", "SwitchStatement", "SwitchCase", "TryStatement", "CatchClause"];
 var LOOP_TYPES = ["ForStatement", "ForInStatement", "ForOfStatement", "WhileStatement", "DoWhileStatement", "LabeledStatement"];
 var CALL_TYPES = ["LogicalExpression", "BreakStatement", "ContinueStatement", "CallExpression", "NewExpression", "ImportExpression"];
@@ -7,7 +7,7 @@ var PLAIN_A_TYPES = ["BlockStatement", "ExpressionStatement", "ReturnStatement",
 var PLAIN_B_TYPES = ["ClassDeclaration", "ClassExpression", "ClassBody", "MethodDefinition", "TSAbstractMethodDefinition", "PropertyDefinition", "TSAbstractPropertyDefinition", "AccessorProperty", "TSAbstractAccessorProperty", "ObjectExpression", "ArrayExpression"];
 var PLAIN_C_TYPES = ["AwaitExpression", "UnaryExpression", "UpdateExpression", "SpreadElement", "YieldExpression", "BinaryExpression", "AssignmentExpression", "TSAsExpression", "TSSatisfiesExpression", "TSTypeAssertion", "TSNonNullExpression", "ChainExpression", "ParenthesizedExpression", "Decorator", "TSInstantiationExpression", "MemberExpression", "JSXMemberExpression", "TemplateLiteral", "TaggedTemplateExpression", "SequenceExpression", "JSXElement", "JSXFragment", "JSXOpeningElement", "JSXAttribute", "JSXExpressionContainer", "JSXSpreadChild", "JSXSpreadAttribute"];
 
-// effect-channel/cognitive-plain.ts
+// readability/cognitive-plain.ts
 function isControl(node) {
   return CONTROL_TYPES.includes(node.type);
 }
@@ -142,7 +142,7 @@ function plainChildrenC(node) {
   }
 }
 
-// effect-channel/cognitive.ts
+// readability/cognitive.ts
 function unreachable2(_value) {}
 function scoreList(state, nodes, nesting, parent) {
   for (const node of nodes) {
@@ -334,7 +334,7 @@ function cognitiveComplexity(root, names) {
   return state.recursive ? state.total + 1 : state.total;
 }
 
-// effect-channel/cognitive-complexity.ts
+// readability/cognitive-complexity.ts
 var DEFAULT_MAX = 15;
 function maxOf(options) {
   const [first] = options;
@@ -416,126 +416,14 @@ var rule = {
 };
 var cognitive_complexity_default = rule;
 
-// effect-channel/no-error-channel-escape.ts
-var EFFECT_SOURCES = new Set(["effect", "effect/Effect"]);
-var INSTEAD = {
-  drops: "it drops the failure and the success together, so no caller can tell one from the other. Handle the error by tag, or keep it as a value with Effect.result or Effect.exit",
-  swallows: "a Cause is the typed error plus defects plus interruption, so this swallows the bugs and the cancellations along with it. Catch the errors you named, with Effect.catchTag or Effect.catchTags",
-  blind: "the handler cannot see what it is recovering from, so every error in the channel collapses into one fallback. Name the errors with Effect.catchTag, or take the error and use it"
-};
-var REFUSED = new Map([
-  ["ignore", INSTEAD.drops],
-  ["ignoreCause", INSTEAD.drops],
-  ["catchCause", INSTEAD.swallows],
-  ["catchCauseIf", INSTEAD.swallows],
-  ["catchCauseFilter", INSTEAD.swallows]
-]);
-var blindToTheError = (handler) => {
-  if (!handler)
-    return false;
-  if (handler.type !== "ArrowFunctionExpression" && handler.type !== "FunctionExpression")
-    return false;
-  return handler.params.every((param) => param.type === "Identifier" && /^_+$/.test(param.name));
-};
-var rule2 = {
-  meta: {
-    type: "problem",
-    docs: { description: "Disallow the combinators that erase Effect's error channel" }
-  },
-  create(context) {
-    const effect = new Set;
-    const named = (node) => {
-      if (!node || node.type !== "MemberExpression" || node.computed)
-        return null;
-      if (node.object.type !== "Identifier" || !effect.has(node.object.name))
-        return null;
-      return node.property.type === "Identifier" ? node.property.name : null;
-    };
-    const refuse = (node, combinator, instead) => {
-      context.report({ node, message: `Effect.${combinator} erases the error channel: ${instead}` });
-    };
-    return {
-      ImportDeclaration(node) {
-        if (!EFFECT_SOURCES.has(node.source.value))
-          return;
-        const module = node.source.value === "effect/Effect";
-        for (const specifier of node.specifiers) {
-          if (specifier.type === "ImportSpecifier") {
-            if (specifier.imported.type === "Identifier" && specifier.imported.name === "Effect")
-              effect.add(specifier.local.name);
-          } else if (module)
-            effect.add(specifier.local.name);
-        }
-      },
-      MemberExpression(node) {
-        const combinator = named(node);
-        if (combinator === null)
-          return;
-        const instead = REFUSED.get(combinator);
-        if (instead !== undefined)
-          refuse(node, combinator, instead);
-      },
-      CallExpression(node) {
-        if (named(node.callee) !== "catch")
-          return;
-        if (!blindToTheError(node.arguments[node.arguments.length - 1]))
-          return;
-        refuse(node, "catch", INSTEAD.blind);
-      }
-    };
-  }
-};
-var no_error_channel_escape_default = rule2;
-
-// effect-channel/no-throw.ts
-var rule3 = {
-  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 = rule3;
-
-// effect-channel/no-try-catch.ts
-var rule4 = {
-  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 = rule4;
-
-// effect-channel/index.ts
+// readability/index.ts
 var plugin = {
-  meta: { name: "effect-channel" },
+  meta: { name: "readability" },
   rules: {
-    "no-error-channel-escape": no_error_channel_escape_default,
-    "no-throw": no_throw_default,
-    "no-try-catch": no_try_catch_default,
     "cognitive-complexity": cognitive_complexity_default
   }
 };
-var effect_channel_default = plugin;
+var readability_default = plugin;
 export {
-  effect_channel_default as default
+  readability_default as default
 };

package/docs/configs/native-settings.md

@@ -57,12 +57,12 @@ The kit's own `.oxlintrc.json` sets these limits for each size override, and a r
 
 <!-- generated size-limits: bun run build writes it from .oxlintrc.json, SIZE_RULES in scripts/size-rules.ts and scripts/doc-blocks.ts -->
 
-| Limits | oxlint rule | `effect-channel/**/*.ts`, `scripts/**/*.ts` | `tests/**/*.ts` |
+| Limits | oxlint rule | `effect-channel/**/*.ts`, `readability/**/*.ts`, `scripts/**/*.ts` | `tests/**/*.ts` |
 | --- | --- | --- | --- |
 | The most lines a file may hold, blank and comment lines counted | `max-lines` | 400 | 600 |
 | The most lines a function may span, blank and comment lines counted | `max-lines-per-function` | 100 | off |
 | The most statements a function may hold | `max-statements` | 30 | 50 |
-| The highest cognitive complexity a function may reach, a switch counted once | `effect-channel/cognitive-complexity` | 15 | 15 |
+| The highest cognitive complexity a function may reach, a switch counted once | `readability/cognitive-complexity` | 15 | 15 |
 | The deepest a block may nest inside a function | `max-depth` | 4 | 4 |
 
 <!-- end generated size-limits -->

package/docs/design.md

@@ -12,7 +12,7 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
 - `files` in package.json is the published surface: `tests/`, `AGENTS.md` and the `.ts` plugin source never reach an install.
   npm adds `package.json`, `README` and `LICENSE` to the tarball whatever `files` says.
   `bun pm pack` builds the same tarball the registry serves, which is what the packed-tarball consumer e2e test installs.
-- The plugin ships compiled as `dist/index.js`, built with `bun build effect-channel/index.ts --outdir dist --target node --format esm`.
+- Each plugin ships compiled under `dist/`, built with `bun build <name>/index.ts --outdir dist/<name> --target node --format esm`.
   Node refuses to type-strip a `.ts` plugin under `node_modules`, so the `.ts` source would fail to load from an installed package.
 - The size rules are plain oxlint rules at `error` in `.oxlintrc.json`, and `bun run lint` enforces them on the whole tree.
   A repository records its existing violations with `oxlint --suppress-all`, and `checks-suppressions-ratchet` refuses any count that rises.
@@ -51,7 +51,7 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
   `@effect/platform-node-shared` is a direct dependency at the same exact version only to pin it: `@effect/platform-bun` asks for it with a `^` range, and a newer rc peers on a newer `effect` than consumers install, so all three move together.
 - Each runnable script ships a `checks-` bin entry, so consumer `package.json` scripts call the short name, which the package manager puts on `PATH` only there.
   A shell runs it through `bun run`, which never falls back to the registry the way `bunx` does.
-  The `.ts` checks keep a `bun` shebang, which needs no build step and no `dist/` entry, unlike the oxlint plugin that node loads.
+  The `.ts` checks keep a `bun` shebang, which needs no build step and no `dist/` entry, unlike the oxlint plugins that node loads.
 - `checks-lint` runs each gate as its own bin in a child process rather than importing it, so a gate behaves the same called alone or through the entry point, and `lint-coverage.sh` stays a shell script.
   The gates run one at a time with their output passed straight through, so each report reads whole and in the table's order.
 - `checks-lint` determines applicable gates from tracked files instead of accepting a repository selection.
@@ -96,6 +96,11 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
   A directory the range deletes still counts as this repository's, so a path under it reads as stale rather than foreign.
 - The command check passes over a page whose front matter sets `audience: consumers`.
   Such a page speaks to a consuming repository, whose scripts are not this one's.
+- `checks-vendor` strips an owner write bit that came back on a cached tree and keeps the tree, rather than refusing it or cloning it again.
+  The GitHub Actions runner clears the read only mode of each item before it deletes `$RUNNER_TEMP`, and on a directory link that chmod lands on the shared tree's top directory.
+  Refusing the tree would fail every later job on the runner until a person cleared it, and cloning it again would need the network after every such job.
+  A write bit is not a write, so the run strips it and then holds the tree to the recorded commit as it holds any tree, and a write it finds there still fails the run.
+  A group or other write bit still fails the run, since another user could have edited `.git/config` through it before `git status` reads it.
 
 ## Related topics
 

package/docs/gates/checks-changelog.md

@@ -0,0 +1,57 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-changelog
+
+`checks-changelog` writes the pending release into `CHANGELOG.md` from the conventional commits since the last release.
+
+## What it checks
+
+It reads the version from `package.json` and treats that version as the release being prepared.
+It lists every conventional commit the release closes, grouped as Features, Fixes, Performance, Reverts and Breaking changes.
+It links each entry to its pull request under the repository address `package.json` names.
+It keeps the date a released section already carries and dates a new section today.
+It writes the whole file newest first, so the changelog is never edited by hand.
+A repository with no tag yet releases from its first commit.
+A release with no conventional commit worth listing keeps only its heading and its date.
+
+## What it reads
+
+It reads `package.json`, `CHANGELOG.md` and the git history from the repository root.
+It finds releases in the version bumps of `package.json` across all of `HEAD` ancestry, so a checkout without tags writes the same file.
+It refuses a shallow checkout, since the releases reach back past its history.
+It refuses a `package.json` with no repository address, since each entry links its pull request under it.
+It refuses a repository address that is no `https` address once `git+`, a trailing slash and `.git` are dropped, since a pull request link needs one.
+
+## Arguments
+
+```sh
+checks-changelog
+```
+
+It takes no arguments.
+Run it through the build, as the release workflow in [checks-release-notes](checks-release-notes.md) shows.
+
+## Exit codes
+
+| Code | Result |
+| --- | --- |
+| 0 | The changelog was written. |
+| 2 | The checkout is shallow, or `package.json` has no `https` repository address. |
+
+## Sample output
+
+```
+checks-changelog: wrote 2 release(s) to CHANGELOG.md
+```
+
+## Opting out
+
+Nothing runs it but the build of a repository that keeps a changelog.
+A repository with no versioned releases leaves it out.
+
+## Related topics
+
+- [checks-release-notes](checks-release-notes.md)
+- [checks-release-report](checks-release-report.md)

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

@@ -0,0 +1,141 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-release-notes
+
+`checks-release-notes` writes the `CHANGELOG.md` section of one version to a file for a GitHub release.
+
+## What it checks
+
+It reads the section the version heads and trims the blank lines around it.
+It writes the notes to the output path.
+It fails when the changelog holds no section for the version or the section is empty.
+
+## What it reads
+
+It reads `CHANGELOG.md` from the working directory.
+It reads the version from its arguments, not from `package.json`.
+
+## Arguments
+
+```sh
+checks-release-notes <version> <output>
+```
+
+The version names the `CHANGELOG.md` section to write, as `0.22.0` with no leading `v`.
+The output names the file to write.
+
+## Exit codes
+
+| Code | Result |
+| --- | --- |
+| 0 | The notes were written. |
+| 2 | The arguments do not parse, or `CHANGELOG.md` holds no notes for the version. |
+
+## Sample output
+
+```
+Released 2026-09-27.
+
+### Features
+
+- Add a release [#67](https://github.com/avi2d/checks/pull/67)
+```
+
+## Release workflow
+
+Each consumer owns `.github/workflows/release.yml` and calls the kit bins from it.
+The version lives in `package.json`, and the tag names the same version with a leading `v`.
+The build writes the changelog, so the release pull request carries the notes before the tag exists.
+A repository that publishes a package to npm releases with this workflow:
+
+```yaml
+name: release
+on:
+  push:
+    tags: ["v*"]
+permissions:
+  contents: read
+  id-token: write
+jobs:
+  publish:
+    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: bun run build
+      - run: git diff --exit-code
+      - name: tag matches package version
+        run: test "v$(bun -p "require('./package.json').version")" = "$GITHUB_REF_NAME"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+      - run: npm publish
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: oven-sh/setup-bun@v2
+      - 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"
+      - name: create the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file "$RUNNER_TEMP/release-notes.md"
+```
+
+A repository that never publishes to npm releases with this workflow instead, since only `checks` publishes a package:
+
+```yaml
+name: release
+on:
+  push:
+    tags: ["v*"]
+permissions:
+  contents: read
+jobs:
+  github-release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bun run build
+      - run: git diff --exit-code
+      - name: tag matches package version
+        run: test "v$(bun -p "require('./package.json').version")" = "$GITHUB_REF_NAME"
+      - name: extract release notes
+        run: ./node_modules/.bin/checks-release-notes "${GITHUB_REF_NAME#v}" "$RUNNER_TEMP/release-notes.md"
+      - name: create the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file "$RUNNER_TEMP/release-notes.md"
+```
+
+Cut a release by merging a pull request that holds only the version bump and the built changelog, then tagging the merge commit on the target branch and pushing the tag.
+The workflow refuses a tag that disagrees with `package.json`, so the tag always names the section the notes come from.
+
+## Opting out
+
+Nothing runs it but the release workflow of a repository that publishes GitHub releases.
+A repository with no versioned releases leaves it out.
+
+## Related topics
+
+- [checks-changelog](checks-changelog.md)
+- [checks-release-report](checks-release-report.md)

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

@@ -0,0 +1,64 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-release-report
+
+`checks-release-report` tells whether the history holds unreleased features or fixes since the last tag.
+
+## What it checks
+
+It lists the conventional commits after the last tag reachable from `HEAD` that reads as a version such as `v0.2.0`.
+It counts a commit when its subject falls in Features, Fixes, Performance, Reverts or Breaking changes, the groups `checks-changelog` writes.
+It prints each unreleased subject on its own line under a count.
+A repository with no tag yet reports every such commit in its history.
+A history with no conventional release-worthy commit reports no unreleased changes.
+
+## What it reads
+
+It reads the tags and the commit subjects from the git history.
+It refuses a shallow checkout, since the tag it sees may not be the last one.
+It passes over any other tag, since only a release tag reads as a version.
+
+## Arguments
+
+```sh
+checks-release-report
+```
+
+It takes no arguments.
+Run it before cutting a tag to decide whether a release is due.
+
+## Exit codes
+
+| Code | Result |
+| --- | --- |
+| 0 | No unreleased changes were found. |
+| 1 | Unreleased changes were found. |
+| 2 | The arguments do not parse, or the history cannot be read. |
+
+## Sample output
+
+A history with unreleased changes prints the count and each subject:
+
+```
+release-report: 2 unreleased change(s) since v0.1.0:
+  feat: price a bill (#4)
+  fix(parts): keep the order of parts (#3)
+```
+
+A history with nothing to release prints one line:
+
+```
+release-report: no unreleased changes since v0.1.0
+```
+
+## Opting out
+
+Nothing runs it but a person or a scheduler deciding when to cut a release.
+A repository with no versioned releases leaves it out.
+
+## Related topics
+
+- [checks-changelog](checks-changelog.md)
+- [checks-release-notes](checks-release-notes.md)