@avi2dg/checks 0.12.0 → 0.14.0

package/dist/feature-rules.js

@@ -17,6 +17,7 @@ var KIT_GATES = [
   { bin: "checks-comment-gate", script: "comment-gate.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-suppressions-ratchet", script: "suppressions-ratchet.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-ci-wiring", script: "ci-wiring.ts", reads: "tree", appliesTo: EVERY_REPOSITORY },
+  { bin: "checks-docs", script: "docs.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-quality", script: "quality.ts", reads: "tree", args: ["--check"], appliesTo: QUALITY_DECLARATION },
   { bin: "checks-size-budget", script: "size-budget.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-feature-owners", script: "feature-owners.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE }
@@ -123,6 +124,17 @@ var AgentRules = Schema2.Struct({
   const both = on.filter((rule) => off.includes(rule));
   return both.length === 0 || `switches ${both.join(", ")} both on and off`;
 }));
+var pagesIn = (mode) => Schema2.optionalKey(Schema2.Array(PathGlob).annotate({ description: `The pages written as ${mode}` }));
+var Docs = Schema2.Struct({
+  pages: Schema2.optionalKey(Schema2.Struct({
+    tutorial: pagesIn("a tutorial, which teaches by building one thing"),
+    "how-to": pagesIn("a how-to, which walks one task"),
+    reference: pagesIn("reference, which describes a thing to be looked up"),
+    explanation: pagesIn("an explanation, which says why")
+  }).annotate({
+    description: "The Diátaxis mode of each page, whose template checks-docs holds the page to; a page under docs/ needs one"
+  }))
+});
 var Quality = Schema2.Struct({
   $schema: Schema2.optionalKey(Schema2.String),
   defaultBranch: Schema2.optionalKey(Schema2.NonEmptyString.annotate({ description: "The branch pull requests merge into; main when absent" })),
@@ -136,7 +148,8 @@ var Quality = Schema2.Struct({
   changeSignal: Schema2.optionalKey(Schema2.Literal("advisory").annotate({
     description: "Report which feature owners a change touches, without failing on it"
   })),
-  agentRules: Schema2.optionalKey(AgentRules)
+  agentRules: Schema2.optionalKey(AgentRules),
+  docs: Schema2.optionalKey(Docs.annotate({ description: "What checks-docs reads to map a doc file to its template" }))
 }).annotate({
   title: QUALITY_FILE,
   description: "What a repository has opted into from @avi2dg/checks, read by its bins and agent Rule selection"

package/docs/configs/commit-messages.md

@@ -0,0 +1,43 @@
+# The commit message lint
+
+The shared commitlint config holds each pull request title to conventional commits, and a reader looks it up to wire the lint into a repository's CI.
+
+## Config
+
+Commits follow `@commitlint/config-conventional` plus the house prefixes `commitlint.config.js` lists, shared from `@avi2dg/checks/commitlint.config.js`.
+It arrives with the kit, since `@commitlint/cli` and `@commitlint/config-conventional` are dependencies, not peers.
+
+## Workflow
+
+The lint runs in CI on pull requests, because `jj` never fires a git hook.
+A repository adds this workflow:
+
+```yaml
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+jobs:
+  commitlint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: printf '%s' "$PR_TITLE (#0000)" > "$RUNNER_TEMP/pr-title"
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+      - run: ./node_modules/.bin/commitlint --config ./node_modules/@avi2dg/checks/commitlint.config.js --edit "$RUNNER_TEMP/pr-title"
+```
+
+## What it lints
+
+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.
+
+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.
+
+## Related topics
+
+- [checks-commit-identity](../gates/checks-commit-identity.md)

package/docs/configs/dependency-rules.md

@@ -0,0 +1,62 @@
+# The dependency rules
+
+The shared dependency-cruiser base holds a repository's imports to a set of rules every repository shares, and a reader looks it up to add a boundary of its own.
+
+## Base rules
+
+`.dependency-cruiser.cjs` extends the shared base, which carries these rules:
+
+- `no-circular`
+- `no-orphans`
+- `not-to-dev-dep`, which refuses shipped source importing a dev-only package, and a package listed in `peerDependencies` too is not dev-only
+- `not-to-unresolvable`, which refuses a specifier nothing installed answers
+- `no-deep-imports`, which refuses a subpath the package's exports map does not publish
+
+The base parses with swc, so it needs `@swc/core` installed, and without it the cruise silently skips every `.ts` file.
+
+## Boundaries
+
+A repository appends a named rule per boundary it owns:
+
+```js
+module.exports = {
+  extends: "./node_modules/@avi2dg/checks/dependency-cruiser.config.js",
+  forbidden: [
+    {
+      name: "ui-cannot-reach-server",
+      severity: "error",
+      from: { path: "^src/ui" },
+      to: { path: "^src/server" },
+    },
+  ],
+};
+```
+
+A rule that restates a base name overrides it field by field.
+That is how an entry point stops being an orphan: redeclare `no-orphans` with the entry added to its `pathNot`.
+A repository that declares feature owners spreads the rules `quality.json` compiles to into the same `forbidden`, as [checks-feature-owners](../gates/checks-feature-owners.md#import-boundary) says.
+
+## Running it
+
+`package.json` gains the script:
+
+```json
+"lint:deps": "depcruise --config .dependency-cruiser.cjs src"
+```
+
+CI runs it beside the other checks:
+
+```yaml
+jobs:
+  lint:
+    steps:
+      - uses: actions/checkout@v5
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bun run lint:deps
+```
+
+## Related topics
+
+- [checks-feature-owners](../gates/checks-feature-owners.md)
+- [Why it is shaped this way](../design.md)

package/docs/configs/effect-rules.md

@@ -0,0 +1,48 @@
+# The Effect rules
+
+The oxlint base config and the tsconfig fragment hold a repository's Effect code to its error channel and to Effect-native IO, and a reader looks them up to learn what each rule refuses and how a path opts in.
+
+## Base config
+
+The base config, `oxlintrc.json`, loads the `effect-channel` plugin and turns on `effect-channel/no-error-channel-escape`.
+That rule refuses `Effect.ignore`, `Effect.ignoreCause`, the `Effect.catchCause` family, and an `Effect.catch` whose handler takes no error or names it `_`.
+
+Two more rules ship off, because a repository writes only some of its paths in Effect, and code a host loads without `node_modules`, such as a hook bundle or this oxlint plugin, cannot import it:
+
+- `effect-channel/no-throw` refuses a `throw` statement.
+- `effect-channel/no-try-catch` refuses a `try` statement with a `catch` clause, and `try`/`finally` stays allowed.
+
+Each refusal says what to write instead: a `Schema.TaggedError` failed through `Effect.fail`, a throwing call wrapped in `Effect.try` or `Effect.tryPromise`, and recovery by tag with `Effect.catchTag`.
+
+## Effect paths
+
+A repository turns the rules on for the paths it writes in Effect by declaring those paths in `quality.json` and extending the fragments [checks-quality](../gates/checks-quality.md) generates:
+
+```json
+"sources": {
+  "effect": { "paths": ["src/**/*.ts"], "exempt": ["src/host/*.ts"] }
+}
+```
+
+The fragment's override carries the kit's Effect rule block, `presets/effect.oxlint.json`.
+It holds the two rules above, plus `node/no-sync`, `oxc/no-async-await`, `promise/avoid-new` and `unicorn/no-process-exit`.
+Files under `exempt` answer to none of them.
+
+oxlint resolves `files` against the directory of the config that holds the override, so a config passed with `-c` from outside the repository matches nothing and reports nothing.
+
+`unicorn/no-process-exit` passes over any file that opens with a shebang.
+A repository whose bins open with one bans `process.exit` itself with `no-restricted-properties` in its own `.oxlintrc.json`, as the kit's own repository does.
+The preset leaves that rule out because a repository's own `no-restricted-properties` list for the same files would replace it, or be replaced by it.
+Sites standing when the declaration lands go in oxlint's own baseline, `oxlint --suppress-all`, so their count can only fall, as [checks-suppressions-ratchet](../gates/checks-suppressions-ratchet.md) holds.
+
+## Language service
+
+The language service holds the same paths to Effect-native IO through the tsconfig fragment's override, whose severities are `presets/effect.language-service.json`.
+`nodeBuiltinImport`, `asyncFunction`, `newPromise` and `extendsNativeError` are all errors.
+effect-tsgo keeps the severities `tsconfig.effect.json` sets when a later config in `extends` restates the plugin with only its overrides.
+
+## Related topics
+
+- [checks-quality](../gates/checks-quality.md)
+- [The quality file](quality-file.md)
+- [Why it is shaped this way](../design.md)

package/docs/configs/quality-file.md

@@ -0,0 +1,99 @@
+# The quality file
+
+`quality.json` at the repository root says what the repository has opted into, and a reader looks it up to learn what each key holds and which bin reads it.
+
+## Keys
+
+The kit's bins find the file at the git root and read it there:
+
+```json
+{
+  "$schema": "./node_modules/@avi2dg/checks/quality.schema.json",
+  "defaultBranch": "main",
+  "gates": {
+    "ci": ["bun run lint", "bun run typecheck", "bun run test"],
+    "scheduled": ["bunx checks-flake --runs 10 --report flake-report.json"]
+  },
+  "commitIdentity": { "authors": [{ "name": "avi2d", "email": "avi2dg@gmail.com" }] },
+  "sources": {
+    "production": ["src/**/*.ts"],
+    "effect": { "paths": ["src/**/*.ts"], "exempt": ["src/host/*.ts"] }
+  },
+  "size": { "fileLines": 400, "functionLines": 100, "applies": "changed" },
+  "features": [
+    {
+      "name": "billing",
+      "root": "src/billing",
+      "entries": ["src/billing/index.ts"],
+      "allowFrom": ["src/main.ts"],
+      "proof": "tests/e2e/billing.test.ts"
+    }
+  ],
+  "changeSignal": "advisory",
+  "agentRules": { "on": [], "off": [] },
+  "docs": { "pages": { "reference": ["docs/gates/*.md"], "explanation": ["docs/design.md"] } }
+}
+```
+
+<!-- generated quality-keys: bun run build writes it from Quality in scripts/quality-file.ts and scripts/doc-blocks.ts -->
+
+| Key | Read by | Holds |
+| --- | --- | --- |
+| `defaultBranch` | `checks-lint`, `checks-ci-wiring` | the branch pull requests merge into, `main` when absent |
+| `gates.ci` | `checks-ci-wiring` | the commands CI runs on every pull request, as [checks-ci-wiring](../gates/checks-ci-wiring.md) says |
+| `gates.scheduled` | `checks-ci-wiring` | the commands a schedule runs |
+| `gates.lint` | `checks-lint`, `checks-ci-wiring` | the gates `checks-lint` runs when not all apply, as [Gate selection](../gates/checks-lint.md#gate-selection) says |
+| `commitIdentity.authors` | `checks-commit-identity` | the identities allowed to author and commit, as [checks-commit-identity](../gates/checks-commit-identity.md) says |
+| `sources.production` | `checks-size-budget`, `checks-quality` | the source the repository ships, as [checks-size-budget](../gates/checks-size-budget.md) says |
+| `sources.effect` | `checks-quality` | the paths held to the Effect rules, and the files under them that are not, as [The Effect rules](effect-rules.md) says |
+| `size` | `checks-size-budget` | the line budget, and which production files it holds |
+| `features` | `featureRules`, `checks-feature-owners` | each feature's root, entries, exempt importers and proof, as [checks-feature-owners](../gates/checks-feature-owners.md) says |
+| `changeSignal` | `checks-feature-owners` | `advisory` to list the feature owners a change touches |
+| `agentRules.on` | agent Rule selection, not the kit | catalogued Rules switched on for this repository |
+| `agentRules.off` | agent Rule selection, not the kit | catalogued Rules switched off for this repository |
+| `docs.pages` | `checks-docs` | the Diátaxis mode of each page, by glob, as [checks-docs](../gates/checks-docs.md) says |
+
+<!-- end generated quality-keys -->
+
+Every key is optional.
+
+## Schema
+
+The bins decode the file with one Effect `Schema`, and the package ships `quality.schema.json` emitted from that schema.
+The `$schema` line therefore gives an editor the verdict the bins reach, save what no JSON Schema can express across two values, which the bins refuse:
+
+- a Rule switched both on and off
+- a feature entry outside its root
+- two features with one name or sharing a root
+
+A key the schema does not name is refused, not ignored, so a misspelt `sources` cannot switch the Effect rules off unnoticed.
+
+## Globs
+
+A glob in `sources` starts at the repository root, names a directory first, uses `*` only within a segment and `**` only as a whole one, and ends in a file name with an extension.
+Those are the globs oxlint, the language service and git all read alike.
+oxlint matches `*.ts` at any depth where the other two match it at the root alone, so the schema refuses it, and `**/*.ts` means every depth to all three.
+The language service matches nothing for `src/**` and oxlint nothing for `src/lib`, so the schema refuses both, and `src/**/*.ts` and `src/lib/*.ts` say it to all three.
+
+## Keys moved from package.json
+
+A repository with no `quality.json` still has `ciWiring` and `commitIdentity` read from `package.json`, with a notice on each read.
+One with both files exits 2 until `package.json` drops them.
+The keys map one for one:
+
+<!-- generated legacy-keys: bun run build writes it from LegacyManifest in scripts/quality-file.ts, QUALITY_FILE in scripts/gates.ts and scripts/doc-blocks.ts -->
+
+| `package.json` | `quality.json` |
+| --- | --- |
+| `ciWiring.gates` | `gates.ci` |
+| `ciWiring.scheduled` | `gates.scheduled` |
+| `ciWiring.lintGates` | `gates.lint` |
+| `ciWiring.defaultBranch` | `defaultBranch` |
+| `commitIdentity` | `commitIdentity` |
+
+<!-- end generated legacy-keys -->
+
+## Related topics
+
+- [checks-quality](../gates/checks-quality.md)
+- [Why it is shaped this way](../design.md)

package/docs/design.md

@@ -0,0 +1,77 @@
+# Why it is shaped this way
+
+Each entry below is a choice in the kit's shape and the constraint that forced it.
+
+- Every config in an oxlint `extends` chain brings its own `plugins`, and one that sets none brings oxlint's default plugins, whose category rules the base's `categories` then turn on across the tree.
+  `rules`, `categories` and `jsPlugins` inherit as expected.
+  That is why the consumer snippet restates `plugins` and nothing else, and why the generated fragment always sets them.
+- `node_modules/` is excluded through the consumer's `.gitignore`, not `ignorePatterns`: oxlint still walks the installed package when only `ignorePatterns` names it.
+- `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`.
+  Node refuses to type-strip a `.ts` plugin under `node_modules`, so the `.ts` source would fail to load from an installed package.
+- `featureRules` ships compiled as `dist/feature-rules.js` for the same reason, with `effect` left out of the bundle so it resolves the consumer's own copy.
+  dependency-cruiser uses a config's export as it is and never awaits it, so the declaration decodes synchronously, and `quality.json` exempts that one file from the Effect rules.
+- `checks-size-budget` writes the head commit's files to a temporary directory and runs oxlint there, with a configuration that sets no plugin and turns every category off, so the consumer's own `.oxlintrc.json`, its ignore files and its other rules never reach the count.
+- `dist/` is committed.
+  No `prepack` or `prepublishOnly` builds it, so a publish ships whatever bundle the publishing worktree holds.
+  Rebuild it after pulling with `bun run build`.
+  `bun run build` also emits `quality.schema.json`, `templates/` and `CHANGELOG.md`, which are committed the same way.
+  CI runs `git diff --exit-code` over the whole tree after the build, because a test that compares a generated file with its source passes on the copy the build just rewrote.
+- `CHANGELOG.md` is generated, so a release commit carries it and the tarball ships it.
+  The commit that bumps package.json `version` closes its release, and the `v*` tag goes on that commit, so commits merged after it wait for the next release.
+  Releases come from the commits, over all of HEAD's ancestry, so a checkout without tags, a fork and a branch that merged `main` in write the same file.
+  A bump not newer than the release before it is a revert: it cancels every release above the version it returns to, and a tag only keeps a reverted release that was already published.
+  The committed changelog is the record of what was released: a version older than the newest it lists and absent from it was never published, and its commits go into the next release.
+  A section keeps the date it was written with, since the squash merge that lands the release commit may fall on another day.
+  Entries come from commit subjects, the squash-merged pull request titles commitlint holds to the conventional format; the bodies are the branch's own messages, which nothing lints.
+  The release path needs no `contents: write`: the changelog arrives in the release commit's pull request, not from a workflow that pushes.
+- `quality.json` is JSON, not TOML or a TypeScript module: a bun bin, a hook running without `node_modules`, a `.cjs` or `.mjs` config and `jq` all parse it with nothing installed, and nobody runs a repository's own code to learn its policy.
+  It holds declarations only.
+  The kit's bins read it directly.
+  oxlint and tsc read nothing but their own JSON, so they extend generated fragments, which `checks-quality --check` holds to the declarations.
+- `quality.json` refuses a key its schema does not name, so a kit that cannot enforce a newer key refuses it rather than let the repository believe it enforced.
+- The base parses with swc because typescript 7, which is tsgo, has no compiler API for dependency-cruiser to use.
+  Without `@swc/core` installed the cruise silently skips every `.ts` file, so this repo's test asserts its own TypeScript is cruised.
+- `bunfig.toml` has no `extends` and no include: bun ignores an unknown top-level key in silence, so a preset cannot be inherited and the consumer's copy is compared key by key against the installed one instead.
+  `[test] pathIgnorePatterns` is a real bunfig key, and an empty `--path-ignore-patterns` flag overrides the file's own list.
+- The Stryker preset is a JavaScript module, not JSON: Stryker 10 does not resolve `extends` in a JSON config, but a `.mjs` config that spreads an imported object consumes it.
+  Keys the consumer sets after the spread win.
+- The `.ts` bins are written in Effect, so `effect` is a peer dependency and `@effect/platform-bun`, which only the bins use, is a dependency.
+  `@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.
+- `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.
+- A gate selection is checked against the repository's contents rather than trusted, so it cannot skip a gate that applies.
+  ci-wiring does that check, which is why a selection without it, or without another gate that applies everywhere, is refused as `checks-lint` reads it: nothing would check the selection otherwise.
+- `checks-test` runs bun itself rather than reading a report some other run left: a skip taken only on CI is visible only in CI's own run, and an earlier run's report may be stale or narrowed.
+  It reads the JUnit report bun writes to a temporary directory, since bun has no other per-test output meant for a program.
+- `checks-ci-wiring` runs inside `lint`, not in a workflow of its own: deleting the step that runs a check is the violation it catches, so the local `lint` is where it has to fail.
+- Workflows are parsed with `Bun.YAML`, which the `bun` shebang already provides, so the check adds no dependency.
+  It reads `on` as a string key, not as the YAML 1.1 boolean.
+- `bun` counts as a built-in module.
+  Nothing installed resolves it except `@types/bun`, which would otherwise make every runtime `bun` import look like a dev-only dependency.
+- The pull request merge commit GitHub builds is authored by `GitHub <noreply@github.com>`, which commit-identity refuses as an author.
+  `checks-lint` ends a pull request's range at the event's head sha, so the merge commit is never in it.
+  A `lint` that calls `checks-commit-identity HEAD` itself checks out `github.event.pull_request.head.sha` instead of the default merge ref.
+- `no-deep-imports` judges the import specifier, never the resolved file.
+  The base honours `exports` maps, so a subpath the map publishes resolves and passes, one it omits fails to resolve and is reported, and a package without an `exports` map publishes every file.
+  A bare import always passes whatever file its entry lives in.
+  Setting your own `options.enhancedResolveOptions` replaces the base's, so restate `exportsFields` and `conditionNames` if you do.
+- dependency-cruiser `extends` merges same-name `forbidden` rules with the child's fields winning.
+  That is the entry-point and layer recipe under Boundaries in [The dependency rules](configs/dependency-rules.md).
+- The templates in `templates/` are rendered from `scripts/doc-templates.ts`, the spec `checks-docs` reads.
+  A template written by hand beside the check agrees with it only until someone edits one of them.
+- A page's Diátaxis mode is declared in `quality.json` rather than read from the page.
+  Whether a page teaches, walks a task, describes or explains is a judgment no program makes, so the repository states it once and the check holds the page to it.
+- `checks-docs` holds a doc file to its template when a change touches it, the way `checks-size-budget` holds a file to its budget.
+  A repository adopts the templates as its files change, and an untouched file is listed as advisory rather than failing a change that never read it.
+- A task heading is verb first, and review holds it there rather than the check.
+  No word list tells `Test layout` from `Test the layout`, and a check that passes the noun is worse than none.
+
+## Related topics
+
+- [checks](../README.md)

package/docs/gates/checks-backtest.md

@@ -0,0 +1,50 @@
+# checks-backtest
+
+`checks-backtest` is the report of what the comment check would have refused at each recent commit, and a reader looks it up to measure a repository's own history before adopting the check.
+
+## What it checks
+
+It checks nothing and fails nothing.
+It walks recent first-parent commits, prints a row per commit that touches code and then the totals, attributes only the refusals each commit introduced, and counts new comment text as a share of added lines.
+A row holds the commit, its added lines, its added comment lines, its refusals and its subject.
+Each commit that introduced a refusal is then listed with its refusals.
+
+## What it reads
+
+It reads each commit and its first parent, and the files each commit changes that have a comment syntax in `scripts/comment-matchers.ts`.
+`generated/`, `vendor/`, `repos/`, `node_modules/` and `dist/` are out of reach, so the figures are authored code.
+
+## Arguments
+
+```sh
+checks-backtest [commit-count]
+```
+
+`commit-count` is the number of first-parent commits it walks, 60 when absent.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | the report printed |
+| 2 | it is given more than one argument, or git cannot read the history, as with a count git refuses |
+
+## Sample output
+
+```
+fe12189	9	0	0	feat(scripts): hold CONTRIBUTING.md to the how-to template
+086bdd0	1205	1	0	feat(scripts): add checks-docs gate holding doc files to s
+dc23b30	21	1	0	fix: release 0.12.0 and read local exports in checks-featu
+bcb4e3b	1252	4	0	feat(scripts): add size budget, feature-owner rules and ch
+4 commits touching code, 2487 added lines
+comment lines added: 6 (0.2% of added lines)
+refusals introduced: 0
+```
+
+## Opting out
+
+Nothing runs it but a person who wants the figures.
+
+## Related topics
+
+- [checks-comment-gate](checks-comment-gate.md)

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

@@ -0,0 +1,122 @@
+# checks-ci-wiring
+
+`checks-ci-wiring` is the gate that fails when a command the repository's CI must run no longer runs on pull requests to the default branch, and a reader looks it up to learn which workflow step counts.
+
+## What it checks
+
+No local check sees a gate drop out of CI, since a workflow whose lint step became a no-op leaves `bun run lint` green.
+The repository declares its gates once, in `quality.json`:
+
+```json
+"gates": {
+  "ci": ["bun run lint", "bun run typecheck", "bun run test"]
+}
+```
+
+It looks, for each gate, for a `run:` step that is the gate command alone on one line, optionally followed by plain arguments.
+Plain arguments are words, quoted strings, and `$VAR` or `${VAR}` expansions.
+`bun run lint --quiet` and `bunx checks-comment-gate "origin/$BASE_REF" "$HEAD_SHA"` count.
+`bun run lint:deps`, `echo bun run lint` and a step `name:` do not.
+
+A step never counts when its script has a second line or any of these, because each can run the gate without its failure failing the step:
+
+- `|`, `||`, `&&`, `;` or `&`
+- `$(...)` or backticks
+- `<` or `>` redirection
+- a comment
+- a leading `NAME=value`
+
+The report names such a gate and says to give it its own step with nothing else in it.
+A gate step counts only when all of these hold:
+
+- Its workflow triggers on `pull_request`.
+  Any `branches` or `branches-ignore` filter there keeps the default branch, any `types` filter keeps `opened` and `synchronize`, and it sets no `paths` or `paths-ignore` filter, which would let some pull requests skip the gate.
+- Neither the step nor its job sets `if: false` or `continue-on-error: true`, bare or as `${{ false }}` and `${{ true }}`.
+- Its job needs no job, directly or through a chain, that sets `if: false`, unless a job on that chain has an `if:` calling `always()`, `failure()` or `cancelled()`.
+  GitHub prefixes every other `if:`, including `true` and `success()`, with `success()`, so a job whose needed job was skipped is skipped too.
+
+A job calling a local reusable workflow, such as `uses: ./.github/workflows/x.yml`, passes its own trigger and `if:` down to the called workflow's steps.
+A remote reusable workflow, such as `uses: owner/repo/...@ref`, is not a supported way to wire a gate.
+It is not read, so a gate must run as a `run:` step in the repository's own workflows, such as `bunx checks-comment-gate`.
+
+A step running `checks-lint` also counts for a declared gate that calls one of the gates `checks-lint` runs by its bare bin name, when the step calls `checks-lint` the same way.
+`bunx checks-lint` counts for `bunx checks-comment-gate "origin/$BASE_REF" "$HEAD_SHA"`.
+A step running `bun run lint` counts only for the `bun run lint` gate, since the check never reads what a package script runs.
+So once `lint` runs `checks-lint`, the per-gate entries can leave `gates.ci` along with the workflows that ran them.
+
+A command a schedule must run, such as the flake run, goes in `gates.scheduled`:
+
+```json
+"gates": {
+  "ci": ["bun run lint", "bun run typecheck", "bun run test"],
+  "scheduled": ["bunx checks-flake --runs 10 --report flake-report.json"]
+}
+```
+
+Each counts only as a step of the same plain shape in a workflow whose `on` carries `schedule` with at least one `cron`, under the same `if: false`, `continue-on-error: true` and `needs` rules as a gate.
+
+It also checks `gates.lint`, as [Gate selection](checks-lint.md#gate-selection) says.
+
+## What it reads
+
+It reads the working tree: `quality.json` for `defaultBranch`, `gates.ci`, `gates.scheduled` and `gates.lint`, and every `.github/workflows/*.yml` and `*.yaml`.
+The default branch is `main` when `quality.json` declares none.
+It parses each workflow with `Bun.YAML` and never runs it.
+
+## Arguments
+
+It takes none.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | every declared command runs where it must |
+| 1 | a gate does not run on pull requests to the default branch, a scheduled command runs on no schedule, or `gates.lint` leaves out a gate that applies |
+| 2 | `quality.json` declares no `gates.ci` or does not decode, a gate or scheduled command is not one plain command, or a workflow does not parse |
+
+Whether a workflow is well formed is actionlint's question, not this one's.
+
+## Sample output
+
+It names each gap, with every step that runs the gate and why that step does not count:
+
+```
+ci-wiring: 1 of 8 gate(s) do not run on pull requests to main:
+  bun run lint
+    .github/workflows/release.yml job publish step 7: .github/workflows/release.yml does not trigger on pull_request
+```
+
+It names each scheduled command no schedule runs:
+
+```
+ci-wiring: 1 of 1 scheduled command(s) do not run on a schedule:
+  bunx checks-flake --runs 10 --report flake-report.json
+    .github/workflows/ci.yml job checks step 5: .github/workflows/ci.yml does not trigger on a schedule
+```
+
+## Opting out
+
+It applies to every repository, so no selection leaves it out.
+It runs inside `lint`, through `checks-lint`, because deleting the step that runs a check is the violation it catches:
+
+```json
+"scripts": {
+  "lint": "oxlint --type-aware && checks-lint"
+}
+```
+
+## Limits
+
+The check reads workflow files and never runs them, so it deliberately does not evaluate these:
+
+- an `if:` expression other than a constant `true` or `false`, which counts as running
+- a `strategy.matrix` `include` or `exclude`, so a matrix that drops every combination still counts as running its steps
+- a remote reusable workflow, whose steps are never read
+- anything that happens at run time on the runner, such as what the gate command itself does, the shell's options, and a step or job that fails or times out before the gate step
+
+## Related topics
+
+- [checks-lint](checks-lint.md)
+- [checks-flake](checks-flake.md)
+- [The quality file](../configs/quality-file.md)

package/docs/gates/checks-comment-gate.md

@@ -0,0 +1,58 @@
+# checks-comment-gate
+
+`checks-comment-gate` is the gate that refuses a banned comment on a line a change adds, and a reader looks it up to learn which comments it refuses.
+
+## What it checks
+
+It fails when an added line carries a banned comment.
+It refuses a machine-read directive, a record or ticket pointer, a doc block, and a file opening with a rationale block over three lines, licence headers excepted.
+Each refusal says what to write instead.
+Only added lines are checked, so a violation in a file the diff never touches stays silent.
+A refusal counts when any line of the comment carrying it was added.
+
+## What it reads
+
+It reads the diff between two commits, and the added lines of each file whose extension has a comment syntax in `scripts/comment-matchers.ts`.
+It passes over a file with any other extension.
+
+`scripts/comment-matchers.ts` holds the scanner, the comment syntaxes and a synchronous `refused()`, and imports nothing.
+A host such as a hook bundle can therefore copy it alone into a directory with no `node_modules` and import it as `@avi2dg/checks/scripts/comment-matchers.ts`.
+The kit's own dependency cruise fails when that file gains an import.
+`scripts/comments.ts` wraps the same matchers in Effect for the gate and for [checks-backtest](checks-backtest.md).
+
+## Arguments
+
+```sh
+checks-comment-gate <base-ref> <head-ref>
+checks-comment-gate <ref>
+```
+
+With two arguments it diffs the base against the head.
+With one it diffs that commit against its parent, or against the empty tree for a repository's first commit, which has none.
+A shallow checkout running the one-argument form needs `fetch-depth: 2`.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | no added line carries a refused comment |
+| 1 | an added line carries a refused comment |
+| 2 | a ref does not resolve, or the parent exists but is not in the clone, which it refuses rather than widening to the whole tree |
+
+## Sample output
+
+```
+comment-gate: 2 violation(s):
+  src/a.ts:1 points at a record or a ticket ("#41"). Drop the pointer: a record is reached by searching docs/adr, and the story of the change goes in the commit message
+  src/a.ts:2 carries the machine-read directive `eslint-disable-next-line`. Fix what the tool is reporting, or stop running the tool on this file
+```
+
+## Opting out
+
+It applies to every repository, so no selection leaves it out.
+`checks-lint` runs it over each pull request's range, as [checks-lint](checks-lint.md) says.
+
+## Related topics
+
+- [checks-backtest](checks-backtest.md)
+- [checks-lint](checks-lint.md)