@avi2dg/checks 0.30.0 → 0.32.0

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

@@ -0,0 +1,63 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-release-tag
+
+`checks-release-tag` tags a landed release commit with its version and dispatches the release workflow on the tag.
+
+## What it checks
+
+It reads the subject of `HEAD`, and does nothing unless the subject is `chore: release <version>`, with or without the ` (#N)` a squash merge adds.
+It refuses a release commit whose `package.json` holds another version.
+It tags `HEAD` as `v<version>` and pushes the tag to `origin`.
+A tag the workflow token pushes starts no `push` workflow, so it then dispatches the workflow its argument names on the tag.
+It does nothing when `v<version>` already tags `HEAD`, so a rerun after a release never publishes it twice.
+When the dispatch fails after the push, it names `gh workflow run <workflow> --ref v<version>`.
+A rerun then finds the tag and does nothing, so that command is what dispatches the release workflow by hand.
+It refuses when `v<version>` already tags another commit.
+Before it pushes the tag, it runs `bun run build` and refuses when the build rewrites a committed file.
+That happens when a release pull request merged behind `main`, so its `CHANGELOG.md` lacks the commits `main` gained.
+The refusal says to open a `chore: cancel the unpublished <version>` pull request that returns `package.json` to the last tag's version and commits what `bun run build` then writes to `CHANGELOG.md`.
+The build reads the returned version as a revert, so it drops the unpublished section, and the next `daily-release` run cuts the release again with every change since the last tag.
+
+## What it reads
+
+It reads the subject of `HEAD` and `package.json` from the checkout, and the tag from `origin` with `git ls-remote`.
+The build it runs reads the whole history, so the checkout fetches all of it.
+It pushes the tag with the credentials the checkout holds.
+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` and `actions: write`.
+
+## Arguments
+
+```sh
+checks-release-tag <workflow>
+```
+
+The argument names the release workflow file under `.github/workflows/`, such as `release.yml`.
+That workflow triggers on `workflow_dispatch` and keeps its own guards, as [checks-release-notes](checks-release-notes.md) shows.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | `HEAD` is no release commit, its tag already tags it, or the tag is pushed and the release workflow dispatched |
+| 2 | the arguments do not parse, `package.json` disagrees with the subject, the tag tags another commit, the build fails or rewrites a committed file, or the push or a GitHub API call fails |
+
+## Sample output
+
+A run that tags the release prints the build's own output, then one line:
+
+```
+release-tag: tagged 3f2a9c81d0b4 as v0.4.0, and dispatched release.yml on it
+```
+
+## When it runs
+
+The `tag` job of the daily release workflow runs it on each push to `main` whose head commit reads as a release, as [checks-release-pr](checks-release-pr.md#running-it-in-ci) shows.
+
+## Related topics
+
+- [checks-release-pr](checks-release-pr.md)
+- [checks-release-notes](checks-release-notes.md)

package/docs/gates/checks-secrets.md

@@ -0,0 +1,93 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-secrets
+
+`checks-secrets` is the gate that fails a range whose commits add a secret, such as an API token, a private key, a VPN key or a proxy link that carries its credential.
+
+## What it checks
+
+It scans the lines each commit in the range adds, in every file the commit adds or modifies, with gitleaks.
+In a merge commit it scans the lines the merge's own resolution adds, such as a key written while resolving a conflict, and not what the merge brings in from the other parent.
+It exits 2 when a commit it scans is an octopus merge, one with three or more parents, because git gives no resolution diff for one.
+It fails on each secret the scan finds, and names its file, its line, the rule that matched and the commit that added it.
+A secret one commit adds and a later commit in the range removes still fails, because the first commit still holds it.
+It guards new changes only, and never scans a commit before the range, so a secret already in the history takes no part.
+
+It runs gitleaks' default rules, which know the API keys and tokens of common services and private keys in PEM form, and eight rules of the kit's own that report a secret:
+
+| Rule | What it matches | What passes |
+| --- | --- | --- |
+| `wireguard-key` | a WireGuard or AmneziaWG private or pre-shared key value, 44 base64 characters, under a name that ends in `PrivateKey`, `PresharedKey` or `psk`, such as a real key after `PrivateKey =`, `"privateKey":`, `wg_private_key:` or `client_psk:` | a placeholder such as `<private-key>` or `${WG_PRIVATE_KEY}` |
+| `wireguard-key-file` | a line that holds only a WireGuard or AmneziaWG key, 44 base64 characters, in a file whose name holds `priv`, `preshared`, `pre_shared`, `pre-shared` or `psk`, such as the `privatekey` file `wg genkey \| tee privatekey` writes, whatever else the name holds | a bare key in a file with any other name, such as `publickey` or `peer.pub`, and a placeholder such as `<private-key>` |
+| `wireguard-dot-key-file` | a line that holds only a WireGuard or AmneziaWG key in a file whose name ends in `.key`, such as `wg0.key` | a file whose name ends in `pub.key` or `public.key`, such as `server-public.key`, unless `wireguard-key-file` matches its name |
+| `proxy-userinfo-link` | a `vless://`, `vmess://`, `ss://`, `trojan://`, `hysteria://`, `hysteria2://`, `hy2://`, `tuic://`, `socks://`, `socks5://`, `socks5h://`, `wireguard://` or `wg://` link whose credential before an `@` has a Shannon entropy above 2.5 bits per character, such as a real password before the `@` of a `trojan://` link or a real private key before the `@` of a `wireguard://` link, and a template reference with real text around it, such as a literal user before `:${PASS}` or a non-empty default in `${PASS:-…}` | a link with no credential such as `socks5://127.0.0.1:1080`, a low-entropy credential such as `pw@` or `user@`, a placeholder credential such as `vless://<uuid>@<host>`, a credential that is only template references, such as `{password}`, `$PASS`, `{{ password }}` or `%(password)s` naming a variable that starts with a letter or underscore, or any `${…}` interpolation except a shell default such as `${PASS:-value}`, such as `${pass}`, `${pass:-}`, `${pass:?message}` or `${encodeURIComponent(pass)}`, including a user part such as `$USER:$PASS@`, and a link to `example.com`, `example.net`, `example.org`, a host under `.example`, `.invalid` or `.test`, or `localhost` |
+| `proxy-base64-link` | a `vmess://`, `ss://` or `ssr://` link whose payload is 16 or more base64 characters with a Shannon entropy above 4.2 bits per character, whatever follows it | a placeholder such as `vmess://<base64-config>`, a link to a host and port such as `ss://vpn.home.net:8388`, and a payload an `@` follows, which `proxy-userinfo-link` judges |
+| `proxy-query-credential-first` | the first `auth`, `auth_str`, `obfsParam`, `obfs-password`, `password` or `pk` query value of one of the links `proxy-userinfo-link` names or an `ssr://` link, whose Shannon entropy is above 2.5 bits per character, such as a real password in the `auth` of a `hysteria://` link or a real private key in the `pk` of a `wg://` link, whatever parameters come before or after it | a low-entropy value such as `auth=pw`, a placeholder value such as `auth=<password>`, a value that is only template references as `proxy-userinfo-link` describes, such as `auth={auth}`, `auth=${HY_AUTH:?set HY_AUTH}` or `auth=${encodeURIComponent("a b")}`, and a link to one of the example hosts above |
+| `proxy-query-credential-last` | the last of these query values in such a link, judged the same way, so a real value after a low-entropy or template one still fails | what passes `proxy-query-credential-first` |
+| `proxy-subscription-url` | 16 or more token characters with a Shannon entropy above 3.0 bits per character after the `sub`, `subs`, `subscribe`, `subscription` or `link` path segment of an `http` or `https` URL, or in any `token`, `key`, `uuid` or `id` query value on a line that holds such a URL, each judged on its own | a `token`, `key`, `uuid` or `id` value on a line with no such URL, and a URL to one of the example hosts above |
+
+A ninth rule, `proxy-subscription-path`, reports nothing: it finds the URL `proxy-subscription-url` needs on the same line.
+
+These rules do not catch:
+
+- a real query value between two others of these parameters in one link whose values are low-entropy or template references, such as a real `auth` between an `obfsParam=pw` or `obfsParam=${OBFS}` and a `password=pw`
+- a real `auth`, `auth_str`, `obfsParam`, `obfs-password`, `password` or `pk` query value of an `http` or `https` URL, or of a scheme the table does not name, because the kit's query rules judge share links only, and gitleaks' default rules catch such a value only now and then
+- a credential that begins with `${` and is not a shell default such as `${PASS:-value}`, `${PASS-value}`, `${PASS:=value}` or `${PASS:+value}`, because it reads as an interpolation, even when it holds a fallback such as `${auth ?? "value"}`
+
+No setting accepts a finding.
+It ignores a repository's `.gitleaks.toml`, its `.gitleaksignore` and every `gitleaks:allow` comment.
+It skips the paths gitleaks' default config skips, such as lockfiles, images and `node_modules/`.
+
+## What it reads
+
+It reads the commits of the range from git, not the working tree.
+It needs git 2.36 or newer, which diffs a merge against the merge git would make on its own, and it exits 2 on an older git.
+It reads its rules from `src/delivery/gitleaks.toml` in the installed package.
+
+It runs gitleaks 8.30.1, pinned by the SHA-256 of each platform's archive and of the binary inside it.
+On first use it downloads the archive from the scanner's GitHub release and unpacks the binary into `~/.cache/avi2dg-checks/gitleaks/8.30.1/`.
+It checks the binary's SHA-256 again on every run and exits 2 on a copy that differs.
+Builds are pinned for macOS and Linux, each on x64 and arm64.
+On any other platform it exits 2, and no setting runs a scanner other than the pinned build.
+A cold cache downloads about 8 MB.
+
+## Arguments
+
+```sh
+checks-secrets <base-ref> <head-ref>
+checks-secrets <ref>
+```
+
+With two arguments it scans each commit from the merge base of the two refs to the head.
+With one it scans that commit alone.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | no commit in the range adds a secret |
+| 1 | a commit in the range adds a secret |
+| 2 | a ref does not resolve, or a commit it scans is an octopus merge, or no verified scanner is at hand, or git is older than 2.36, or gitleaks fails |
+
+## Sample output
+
+```
+secrets: the range adds 3 secret(s); put a placeholder such as <private-key> in its place in the commit that added it, and rotate any secret that left this machine:
+  vpn/links.txt:1 proxy-userinfo-link in e19e45c2: A proxy share link that carries its credential before the @, such as vless://, trojan://, socks5:// or wireguard://
+  vpn/wg0.conf:2 wireguard-key in e19e45c2: A WireGuard or AmneziaWG private or pre-shared key
+  vpn/wg0.conf:7 wireguard-key in e19e45c2: A WireGuard or AmneziaWG private or pre-shared key
+```
+
+The report never prints a secret.
+
+## When it runs
+
+`checks-lint` runs it over each pull request's range in every repository, as [checks-lint](checks-lint.md) says.
+A local `bun run lint` runs it over the commits the branch adds, so it fails before a push.
+
+## Related topics
+
+- [checks-lint](checks-lint.md)
+- [Why it is shaped this way](../design.md)

package/docs/gates/checks-unused.md

@@ -4,14 +4,14 @@ audience: consumers
 ---
 # checks-unused
 
-`checks-unused` is the gate that refuses a TypeScript file no entry point reaches.
+`checks-unused` is the gate that refuses a TypeScript or Astro file no entry point reaches.
 
 ## What it checks
 
-It runs Knip with the repository's own configuration and names each `.ts` or `.tsx` file no entry reaches.
+It runs Knip with the repository's own configuration and names each `.ts`, `.tsx` or `.astro` file no entry reaches.
 It reads only the files issue type, so an unused export or dependency never fails it.
 It asks Knip for that issue type itself, so a configuration that narrows `include`, excludes files or turns the files rule off still has its files judged.
-It fails when the repository tracks no TypeScript source, since an empty scan would pass without judging anything.
+It fails when the repository tracks no `.ts`, `.tsx` or `.astro` file, since an empty scan would pass without judging anything.
 It fails when the repository holds no Knip configuration, since Knip's default entries cannot tell a dead file from an entry point.
 
 ## What it reads
@@ -27,6 +27,7 @@ export default { ...base, entry: ["src/index.ts", "tests/**/*.test.ts"] };
 ```
 
 The base in `knip-base.json` reports only unreferenced files.
+In a repository that depends on `astro`, Knip reads `.astro` imports, so a file only an `.astro` entry imports counts as used and an `.astro` file no entry reaches is named.
 The gate resolves the Knip binary from the installed kit, so a consumer installs nothing beyond the kit.
 
 ## Arguments
@@ -39,7 +40,7 @@ It takes none.
 | --- | --- |
 | 0 | no tracked file is unreferenced |
 | 1 | a tracked file is unreferenced or the repository holds no Knip configuration |
-| 2 | the repository tracks no TypeScript source, Knip cannot run, or its configuration does not parse |
+| 2 | the repository tracks no TypeScript or Astro source, Knip cannot run, or its configuration does not parse |
 
 ## Sample output
 
@@ -51,12 +52,12 @@ unused: 1 unreferenced file(s):
 A passing run counts the files it judged:
 
 ```
-unused: no unreferenced files among 110 tracked .ts/.tsx file(s)
+unused: no unreferenced files among 110 tracked .ts/.tsx/.astro file(s)
 ```
 
 ## 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.
 Such a repository names its entries in a Knip configuration.
 
 ## Related topics

package/oxlintrc.json

@@ -37,6 +37,13 @@
         "typescript/no-unsafe-return": "error",
         "typescript/no-unsafe-call": "error"
       }
+    },
+    {
+      "files": ["**/*.astro"],
+      "rules": {
+        "readability/thin-astro": "error",
+        "import/no-unassigned-import": "off"
+      }
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "license": "MIT",
   "repository": {
@@ -29,6 +29,10 @@
     "src/delivery/changelog-write.ts",
     "src/delivery/release-notes.ts",
     "src/delivery/release-report.ts",
+    "src/delivery/release.ts",
+    "src/delivery/release-pr.ts",
+    "src/delivery/release-tag.ts",
+    "src/delivery/github.ts",
     "src/testing/test-layout.ts",
     "src/testing/test.ts",
     "src/testing/test-skips.ts",
@@ -43,6 +47,9 @@
     "src/testing/subsumed-tests.ts",
     "src/delivery/ci-wiring.ts",
     "src/delivery/shell-command.ts",
+    "src/delivery/secrets.ts",
+    "src/delivery/gitleaks.ts",
+    "src/delivery/gitleaks.toml",
     "src/quality/comment-matchers.ts",
     "src/docs/prose-matchers.ts",
     "src/quality/comments.ts",
@@ -60,6 +67,7 @@
     "src/dependencies/advisories.ts",
     "src/dependencies/advisory-rules.ts",
     "src/dependencies/osv-scanner.ts",
+    "src/dependencies/pinned-binary.ts",
     "src/docs/doc-agents.ts",
     "src/docs/doc-outline.ts",
     "src/docs/doc-rules.ts",
@@ -93,6 +101,8 @@
     "checks-changelog": "src/delivery/changelog-write.ts",
     "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-tag": "src/delivery/release-tag.ts",
     "checks-lint-coverage": "src/quality/lint-coverage.sh",
     "checks-test-layout": "src/testing/test-layout.ts",
     "checks-test": "src/testing/test.ts",
@@ -110,14 +120,17 @@
     "checks-quarantine-clock": "src/testing/quarantine-clock.ts",
     "checks-docs": "src/docs/docs.ts",
     "checks-vendor": "src/dependencies/vendor.ts",
-    "checks-advisories": "src/dependencies/advisories.ts"
+    "checks-advisories": "src/dependencies/advisories.ts",
+    "checks-secrets": "src/delivery/secrets.ts"
   },
   "scripts": {
     "prepare": "bun src/dependencies/vendor.ts --library effect --package effect --repository https://github.com/Effect-TS/effect.git --tag 'effect@{version}' --path packages/effect/package.json",
     "build": "bun build src/quality/effect-channel/index.ts --outdir dist/effect-channel --target node --format esm && bun build src/complexity/readability/index.ts --outdir dist/readability --target node --format esm && bun build src/quality/data-shape/index.ts --outdir dist/data-shape --target node --format esm && bun scripts/doc-templates-write.ts && bun src/delivery/changelog-write.ts && bun scripts/doc-blocks-write.ts",
     "lint": "oxlint --type-aware && bun src/core/lint.ts && depcruise --config .dependency-cruiser.cjs .",
     "typecheck": "tsc --noEmit && effect-tsgo diagnostics --project tsconfig.json --format text --strict",
-    "test": "bun src/testing/test.ts"
+    "test": "bun src/testing/test.ts",
+    "mutate": "bunx stryker run",
+    "mutate:incremental": "bunx stryker run --incremental"
   },
   "peerDependencies": {
     "@swc/core": "1.16.2",
@@ -131,7 +144,9 @@
   },
   "devDependencies": {
     "@effect/tsgo": "0.45.0",
+    "@hughescr/stryker-bun-runner": "1.4.0",
     "@oxlint/plugins": "1.83.0",
+    "@stryker-mutator/core": "10.0.0",
     "@swc/core": "1.16.2",
     "@types/bun": "^1.3.0",
     "dependency-cruiser": "18.4.0",
@@ -148,5 +163,9 @@
     "@effect/platform-node-shared": "4.0.0-rc.115",
     "@total-typescript/ts-reset": "0.6.1",
     "knip": "6.38.0"
+  },
+  "overrides": {
+    "qs": "6.16.0",
+    "smol-toml": "1.9.0"
   }
 }

package/src/complexity/exports.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import { TYPESCRIPT_SOURCE } from "../core/gates.ts";
 import { checkoutFiles, commitOf, git, pathsAt, rangeEnds, refArgs } from "../core/git.ts";
 import { runMain } from "../core/main.ts";
 import { knipReport, scanTree } from "./knip.ts";
@@ -127,7 +128,7 @@ export function report(head: Baseline, { unlisted, added, stale }: Drift): strin
     : `${NAME}: ${head.length} unused export(s) in ${BASELINE_FILE}, and no new ones`;
 }
 
-const scan = scanTree(NAME, INCLUDED).pipe(Effect.mapError((cause) => new ExportsError({ message: cause.message })));
+const scan = scanTree(NAME, INCLUDED, TYPESCRIPT_SOURCE).pipe(Effect.mapError((cause) => new ExportsError({ message: cause.message })));
 
 // Knip loads the configuration's imports, such as the kit's knip-base.json, from a node_modules the checkout lacks.
 const unusedAt = Effect.fn("unusedAt")(

package/src/complexity/knip.ts

@@ -1,4 +1,5 @@
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import type { TrackedContent } from "../core/gates.ts";
 import { collect, git } from "../core/git.ts";
 
 class KnipError extends Schema.TaggedError<KnipError>()("KnipError", {
@@ -16,8 +17,6 @@ const CONFIGS = [
   "knip.config.ts",
 ] as const;
 
-const TYPESCRIPT = ["*.ts", "*.tsx"];
-
 const hasKnipConfig = Effect.fn("hasKnipConfig")(function* (root: string) {
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
@@ -55,13 +54,13 @@ export const knipReport = Effect.fn("knipReport")(function* (root: string, args:
   return { kind: "reported", stdout: run.stdout } as const;
 });
 
-export const scanTree = Effect.fn("scanTree")(function* (name: string, args: readonly string[]) {
+export const scanTree = Effect.fn("scanTree")(function* (name: string, args: readonly string[], source: TrackedContent) {
   const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
-  const tracked = (yield* git(["ls-files", "--", ...TYPESCRIPT], root))
+  const tracked = (yield* git(["ls-files", "--", ...source.pathspecs], root))
     .split("\n")
     .map((line) => line.trim())
     .filter((line) => line !== "");
-  if (tracked.length === 0) return yield* new KnipError({ message: "no tracked .ts or .tsx files to scan" });
+  if (tracked.length === 0) return yield* new KnipError({ message: `no tracked ${source.content} to scan` });
   const reported = yield* knipReport(root, args);
   if (reported.kind === "unconfigured") {
     yield* Console.log(`${name}: no knip configuration names entry files, so add one extending the kit's knip-base.json`);

package/src/complexity/unused.ts

@@ -1,12 +1,13 @@
 #!/usr/bin/env bun
 import { Console, Effect, Schema } from "effect";
+import { LINTED_SOURCE } from "../core/gates.ts";
 import { runMain } from "../core/main.ts";
 import { scanTree } from "./knip.ts";
 
 export type Scan = { readonly tracked: number; readonly files: readonly string[] };
 
 const NAME = "unused";
-const JUDGED = /\.tsx?$/;
+const JUDGED = /[.]tsx?$|[.]astro$/;
 
 class UnusedError extends Schema.TaggedError<UnusedError>()("UnusedError", {
   message: Schema.String,
@@ -31,12 +32,12 @@ export const filesOf = Effect.fn("filesOf")(function* (stdout: string) {
 });
 
 export function report({ tracked, files }: Scan): string {
-  if (files.length === 0) return `${NAME}: no unreferenced files among ${tracked} tracked .ts/.tsx file(s)`;
+  if (files.length === 0) return `${NAME}: no unreferenced files among ${tracked} tracked .ts/.tsx/.astro file(s)`;
   return [`${NAME}: ${files.length} unreferenced file(s):`, ...files.map((file) => `  ${file}`)].join("\n");
 }
 
 const unused = Effect.gen(function* () {
-  const { tracked, reported } = yield* scanTree(NAME, ["--files"]).pipe(
+  const { tracked, reported } = yield* scanTree(NAME, ["--files"], LINTED_SOURCE).pipe(
     Effect.mapError((cause) => new UnusedError({ message: cause.message })),
   );
   if (reported.kind === "unconfigured") return false;

package/src/core/gates.ts

@@ -3,7 +3,7 @@ export type Program = {
   readonly script: string;
 };
 
-type TrackedContent = {
+export type TrackedContent = {
   readonly pathspecs: readonly string[];
   readonly content: string;
 };
@@ -30,20 +30,23 @@ export const TEST_ENTRY_POINT: Program = { bin: "checks-test", script: "testing/
 
 export const DEFAULT_BRANCH = "main";
 
-const TYPESCRIPT_SOURCE: TrackedContent = { pathspecs: ["*.ts", "*.tsx"], content: "TypeScript source" };
+export const TYPESCRIPT_SOURCE: TrackedContent = { pathspecs: ["*.ts", "*.tsx"], content: "TypeScript source" };
+
+export const LINTED_SOURCE: TrackedContent = { pathspecs: ["*.ts", "*.tsx", "*.astro"], content: "TypeScript or Astro source" };
 
 const BUN_LOCKFILE: TrackedContent = { pathspecs: ["bun.lock"], content: "a bun lockfile" };
 
 export const KIT_GATES = [
-  { bin: "checks-lint-coverage", vector: "quality", file: "lint-coverage.sh", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
+  { bin: "checks-lint-coverage", vector: "quality", file: "lint-coverage.sh", reads: "tree", appliesTo: LINTED_SOURCE },
   { bin: "checks-test-layout", vector: "testing", file: "test-layout.ts", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-commit-identity", vector: "delivery", file: "commit-identity.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-comment-gate", vector: "quality", file: "comment-gate.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-suppressions-ratchet", vector: "complexity", file: "suppressions-ratchet.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-ci-wiring", vector: "delivery", file: "ci-wiring.ts", reads: "tree", appliesTo: EVERY_REPOSITORY },
+  { bin: "checks-secrets", vector: "delivery", file: "secrets.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-docs", vector: "docs", file: "docs.ts", reads: "range", alsoReads: "every agent file at the head commit", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-repetition", vector: "complexity", file: "repetition.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
-  { bin: "checks-unused", vector: "complexity", file: "unused.ts", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
+  { bin: "checks-unused", vector: "complexity", file: "unused.ts", reads: "tree", appliesTo: LINTED_SOURCE },
   { bin: "checks-exports", vector: "complexity", file: "exports.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-quarantine-clock", vector: "testing", file: "quarantine-clock.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-advisories", vector: "dependencies", file: "advisories.ts", reads: "range", appliesTo: BUN_LOCKFILE },

package/src/delivery/commit-identity.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import { releasedVersionOf } from "./release.ts";
 import { git, refArgs } from "../core/git.ts";
 import { runMain } from "../core/main.ts";
 
@@ -20,6 +21,17 @@ const DEFAULT_AUTHORS: readonly Identity[] = [{ name: "avi2d", email: "avi2dg@gm
 // GitHub writes the squash commit, so it commits what the owner authored and never authors.
 const SQUASH_COMMITTER: Identity = { name: "GitHub", email: "noreply@github.com" };
 
+// checks-release-pr commits through the workflow token, which GitHub attributes to its Actions bot.
+// GitHub may also name that bot as co-author when it squashes the pull request the bot opened.
+const RELEASE_AUTHOR: Identity = { name: "github-actions[bot]", email: "41898282+github-actions[bot]@users.noreply.github.com" };
+
+const CO_AUTHOR = /^co-authored-by:\s*(.*?)\s*<([^<>]*)>\s*$/i;
+
+function namesReleaseAuthor(trailer: string): boolean {
+  const [, name, email = ""] = CO_AUTHOR.exec(trailer) ?? [];
+  return name !== undefined && allows([RELEASE_AUTHOR], { name, email });
+}
+
 // git's own trailer parser, so only the trailer block counts and prose never does.
 const CO_AUTHORED_BY_FORMAT = "%(trailers:key=Co-authored-by)";
 
@@ -113,13 +125,16 @@ function allows(allowed: readonly Identity[], identity: Identity): boolean {
 
 function inspect(commit: Commit, allowed: readonly Identity[]): Offence | undefined {
   const reasons: string[] = [];
-  if (!allows(allowed, commit.author)) {
+  const release = releasedVersionOf(commit.subject) !== undefined;
+  const authors = release ? [...allowed, RELEASE_AUTHOR] : allowed;
+  if (!allows(authors, commit.author)) {
     reasons.push(`author ${render(commit.author)}`);
   }
   if (!allows([...allowed, SQUASH_COMMITTER], commit.committer)) {
     reasons.push(`committer ${render(commit.committer)}`);
   }
   for (const trailer of commit.coAuthoredBy) {
+    if (release && namesReleaseAuthor(trailer)) continue;
     reasons.push(`trailer ${trailer}`);
   }
   return reasons.length === 0 ? undefined : { commit, reasons };
@@ -144,6 +159,7 @@ const check = Effect.gen(function* () {
     }
     lines.push(`  allowed: ${allowed.map(render).join(", ")}`);
     lines.push(`  allowed as committer only: ${render(SQUASH_COMMITTER)}`);
+    lines.push(`  allowed as release author only: ${render(RELEASE_AUTHOR)}`);
     yield* Console.error(lines.join("\n"));
     return false;
   }
@@ -152,4 +168,4 @@ const check = Effect.gen(function* () {
   return true;
 });
 
-runMain("commit-identity", check);
+if (import.meta.main) runMain("commit-identity", check);

package/src/delivery/github.ts

@@ -0,0 +1,38 @@
+import { Effect, Schema } from "effect";
+import { ChildProcessSpawner } from "effect/unstable/process";
+import { collect } from "../core/git.ts";
+
+export class GitHubFailure extends Schema.TaggedError<GitHubFailure>()("GitHubFailure", {
+  message: Schema.String,
+}) {}
+
+type Method = "GET" | "POST" | "PATCH";
+
+type Decode<A> = (text: string) => Effect.Effect<A, Schema.SchemaError>;
+
+// gh fills {owner} and {repo} from the checkout's remote, so a workflow names no repository.
+export const REPOSITORY = "repos/{owner}/{repo}";
+
+const gitHub = Effect.fn("gitHub")(function* (method: Method, path: string, body?: unknown) {
+  const failed = (reason: string): GitHubFailure => new GitHubFailure({ message: `gh api ${method} ${path}: ${reason.trim()}` });
+  const input = body === undefined ? [] : ["--input", "-"];
+  const feed = body === undefined ? {} : { input: JSON.stringify(body) };
+  const { stdout, stderr, exitCode } = yield* collect("gh", ["api", "--method", method, path, ...input], undefined, feed).pipe(
+    Effect.mapError((cause) => failed(cause.message)),
+  );
+  if (exitCode !== ChildProcessSpawner.ExitCode(0)) return yield* failed(stderr);
+  return stdout;
+});
+
+export function gitHubJson<A>(decode: Decode<A>, method: Method, path: string, body?: unknown): Effect.Effect<A, GitHubFailure, ChildProcessSpawner.ChildProcessSpawner> {
+  return gitHub(method, path, body).pipe(
+    Effect.flatMap((text) =>
+      decode(text).pipe(Effect.mapError((cause) => new GitHubFailure({ message: `gh api ${method} ${path} answered ${cause.message}` }))),
+    ),
+  );
+}
+
+// A dispatch is the one run a workflow token starts at once: GitHub starts none for the token's push, and holds its pull request's runs for approval.
+export const dispatch = Effect.fn("dispatch")(function* (workflow: string, ref: string) {
+  yield* gitHub("POST", `${REPOSITORY}/actions/workflows/${workflow}/dispatches`, { ref });
+});

package/src/delivery/gitleaks.toml

@@ -0,0 +1,113 @@
+title = "checks-secrets"
+
+[extend]
+useDefault = true
+
+[[rules]]
+id = "wireguard-key"
+description = "A WireGuard or AmneziaWG private or pre-shared key"
+regex = '''(?i)(?:private[_-]?key|pre[_-]?shared[_-]?key|psk)["']?[ \t]*[:=][ \t]*["']?([A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=)'''
+secretGroup = 1
+entropy = 3.0
+keywords = ["private", "preshared", "pre_shared", "pre-shared", "psk"]
+
+[[rules]]
+id = "wireguard-key-file"
+description = "A WireGuard or AmneziaWG key alone on a line of a file whose name says private, priv, pre-shared or psk"
+path = '''(?i)(?:^|/)[^/]*(?:priv|pre[_-]?shared|psk)[^/]*$'''
+regex = '''(?m)^[ \t]*([A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=)[ \t]*\r?$'''
+secretGroup = 1
+entropy = 3.0
+
+[[rules]]
+id = "wireguard-dot-key-file"
+description = "A WireGuard or AmneziaWG key alone on a line of a .key file not named for a public key"
+path = '''(?i)\.key$'''
+regex = '''(?m)^[ \t]*([A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=)[ \t]*\r?$'''
+secretGroup = 1
+entropy = 3.0
+
+[[rules.allowlists]]
+description = "A .key file named for a public key"
+paths = ['''(?i)pub(?:lic)?\.key$''']
+
+[[rules]]
+id = "proxy-userinfo-link"
+description = "A proxy share link that carries its credential before the @, such as vless://, trojan://, socks5:// or wireguard://"
+regex = '''(?i)\b(?:vless|vmess|ss|trojan|hysteria2?|hy2|tuic|socks5?h?|wireguard|wg)://([^\s"'`<>@?#]+)@[^\s"'`<>]+'''
+secretGroup = 1
+entropy = 2.5
+keywords = ["vless://", "vmess://", "ss://", "trojan://", "hysteria://", "hysteria2://", "hy2://", "tuic://", "socks://", "socksh://", "socks5://", "socks5h://", "wireguard://", "wg://"]
+
+[[rules.allowlists]]
+description = "A link to a reserved example or test host"
+regexTarget = "match"
+regexes = ['''^(?i)[a-z0-9]+://(?:[^\s"'`@?#]*@)?(?:[\w-]+\.)*(?:example\.(?:com|net|org)|[\w-]+\.(?:example|invalid|test)|localhost)(?::\d+)?(?:[/?#]|$)''']
+
+[[rules]]
+id = "proxy-base64-link"
+description = "A proxy share link whose whole payload is base64, such as vmess://, ss:// or ssr://"
+regex = '''(?i)\b(?:vmess|ssr?)://([A-Za-z0-9+/_-]{16,}={0,2})@?'''
+secretGroup = 1
+entropy = 4.2
+keywords = ["vmess://", "ss://", "ssr://"]
+
+[[rules.allowlists]]
+description = "A payload an @ follows, which proxy-userinfo-link judges"
+regexTarget = "match"
+regexes = ['''@$''']
+
+[[rules]]
+id = "proxy-query-credential-first"
+description = "The first auth, auth_str, obfsParam, obfs-password, password or pk query parameter of a proxy share link, such as hysteria://host?auth="
+regex = '''(?i)\b(?:vless|vmess|ssr?|trojan|hysteria2?|hy2|tuic|socks5?h?|wireguard|wg)://[^\s"'`?#]*\?(?:[^\s"'`#]*?&)??(?:auth|auth_str|obfsParam|obfs-password|password|pk)=([^\s"'`<>&#]+)'''
+secretGroup = 1
+entropy = 2.5
+keywords = ["vless://", "vmess://", "ss://", "ssr://", "trojan://", "hysteria://", "hysteria2://", "hy2://", "tuic://", "socks://", "socksh://", "socks5://", "socks5h://", "wireguard://", "wg://"]
+
+[[rules.allowlists]]
+description = "A link to a reserved example or test host"
+regexTarget = "match"
+regexes = ['''^(?i)[a-z0-9]+://(?:[^\s"'`@?#]*@)?(?:[\w-]+\.)*(?:example\.(?:com|net|org)|[\w-]+\.(?:example|invalid|test)|localhost)(?::\d+)?(?:[/?#]|$)''']
+
+[[rules]]
+id = "proxy-query-credential-last"
+description = "The last auth, auth_str, obfsParam, obfs-password, password or pk query parameter of a proxy share link, such as hysteria://host?auth="
+regex = '''(?i)\b(?:vless|vmess|ssr?|trojan|hysteria2?|hy2|tuic|socks5?h?|wireguard|wg)://[^\s"'`?#]*\?(?:[^\s"'`#]*&)?(?:auth|auth_str|obfsParam|obfs-password|password|pk)=([^\s"'`<>&#]+)'''
+secretGroup = 1
+entropy = 2.5
+keywords = ["vless://", "vmess://", "ss://", "ssr://", "trojan://", "hysteria://", "hysteria2://", "hy2://", "tuic://", "socks://", "socksh://", "socks5://", "socks5h://", "wireguard://", "wg://"]
+
+[[rules.allowlists]]
+description = "A link to a reserved example or test host"
+regexTarget = "match"
+regexes = ['''^(?i)[a-z0-9]+://(?:[^\s"'`@?#]*@)?(?:[\w-]+\.)*(?:example\.(?:com|net|org)|[\w-]+\.(?:example|invalid|test)|localhost)(?::\d+)?(?:[/?#]|$)''']
+
+[[rules]]
+id = "proxy-subscription-url"
+description = "A proxy subscription URL whose path or query carries its token"
+regex = '''(?i)(?:\bhttps?://[^\s"'`<>/]+/(?:[^\s"'`<>?]*/)?(?:sub|subs|subscribe|subscription|link)/|[?&](?:token|key|uuid|id)=)([A-Za-z0-9_-]{16,})'''
+secretGroup = 1
+entropy = 3.0
+keywords = ["sub", "link"]
+
+[[rules.required]]
+id = "proxy-subscription-path"
+withinLines = 0
+
+[[rules]]
+id = "proxy-subscription-path"
+description = "An http or https URL whose last path segment before its token or query is sub, subs, subscribe, subscription or link"
+regex = '''(?i)\bhttps?://[^\s"'`<>/]+/(?:[^\s"'`<>?]*/)?(?:sub|subs|subscribe|subscription|link)[/?]'''
+keywords = ["sub", "link"]
+skipReport = true
+
+[[rules.allowlists]]
+description = "A link to a reserved example or test host"
+regexTarget = "match"
+regexes = ['''^(?i)https?://(?:[\w-]+\.)*(?:example\.(?:com|net|org)|[\w-]+\.(?:example|invalid|test)|localhost)(?:[:/?#]|$)''']
+
+[[allowlists]]
+description = "A link credential that is only template references, such as {password}, ${pass}, ${encodeURIComponent(pass)}, ${pass:-}, ${pass:?message}, $PASS, {{ password }} or %(password)s, with a user part that is one too; a last ${...} may be cut short, and one that gives a default or alternative value, such as ${pass:-value}, is not a reference"
+targetRules = ["proxy-userinfo-link", "proxy-query-credential-first", "proxy-query-credential-last"]
+regexes = ['''^(?:(?:\$\{(?:[^A-Za-z_}][^}]*|[A-Za-z_][\w.]*(?:[^\w.:=+}-][^}]*|:(?:[^-=+}][^}]*)?|:?[-=+])?)?\}|\$[A-Za-z_]\w*|\{\{\s*[A-Za-z_][\w.]*\s*\}\}|\{[A-Za-z_][\w.]*\}|%\([A-Za-z_][\w.]*\)s):)?(?:\$\{(?:[^A-Za-z_}][^}]*|[A-Za-z_][\w.]*(?:[^\w.:=+}-][^}]*|:(?:[^-=+}][^}]*)?|:?[-=+])?)?\}?|\$[A-Za-z_]\w*|\{\{\s*[A-Za-z_][\w.]*\s*\}\}|\{[A-Za-z_][\w.]*\}|%\([A-Za-z_][\w.]*\)s)$''']