@avi2dg/checks 0.30.0 → 0.32.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.32.0
+
+Released 2026-09-29.
+
+### Features
+
+- **delivery:** add checks-secrets gate that fails a range whose commits add a secret [#112](https://github.com/avi2d/checks/pull/112)
+- **delivery:** open a release pull request daily and tag it when it merges [#111](https://github.com/avi2d/checks/pull/111)
+
+## 0.31.0
+
+Released 2026-09-28.
+
+### Features
+
+- lint .astro files in lint coverage, unused and a thin-frontmatter rule [#108](https://github.com/avi2d/checks/pull/108)
+
 ## 0.30.0
 
 Released 2026-09-28.

package/README.md

@@ -118,15 +118,16 @@ The table groups the gates by vector, the part of a repository each one judges.
 | --- | --- | --- | --- |
 | complexity | [`checks-suppressions-ratchet`](docs/gates/checks-suppressions-ratchet.md) | the range | every repository |
 | complexity | [`checks-repetition`](docs/gates/checks-repetition.md) | the range | a repository tracking `*.ts` or `*.tsx` |
-| complexity | [`checks-unused`](docs/gates/checks-unused.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
+| complexity | [`checks-unused`](docs/gates/checks-unused.md) | the working tree | a repository tracking `*.ts` or `*.tsx` or `*.astro` |
 | complexity | [`checks-exports`](docs/gates/checks-exports.md) | the range | a repository tracking `*.ts` or `*.tsx` |
-| quality | [`checks-lint-coverage`](docs/gates/checks-lint-coverage.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
+| quality | [`checks-lint-coverage`](docs/gates/checks-lint-coverage.md) | the working tree | a repository tracking `*.ts` or `*.tsx` or `*.astro` |
 | quality | [`checks-comment-gate`](docs/gates/checks-comment-gate.md) | the range | every repository |
 | testing | [`checks-test-layout`](docs/gates/checks-test-layout.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
 | testing | [`checks-quarantine-clock`](docs/gates/checks-quarantine-clock.md) | the range | every repository |
 | docs | [`checks-docs`](docs/gates/checks-docs.md) | the range, and every agent file at the head commit | every repository |
 | delivery | [`checks-commit-identity`](docs/gates/checks-commit-identity.md) | the range | every repository |
 | delivery | [`checks-ci-wiring`](docs/gates/checks-ci-wiring.md) | the working tree | every repository |
+| delivery | [`checks-secrets`](docs/gates/checks-secrets.md) | the range | every repository |
 | dependencies | [`checks-advisories`](docs/gates/checks-advisories.md) | the range | a repository tracking `bun.lock` |
 
 <!-- end generated gates -->
@@ -141,6 +142,8 @@ These bins run on their own:
 - [`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-release-pr`](docs/gates/checks-release-pr.md) opens or refreshes the pull request that releases the next version, and dispatches its checks.
+- [`checks-release-tag`](docs/gates/checks-release-tag.md) tags a landed release commit with its version and dispatches the release workflow on the 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.

package/dist/readability/index.js

@@ -416,11 +416,104 @@ var rule = {
 };
 var cognitive_complexity_default = rule;
 
+// src/complexity/readability/thin-astro.ts
+function unwrapped(expression) {
+  let current = expression;
+  while (current.type === "TSAsExpression" || current.type === "TSSatisfiesExpression" || current.type === "TSNonNullExpression" || current.type === "TSTypeAssertion") {
+    current = current.expression;
+  }
+  return current;
+}
+function isAstroProps(value) {
+  if (value.type !== "MemberExpression" || value.computed)
+    return false;
+  const { object, property } = value;
+  return object.type === "Identifier" && object.name === "Astro" && property.type === "Identifier" && property.name === "props";
+}
+function isPlainValue(value, bound) {
+  return value.type === "Literal" || value.type === "Identifier" && bound.has(value.name);
+}
+function readsProps(expression, bound) {
+  const value = unwrapped(expression);
+  if (value.type !== "MemberExpression")
+    return value.type === "Identifier" && bound.has(value.name);
+  if (value.computed && !isPlainValue(value.property, bound))
+    return false;
+  return isAstroProps(value) || readsProps(value.object, bound);
+}
+function isPlainPattern(pattern, bound) {
+  if (pattern === null)
+    return true;
+  if (pattern.type === "RestElement")
+    return isPlainPattern(pattern.argument, bound);
+  if (pattern.type === "AssignmentPattern")
+    return isPlainValue(pattern.right, bound) && isPlainPattern(pattern.left, bound);
+  if (pattern.type === "ArrayPattern")
+    return pattern.elements.every((element) => isPlainPattern(element, bound));
+  if (pattern.type === "Identifier")
+    return true;
+  return pattern.properties.every((property) => property.type === "RestElement" ? isPlainPattern(property.argument, bound) : (!property.computed || isPlainValue(property.key, bound)) && isPlainPattern(property.value, bound));
+}
+function isPropsRead(declarator, bound) {
+  return declarator.init !== null && readsProps(declarator.init, bound) && isPlainPattern(declarator.id, bound);
+}
+function boundName(pattern, found) {
+  if (pattern === null)
+    return;
+  if (pattern.type === "RestElement")
+    boundName(pattern.argument, found);
+  else if (pattern.type === "AssignmentPattern")
+    boundName(pattern.left, found);
+  else if (pattern.type === "ObjectPattern") {
+    for (const property of pattern.properties)
+      boundName(property.type === "Property" ? property.value : property.argument, found);
+  } else if (pattern.type === "ArrayPattern") {
+    for (const element of pattern.elements)
+      boundName(element, found);
+  } else
+    found.add(pattern.name);
+}
+function isTypeDeclaration(statement) {
+  const declaration = statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
+  return declaration?.type === "TSInterfaceDeclaration" || declaration?.type === "TSTypeAliasDeclaration";
+}
+var rule2 = {
+  meta: {
+    type: "problem",
+    docs: { description: 'Disallow logic in .astro frontmatter and script blocks: only imports, props and markup, with client code loaded by a side-effect import such as import "../client.ts"' }
+  },
+  create(context) {
+    if (!context.filename.endsWith(".astro"))
+      return {};
+    const bound = new Set;
+    return {
+      Program(node) {
+        for (const statement of node.body) {
+          if (statement.type === "ImportDeclaration" || statement.type === "EmptyStatement" || statement.type === "ExportNamedDeclaration" && statement.source !== null || isTypeDeclaration(statement)) {
+            continue;
+          }
+          if (statement.type === "VariableDeclaration" && statement.declarations.length > 0 && statement.declarations.every((declarator) => isPropsRead(declarator, bound))) {
+            for (const declarator of statement.declarations)
+              boundName(declarator.id, bound);
+            continue;
+          }
+          context.report({
+            node: statement,
+            message: 'an .astro frontmatter or script block holds more than imports and props: move this statement into a .ts file and import it, so the .astro file holds only imports, props and markup; a script block loads client code with a side-effect import such as import "../client.ts"'
+          });
+        }
+      }
+    };
+  }
+};
+var thin_astro_default = rule2;
+
 // src/complexity/readability/index.ts
 var plugin = {
   meta: { name: "readability" },
   rules: {
-    "cognitive-complexity": cognitive_complexity_default
+    "cognitive-complexity": cognitive_complexity_default,
+    "thin-astro": thin_astro_default
   }
 };
 var readability_default = plugin;

package/docs/configs/commit-messages.md

@@ -23,6 +23,11 @@ It lints the pull request title and nothing else.
 The title is the enforced subject because a squash merge uses it as the main commit subject, and per-commit messages are not linted.
 GitHub appends ` (#N)` to the squashed subject, so the workflow lints the title with that suffix attached, and the header length limit applies to the landed subject, not the bare title.
 The workflow moves git's comment character off `#`, so a title starting with `#` is linted like any other.
+The workflow also triggers on `workflow_dispatch`, since GitHub holds the `pull_request` runs of a release pull request the workflow token opens until a maintainer approves them, as [checks-release-pr](../gates/checks-release-pr.md) says.
+A dispatched run carries no pull request, so the workflow reads the title of the one open pull request its branch heads, and fails when there is none.
+That lookup needs the workflow's `pull-requests: read` permission.
+It reports a dispatched run's result on the head commit as a `commitlint` status, since GitHub keeps a dispatched run's check off the pull request.
+The kit's own `.github/workflows/commitlint.yml` shows the step.
 
 It never sees a commit's author or committer fields, nor the `Co-authored-by` trailer GitHub writes from a foreign author when it squashes, so it cannot enforce who a commit belongs to.
 [checks-commit-identity](../gates/checks-commit-identity.md) is that enforcement.

package/docs/configs/typescript-rules.md

@@ -43,6 +43,16 @@ The base loads the kit's `data-shape` plugin from `dist/` with one rule for ever
 - Derive such a type from the schema with `typeof Name.Type` instead of writing both.
 - The twin rule runs on production files only, so a test that declares its own schema as an oracle stays green.
 
+## Astro rules
+
+An override in `oxlintrc.json` turns on one rule of the kit's `readability` plugin in each `.astro` file:
+
+- `readability/thin-astro` refuses a statement in the frontmatter or a script block that is neither an import, a re-export from another module, a type or interface declaration, nor a variable read from `Astro.props`.
+- A default inside an `Astro.props` destructuring passes only when it is a literal or a name read from `Astro.props` earlier, so `const { title = "Home" } = Astro.props;` passes and a call or `await` in a default is refused.
+- Move a refused statement into a `.ts` file and import it, so the `.astro` file holds only imports, props and markup.
+- A script block loads client code with a side-effect import, as in `<script>import "../client.ts";</script>`, and the override turns off `import/no-unassigned-import` so that import passes.
+- A dynamic route re-exports `getStaticPaths` from a `.ts` file, as in `export { getStaticPaths } from "../lib/paths.ts";`.
+
 ## Rules outside tests
 
 An override in `oxlintrc.json` turns on these type-aware rules in each `.ts` and `.tsx` file outside `tests/`:

package/docs/design.md

@@ -86,7 +86,7 @@ npm adds `package.json`, `README.md` and `LICENSE` whatever `files` says.
 `bun pm pack` builds the same tarball the registry serves, and the consumer e2e test installs that tarball.
 
 Each oxlint plugin ships compiled under `dist/`, because Node refuses to strip types from a `.ts` file under `node_modules`.
-`@oxlint/plugins` ships no RuleTester, so each `effect-channel`, `readability` and `data-shape` rule is proven red and green against an installed consumer in `tests/e2e/consumer.test.ts`.
+`@oxlint/plugins` ships no RuleTester, so each `effect-channel`, `readability` and `data-shape` rule is proven red and green against an installed consumer in `tests/e2e/consumer.test.ts`, except `readability/thin-astro`, which `tests/e2e/astro-consumer.test.ts` proves against a consumer tree linked to the checkout.
 `dist/` is committed, with the doc templates in `dist/templates/`, and so is `CHANGELOG.md`, which the same build writes.
 No `prepack` or `prepublishOnly` script rebuilds them, so a publish ships the committed files.
 CI runs `git diff --exit-code` over the whole tree after `bun run build`.
@@ -109,7 +109,7 @@ So the three packages move together at one exact version.
 A gate then behaves the same alone or through `checks-lint`, and `lint-coverage.sh` can stay a shell script.
 The gates run one at a time and pass their output straight through, so each report reads whole and in the order of the gate table.
 `checks-lint` picks the gates that apply from the tracked files, and a repository cannot select gates.
-A TypeScript gate runs as soon as the repository tracks TypeScript source.
+A TypeScript gate runs as soon as the repository tracks TypeScript source, and `checks-lint-coverage` and `checks-unused` also run on tracked Astro source.
 
 GitHub authors the pull request merge commit it builds as `GitHub <noreply@github.com>`, and `checks-commit-identity` refuses that author.
 So `checks-lint` ends a pull request's range at the event's head commit, and the merge commit is never in it.
@@ -162,8 +162,24 @@ So a checkout without tags, a fork, and a branch that merged `main` in all write
 A section keeps the date it was written, because the squash merge that lands the release commit may fall on another day.
 Entries come from commit subjects, which are the squash-merged pull request titles that commitlint holds to the conventional format.
 A commit body holds the branch's own messages, and nothing lints it, so no entry comes from a body.
-The changelog arrives in the release pull request, and no workflow pushes to the repository.
-The only write access the release path holds is the `github-release` job's `contents: write`, which creates or updates the GitHub release from the tag's `CHANGELOG.md` section.
+The changelog arrives in the release pull request, and no workflow pushes to a branch a person works on.
+
+## A release is cut every day
+
+A release waits for no quiet moment, since a busy repository always has work under way.
+The daily release opens the release pull request from `main` whenever it holds a feature or a fix since the last tag, and the pull request merges through the repository's usual merge path once its checks pass.
+`checks-release-pr` writes only to the `release/<branch>` branch it owns, and rebuilds that branch on `main` rather than merging `main` into it, so the changelog it carries is the one the build writes.
+`checks-release-tag` writes only the `v*` tag of a release commit that already landed.
+The `github-release` job's `contents: write` creates or updates the GitHub release from the tag's `CHANGELOG.md` section.
+
+Both jobs act with the workflow token.
+GitHub starts no run for a push that token makes, and holds the runs of a pull request it opens until a maintainer approves them.
+A GitHub App or a personal token would start them, but either is a credential each repository stores and someone rotates.
+So `checks-release-pr` dispatches the required checks on the release head, and `checks-release-tag` dispatches the release workflow on the tag, since a dispatch is the one run the token can start.
+GitHub keeps a dispatched run's checks off the pull request, and branch protection does not count them.
+So each dispatched job reports its result as a commit status named for the job, which a required check of that name counts.
+Where a status and a check share a name, branch protection requires both, so the status never passes a pull request whose own check failed.
+The cost is a `workflow_dispatch` trigger and a status step on each workflow a release needs, a title lint that reads its title from the open pull request, and the repository setting that lets the token open a pull request.
 
 ## The docs gate judges what a change touches
 
@@ -238,6 +254,24 @@ The kit caps each entry at 30 days and measures a range from the head's dates, a
 `--all` measures from the current time instead, because a head's dates never move in a repository that takes no commit, and an entry measured from them would never expire.
 The file is JSON because `Bun.TOML` cannot parse a TOML date.
 
+## Secrets fail in every commit of the range
+
+`checks-secrets` scans each commit in the range rather than the files at the head.
+A secret a commit adds stays in that commit after a later commit deletes it, and a pushed branch has already sent it to the forge.
+So the fix is to rewrite the commit that added it, and to rotate the secret once it has left the machine.
+
+In a merge commit the gate scans only the merge's own resolution, the difference from the merge git would make on its own.
+A diff against the first parent would also scan what the merge brings in from the other parent, so a branch that merges main would fail on a secret main already holds, from before the range.
+Git gives no such diff for an octopus merge and warns instead of failing, so the gate refuses to scan one rather than pass a commit it never read.
+
+The gate runs gitleaks rather than a hand-written pattern list, because its default config already holds over 200 rules for the token shapes of common services.
+The kit's own rules in `src/delivery/gitleaks.toml` add only the VPN keys and proxy links those rules miss.
+The kit pins gitleaks by version and SHA-256 for the reason it pins OSV-Scanner.
+
+No finding can be accepted.
+A secret has no false positive worth keeping in git, because a placeholder carries the same shape without the value.
+So the gate ignores a repository's `.gitleaks.toml`, `.gitleaksignore` and `gitleaks:allow` comments, which would each let one repository pass what another fails.
+
 ## Related topics
 
 - [checks](../README.md)

package/docs/gates/checks-commit-identity.md

@@ -11,6 +11,9 @@ audience: consumers
 The author and committer of each commit must be allowed.
 A commit whose trailer block carries a `Co-authored-by` trailer, as git parses it, is refused.
 `GitHub <noreply@github.com>` is allowed as committer only.
+`github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>` is allowed as author only of a commit whose subject is `chore: release <version>`, with or without the pull request number a squash merge adds.
+GitHub attributes the release commit [checks-release-pr](checks-release-pr.md) makes to that bot, since it commits through the workflow token.
+Such a commit may carry a `Co-authored-by` trailer naming that bot, since GitHub adds one to some squash merges of a pull request the bot opened, and every other trailer is refused.
 
 ## What it reads
 

package/docs/gates/checks-lint-coverage.md

@@ -4,12 +4,13 @@ audience: consumers
 ---
 # checks-lint-coverage
 
-`checks-lint-coverage` is the gate that fails when oxlint skips a tracked TypeScript file, or when the program `tsconfig.json` builds drops the ts-reset rules, without saying so.
+`checks-lint-coverage` is the gate that fails when oxlint skips a tracked TypeScript or Astro file, or when the program `tsconfig.json` builds drops the ts-reset rules, without saying so.
 
 ## What it checks
 
-It fails when oxlint skips a tracked `.ts` or `.tsx` file, for example through a stray `.gitignore` entry.
+It fails when oxlint skips a tracked `.ts`, `.tsx` or `.astro` file, for example through a stray `.gitignore` entry.
 It compares `git ls-files` against oxlint's own file walk and names the missing files.
+It lists each tracked `.astro` file the same way, since oxlint lints the frontmatter and script blocks of an `.astro` file, where a script block loads client code with a side-effect import such as `import "../client.ts";`.
 
 It fails when the program `tsconfig.json` builds leaves out the `is-array` or the `json-parse` rule of `@total-typescript/ts-reset`, which `tsconfig.effect.json` lists.
 A `tsconfig.json` that does not extend `@avi2dg/checks/tsconfig.effect.json`, or that sets both `files` and `include`, leaves both rules out.
@@ -17,9 +18,9 @@ A `tsconfig.json` that does not extend `@avi2dg/checks/tsconfig.effect.json`, or
 
 ## What it reads
 
-It reads the working tree: the `*.ts` and `*.tsx` files `git ls-files` lists, and the files `oxlint --debug=files` walks.
+It reads the working tree: the `*.ts`, `*.tsx` and `*.astro` files `git ls-files` lists, and the files `oxlint --debug=files` walks.
 It walks without naming a path, since an explicit path bypasses the ignore files whose skips it looks for.
-It reads the program from `tsc --listFilesOnly -p tsconfig.json`, and passes over the program when the root holds no `tsconfig.json`.
+It reads the program from `tsc --listFilesOnly -p tsconfig.json`, and passes over the program when the repository tracks no `.ts` or `.tsx` file or the root holds no `tsconfig.json`.
 oxlint and tsc must be on `PATH`, as they are under a package script.
 
 ## Arguments
@@ -30,14 +31,14 @@ It takes none.
 
 | Code | When |
 | --- | --- |
-| 0 | the repository tracks no `.ts` or `.tsx` file, or oxlint walks each one and the program holds both ts-reset rules or the root holds no `tsconfig.json` |
+| 0 | the repository tracks no `.ts`, `.tsx` or `.astro` file, or oxlint walks each one and the program holds both ts-reset rules, the repository tracks no `.ts` or `.tsx` file or the root holds no `tsconfig.json` |
 | 1 | oxlint skips a tracked file, or the program drops a ts-reset rule |
 | 2 | oxlint cannot walk the tree, or tsc cannot list the program after oxlint walks every tracked file, as when either is not on `PATH` or a config does not parse |
 
 ## Sample output
 
 ```
-lint-coverage: oxlint skips 1/3 tracked .ts/.tsx files; missing:
+lint-coverage: oxlint skips 1/3 tracked .ts/.tsx/.astro files; missing:
 ignored/b.ts
 lint-coverage: the program tsconfig.json builds drops the ts-reset rules: is-array json-parse
   extend @avi2dg/checks/tsconfig.effect.json, and set files or include in tsconfig.json but not both
@@ -46,13 +47,13 @@ lint-coverage: the program tsconfig.json builds drops the ts-reset rules: is-arr
 A passing run counts the files and names the rules:
 
 ```
-lint-coverage: 71/71 tracked .ts/.tsx files
+lint-coverage: 71/71 tracked .ts/.tsx/.astro files
 lint-coverage: the program tsconfig.json builds holds the ts-reset rules is-array and json-parse
 ```
 
 ## When it runs
 
-`checks-lint` runs it when the repository tracks a `.ts` or `.tsx` file.
+`checks-lint` runs it when the repository tracks a `.ts`, `.tsx` or `.astro` file.
 
 ## Related topics
 

package/docs/gates/checks-lint.md

@@ -10,6 +10,7 @@ audience: consumers
 
 It runs the gates under [What runs](../../README.md#what-runs), each in its own process.
 Gates requiring tracked TypeScript files begin running when the repository tracks TypeScript.
+`checks-lint-coverage` and `checks-unused` also begin running when the repository tracks an `.astro` file.
 `checks-advisories` begins running when the repository tracks `bun.lock`.
 All other gates run for every repository.
 
@@ -45,7 +46,7 @@ With two arguments, the base and head override range discovery.
 
 ```
 checks-lint: range 2504acf098d120e73a8ece3c96f22b934f35c6a8..10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD against origin/main
-checks-lint: 1 of 12 gate(s) failed: checks-comment-gate
+checks-lint: 1 of 13 gate(s) failed: checks-comment-gate
 ```
 
 <!-- end generated lint-sample -->
@@ -53,7 +54,7 @@ checks-lint: 1 of 12 gate(s) failed: checks-comment-gate
 ## When it runs
 
 A repository runs it from `bun run lint` in a pull request workflow that fetches the whole git history.
-It leaves out the TypeScript gates while the repository tracks no TypeScript file.
+It leaves out the TypeScript gates while the repository tracks no TypeScript file, except that `checks-lint-coverage` and `checks-unused` run when it tracks an `.astro` file.
 
 ## Related topics
 

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

@@ -55,6 +55,7 @@ name: release
 on:
   push:
     tags: ["v*"]
+  workflow_dispatch:
 permissions:
   contents: read
   id-token: write
@@ -65,6 +66,8 @@ jobs:
       - uses: actions/checkout@v5
         with:
           fetch-depth: 0
+      - name: ref is a tag
+        run: test "$GITHUB_REF_TYPE" = tag
       - uses: oven-sh/setup-bun@v2
       - run: bun install --frozen-lockfile
       - run: bun run build
@@ -102,6 +105,7 @@ name: release
 on:
   push:
     tags: ["v*"]
+  workflow_dispatch:
 permissions:
   contents: read
 jobs:
@@ -113,6 +117,8 @@ jobs:
       - uses: actions/checkout@v5
         with:
           fetch-depth: 0
+      - name: ref is a tag
+        run: test "$GITHUB_REF_TYPE" = tag
       - uses: oven-sh/setup-bun@v2
       - run: bun install --frozen-lockfile
       - run: bun run build
@@ -127,7 +133,10 @@ jobs:
         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.
+A release is a pull request that holds only the version bump and the built changelog, which [checks-release-pr](checks-release-pr.md) opens once a day.
+When it lands, [checks-release-tag](checks-release-tag.md) tags the merge commit and dispatches this workflow on the tag.
+A tag the workflow token pushes starts no `push` run, so the workflow triggers on `workflow_dispatch` as well, and refuses a dispatch on a ref that is not a tag.
+A tag a person pushes starts the same workflow through its `push` trigger.
 The workflow refuses a tag that disagrees with `package.json`, so the tag always names the section the notes come from.
 
 ## When it runs

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

@@ -0,0 +1,185 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-release-pr
+
+`checks-release-pr` opens or refreshes the one pull request that releases the next version, and dispatches its checks on its head.
+
+## What it checks
+
+It lists the unreleased changes the way [checks-release-report](checks-release-report.md) does, and does nothing when there are none.
+It bumps the version `package.json` holds by the kit's rule:
+
+| Unreleased changes | Below 1.0.0 | From 1.0.0 |
+| --- | --- | --- |
+| a breaking change | minor | major |
+| a feature and no breaking change | minor | minor |
+| only fixes, performance changes or reverts | patch | patch |
+
+It refuses when the last release tag names a version other than the one `package.json` holds, since an untagged bump means a release landed that nothing published.
+The refusal points at the `tag` job of `daily-release` on the release commit, whose own refusal says what to fix, rather than at a tag pushed by hand.
+It refuses a version that is not a plain `major.minor.patch`.
+It writes the next version into `package.json`, runs `bun run build` so the build writes `CHANGELOG.md`, and commits every tracked file the build changed as `chore: release <version>`.
+The commit's one parent is `HEAD`.
+It makes the commit through the GitHub API, which attributes it to `github-actions[bot]` and signs it, so the job sets no git identity.
+It checks that the tree GitHub built matches the tree the build wrote.
+It points the branch `release/<branch>` at the commit, where `<branch>` is the branch `HEAD` is on.
+It opens a pull request from that branch into `<branch>` titled `chore: release <version>`, with the body `Release <version>.`, or retitles the open one to the new version.
+It then dispatches each workflow its arguments name on the release branch.
+GitHub holds the `pull_request` runs of a pull request the workflow token opens until a maintainer approves them, so the dispatch is what runs the required checks on the release head.
+GitHub keeps a dispatched run's checks off the pull request, so each dispatched job reports its result as a commit status named for the job, which the required check of that name counts.
+When the release branch already holds this version on top of `HEAD` and its pull request carries the right title, it pushes nothing and dispatches nothing.
+It leaves the working tree as it found it.
+
+## What it reads
+
+It reads the `v*` tags, the commit subjects since the last one and `package.json` from the checkout.
+It refuses a shallow checkout, a detached `HEAD` and a working tree with changes to tracked files.
+It reads the release branch from `origin` with `git ls-remote` and `git fetch`.
+It calls the GitHub API through `gh api`, which takes the repository from the checkout's remote and the token from `GH_TOKEN`.
+The token needs `contents: write`, `pull-requests: write` and `actions: write`.
+The repository needs **Allow GitHub Actions to create and approve pull requests** turned on under its Actions settings, or GitHub refuses the pull request.
+
+## Arguments
+
+```sh
+checks-release-pr <workflow>...
+```
+
+Each argument names a workflow file under `.github/workflows/` whose jobs report the checks the default branch requires, such as `ci.yml` and `commitlint.yml`.
+Each named workflow triggers on `workflow_dispatch`.
+Name no workflow that runs something else on dispatch, such as a mutation baseline.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | nothing is unreleased, or the release pull request is open on the current `HEAD` and its checks are dispatched |
+| 2 | the arguments do not parse, a refusal above applies, the build fails, or a GitHub API call fails |
+
+## Sample output
+
+A run that opens the pull request prints the build's own output, then one line:
+
+```
+release-pr: opened https://github.com/acme/widget/pull/12 to release 0.4.0, and dispatched ci.yml, commitlint.yml on release/main
+```
+
+A run on the same `HEAD` the next day prints one line:
+
+```
+release-pr: https://github.com/acme/widget/pull/12 releases 0.4.0 from 3f2a9c81d0b4 and is current
+```
+
+## When it runs
+
+The daily release workflow below runs it once a day on the default branch.
+Run the workflow by hand with `gh workflow run daily-release` to refresh the release pull request sooner.
+
+## Running it in CI
+
+A repository takes the daily release as `.github/workflows/daily-release.yml`.
+The `pull-request` job runs on the schedule, and the `tag` job runs when a release commit lands on `main`, as [checks-release-tag](checks-release-tag.md) says:
+
+```yaml
+name: daily-release
+on:
+  schedule:
+    - cron: "29 3 * * *"
+  workflow_dispatch:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+jobs:
+  pull-request:
+    if: github.event_name != 'push'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    concurrency:
+      group: release-pull-request
+      cancel-in-progress: false
+    permissions:
+      contents: write
+      pull-requests: write
+      actions: write
+    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: open or refresh the release pull request
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: ./node_modules/.bin/checks-release-pr ci.yml commitlint.yml
+  tag:
+    if: "github.event_name == 'push' && startsWith(github.event.head_commit.message, 'chore: release ')"
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+      actions: write
+    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: tag the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: ./node_modules/.bin/checks-release-tag release.yml
+```
+
+A public repository keeps `runs-on: ubuntu-latest`.
+A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || fromJSON('["self-hosted","Linux","X64","winbox"]') }}` on both jobs, as its other workflows do.
+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.
+Neither job runs a test suite or a mutation run.
+On a hosted runner the `pull-request` job takes about 25 seconds, which GitHub bills as one minute, whether it opens, refreshes or leaves the pull request alone.
+A private repository runs it on its self-hosted runner, which bills no minutes.
+The `tag` job runs only when a release lands, and a job its `if` skips bills nothing.
+The checks it dispatches are the release pull request's own required checks, and they run again only when `main` moves under it.
+The pull request also lists its own `pull_request` runs as waiting for approval.
+Nothing requires them, and approving them runs the same checks again.
+
+The daily release needs the repository's other workflows to accept the dispatch:
+
+- `.github/workflows/ci.yml` and `.github/workflows/commitlint.yml` trigger on `workflow_dispatch`, grant `statuses: write`, and end each required job with the step below.
+  `commitlint.yml` also grants `pull-requests: read`, which the title lookup needs.
+- The title lint reads the title of the one open pull request its branch heads when the event carries none, as [Commit messages](../configs/commit-messages.md) says.
+- `.github/workflows/release.yml` triggers on `workflow_dispatch` and refuses a ref that is not a tag, as [checks-release-notes](checks-release-notes.md) shows.
+- **Allow GitHub Actions to create and approve pull requests** is on, which the call after the step sets.
+- A release pull request holds current `main` when it merges.
+  One that merges behind `main` lands a changelog short of the commits `main` gained, and `checks-release-tag` refuses to tag it.
+
+The step reports a dispatched run's result as a commit status on the head commit:
+
+```yaml
+      - name: report the result on the head commit
+        if: always() && github.event_name == 'workflow_dispatch'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          STATE: ${{ job.status == 'success' && 'success' || 'failure' }}
+        run: gh api "repos/$GITHUB_REPOSITORY/statuses/$GITHUB_SHA" -f state="$STATE" -f context="$GITHUB_JOB" -f target_url="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" --silent
+```
+
+The status takes the job's id as its name, so a required job's id is the check name the branch requires.
+Where a status and a check share a name, branch protection requires both, so the status never passes a pull request whose own check failed.
+The call turns the repository setting on:
+
+```sh
+gh api --method PUT repos/<owner>/<repo>/actions/permissions/workflow -F can_approve_pull_request_reviews=true
+```
+
+## Related topics
+
+- [checks-release-report](checks-release-report.md)
+- [checks-release-tag](checks-release-tag.md)
+- [checks-changelog](checks-changelog.md)
+- [checks-release-notes](checks-release-notes.md)

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

@@ -27,7 +27,7 @@ checks-release-report
 ```
 
 It takes no arguments.
-Run it before cutting a tag to decide whether a release is due.
+Run it to see whether a release is due and what it holds.
 
 ## Exit codes
 
@@ -55,10 +55,12 @@ release-report: no unreleased changes since v0.1.0
 
 ## When it runs
 
-Only a person or a scheduler deciding when to cut a release runs it.
+A person runs it to see what the next release holds.
+[checks-release-pr](checks-release-pr.md) reads the same changes before it opens the release pull request.
 A repository with no versioned releases does not need it.
 
 ## Related topics
 
 - [checks-changelog](checks-changelog.md)
 - [checks-release-notes](checks-release-notes.md)
+- [checks-release-pr](checks-release-pr.md)