@avi2dg/checks 0.12.0 → 0.13.0

package/README.md

@@ -13,12 +13,20 @@ compiles into it, the test-layout check with its bunfig preset, the commit-ident
 comment gate with its backtest, the oxlint suppressions ratchet, the
 size budget, the feature-owner change signal and proof check, the
 Stryker mutation-testing preset with its no-regression comparator, the
-CI-wiring check, and the Effect error-channel plugin compiled to
-JavaScript.
+CI-wiring check, a template for each kind of doc file with the gate that
+holds each doc file to its template, and the Effect error-channel plugin
+compiled to JavaScript.
 
 Published as `@avi2dg/checks` on the public npm registry.
 
-## Consume it
+## Before you begin
+
+- Bun, which runs every bin.
+  The kit is tested on the version its own `.bun-version` pins.
+- A git repository, whose history the range gates read.
+- The peer versions the install line below pins, which `peerDependencies` in `package.json` holds.
+
+## Install
 
 From the consuming repo:
 
@@ -50,7 +58,7 @@ node_modules/
 ```
 
 `quality.json` at the repository root declares what the repository
-opts into, starting with the commands its CI runs; see "Quality file"
+opts into, starting with the commands its CI runs. See "Declare policy in the quality file"
 below:
 
 ```json
@@ -75,9 +83,9 @@ cp node_modules/@avi2dg/checks/bunfig.toml bunfig.toml
 ```
 
 `checks-test` runs `bun test --randomize` and fails on a skip the
-repository has not declared; see "Test entry point" below.
+repository has not declared. See "Run the suite" below.
 
-`checks-lint` runs every kit gate a lint needs; see "Lint entry point"
+`checks-lint` runs every kit gate a lint needs. See "Run every lint gate"
 below. Three of them:
 
 `lint-coverage.sh` fails when oxlint silently skips a tracked `.ts` or
@@ -89,7 +97,7 @@ or its config does not parse.
 `test-layout.ts` decides the test layout described below.
 
 `commit-identity.ts` refuses a commit with an author other than the
-repository owner; see "Commit identity" below.
+repository owner. See "Check commit identities" below.
 
 A repo that runs mutation testing installs `@stryker-mutator/core` and
 `@hughescr/stryker-bun-runner`, then spreads the shipped preset in
@@ -106,7 +114,7 @@ export default {
 The registry version is pinned by the consumer's lockfile; bump
 `@avi2dg/checks` to adopt a new release.
 
-## Quality file
+## Declare policy in the quality file
 
 `quality.json` at the repository root says what the repository has
 opted into. The kit's bins find it at the git root and read it there:
@@ -135,23 +143,25 @@ opted into. The kit's bins find it at the git root and read it there:
     }
   ],
   "changeSignal": "advisory",
-  "agentRules": { "on": [], "off": [] }
+  "agentRules": { "on": [], "off": [] },
+  "docs": { "pages": { "reference": ["docs/gates/*.md"], "explanation": ["docs/design.md"] } }
 }
 ```
 
 | 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; see "CI wiring" |
+| `gates.ci` | `checks-ci-wiring` | the commands CI runs on every pull request. See "Check the CI wiring" |
 | `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; see "Gate selection" |
-| `commitIdentity.authors` | `checks-commit-identity` | the identities allowed to author and commit; see "Commit identity" |
-| `sources.effect` | `checks-quality` | the paths held to the Effect rules, and the files under them that are not; see "Effect rules" |
-| `sources.production` | `checks-size-budget`, `checks-quality` | the source the repository ships; see "Size budget" |
-| `size` | `checks-size-budget` | the line budget, and which production files it holds; see "Size budget" |
-| `features` | `featureRules`, `checks-feature-owners` | each feature's root, entries, exempt importers and proof; see "Feature owners" |
-| `changeSignal` | `checks-feature-owners` | `advisory` to list the feature owners a change touches; see "Feature owners" |
+| `gates.lint` | `checks-lint`, `checks-ci-wiring` | the gates `checks-lint` runs when not all apply. See "Gate selection" |
+| `commitIdentity.authors` | `checks-commit-identity` | the identities allowed to author and commit. See "Check commit identities" |
+| `sources.effect` | `checks-quality` | the paths held to the Effect rules, and the files under them that are not. See "Enforce the Effect rules" |
+| `sources.production` | `checks-size-budget`, `checks-quality` | the source the repository ships. See "Hold files to a size budget" |
+| `size` | `checks-size-budget` | the line budget, and which production files it holds. See "Hold files to a size budget" |
+| `features` | `featureRules`, `checks-feature-owners` | each feature's root, entries, exempt importers and proof. See "Declare feature owners" |
+| `changeSignal` | `checks-feature-owners` | `advisory` to list the feature owners a change touches. See "Declare feature owners" |
 | `agentRules.on`, `agentRules.off` | agent Rule selection, not the kit | catalogued Rules switched on or off for this repository |
+| `docs.pages` | `checks-docs` | the Diátaxis mode of each page, by glob. See "Hold docs to their templates" |
 
 Every key is optional. The bins decode the file with one Effect
 `Schema`, and the package ships `quality.schema.json` emitted from that
@@ -258,12 +268,12 @@ pin both:
   because one that leaves any of the kit's out turns on the category
   rules of the plugins it adds under every declared path.
 
-## Lint entry point
+## Run every lint gate
 
 `checks-lint` runs each of the kit's lint gates in turn and names every
 one that fails, rather than stopping at the first. A repository whose
 tracked files give a gate nothing to check can leave it out through
-`gates.lint`; see "Gate selection" under "CI wiring".
+`gates.lint`. See "Gate selection" under "Check the CI wiring".
 
 | Gate | Reads |
 | --- | --- |
@@ -273,6 +283,7 @@ tracked files give a gate nothing to check can leave it out through
 | `checks-comment-gate` | the range |
 | `checks-suppressions-ratchet` | the range |
 | `checks-ci-wiring` | the working tree |
+| `checks-docs` | the range |
 | `checks-quality` | the working tree |
 | `checks-size-budget` | the range |
 | `checks-feature-owners` | the range |
@@ -287,7 +298,7 @@ Locally, and on any event other than a pull request, the range ends at
 `HEAD` and starts where `HEAD` branched from the origin default branch:
 `origin/HEAD`, or when `origin/HEAD` is not set, as in an
 `actions/checkout` clone, `origin/<defaultBranch>` from the
-repository's `quality.json` (see "Quality file"), and `origin/main` when
+repository's `quality.json`, as "Declare policy in the quality file" says, and `origin/main` when
 that is not declared. In a GitHub Actions pull request, where
 `GITHUB_EVENT_NAME` is `pull_request`, it ends
 at the event's head sha and starts where that branched from
@@ -333,8 +344,8 @@ checks-lint: 3 of 9 gate(s) failed: checks-commit-identity, checks-comment-gate,
 
 It exits 1 when any gate found a violation, and 2 when the range or the
 selection does not resolve, or no failing gate could decide. ci-wiring
-always runs, so a repository on `checks-lint` declares `gates.ci`
-(see "CI wiring"), and it holds the test layout unless its selection
+always runs, so a repository on `checks-lint` declares `gates.ci`,
+as "Check the CI wiring" says, and it holds the test layout unless its selection
 leaves out `checks-test-layout`.
 
 CI runs it through `lint`. The checkout fetches the whole history, which
@@ -355,7 +366,7 @@ jobs:
       - run: bun run lint
 ```
 
-## Effect rules
+## Enforce the Effect rules
 
 The base config loads the `effect-channel` plugin and turns on
 `effect-channel/no-error-channel-escape`, which refuses `Effect.ignore`,
@@ -376,7 +387,7 @@ through `Effect.fail`, a throwing call wrapped in `Effect.try` or
 
 A repository turns them on for the paths it writes in Effect by
 declaring those paths in `quality.json` and extending the generated
-fragments; see "Generated fragments" under "Quality file":
+fragments. See "Generated fragments" under "Declare policy in the quality file":
 
 ```json
 "sources": {
@@ -412,7 +423,7 @@ the tsconfig fragment's override, whose severities are
 effect-tsgo keeps the severities `tsconfig.effect.json` sets when a later
 config in `extends` restates the plugin with only its overrides.
 
-## Test layout
+## Lay out the tests
 
 `checks-test-layout` fails unless the repo holds this shape, and names the
 file and the path to move it to when it does not:
@@ -435,7 +446,7 @@ file and the path to move it to when it does not:
   with swc and reads import specifiers and identifier use, so a test that
   only carries `"node:child_process"` as a string is not a violation.
 - `scripts.test` is exactly `checks-test`, which runs `bun test --randomize`
-  (see "Test entry point"), and `scripts.lint` runs this check, itself or
+  as "Run the suite" says, and `scripts.lint` runs this check, itself or
   through `checks-lint` called by its bare bin name.
 - `bunfig.toml` carries every `[test]` key of the shipped preset with the
   same value, and `[test].pathIgnorePatterns` is always
@@ -455,7 +466,7 @@ still run on demand:
 bun test --path-ignore-patterns='' tests/quarantine
 ```
 
-## Test entry point
+## Run the suite
 
 `checks-test` runs the whole suite with `bun test --randomize`, passes
 bun's output through, and then reads bun's JUnit report of the same run.
@@ -498,10 +509,10 @@ passed without writing its report. It takes no arguments: a `-t`
 filter reports every test it leaves out as skipped and a path filter
 drops files a declaration names, so a narrowed run is plain
 `bun test --randomize` with the arguments. Files under
-`tests/quarantine/` are never run and so never reported; see "Test
+`tests/quarantine/` are never run and so never reported. See "Test
 layout".
 
-## Flake run
+## Find flaky tests
 
 A green run proves nothing failed in that run, not that no test is
 flaky. `checks-flake` runs the whole suite several times, each with its
@@ -556,9 +567,9 @@ jobs:
 ```
 
 and declares the step in `gates.scheduled`, so `checks-ci-wiring`
-fails once the schedule stops running it; see "CI wiring".
+fails once the schedule stops running it. See "Check the CI wiring".
 
-## Dependency rules
+## Enforce dependency rules
 
 `.dependency-cruiser.cjs` extends the shared base, which carries
 `no-circular`, `no-orphans`, `not-to-dev-dep` (shipped source importing
@@ -587,7 +598,7 @@ by field, which is how an entry point stops being an orphan:
 redeclare `no-orphans` with your entry added to its `pathNot`.
 This repo's own `.dependency-cruiser.cjs` does that for the plugin
 entry. A repository that declares feature owners spreads the rules
-`quality.json` compiles to into the same `forbidden`; see "Feature
+`quality.json` compiles to into the same `forbidden`. See "Feature
 owners".
 
 `package.json` gains the script:
@@ -608,7 +619,7 @@ jobs:
       - run: bun run lint:deps
 ```
 
-## Commit lint
+## Lint commit messages
 
 Commits follow `@commitlint/config-conventional` plus the house
 prefixes listed in `commitlint.config.js`, shared from
@@ -647,7 +658,7 @@ It never sees a commit's author or committer fields, nor the
 squashes, so it cannot enforce who a commit belongs to. The
 commit-identity check below is the enforcement.
 
-## Commit identity
+## Check commit identities
 
 `scripts/commit-identity.ts` walks every commit in a range and fails when
 one carries an identity other than the repository owner's:
@@ -673,9 +684,10 @@ owners restates it in `quality.json`:
 }
 ```
 
-`checks-lint` runs it over each pull request's range; see "Lint entry point".
+`checks-lint` runs it over each pull request's range.
+See "Run every lint gate".
 
-## Comment gate
+## Refuse banned comments
 
 `scripts/comment-gate.ts` runs the comment check over a diff and fails
 when an added line carries a banned comment:
@@ -704,9 +716,10 @@ and import it as `@avi2dg/checks/scripts/comment-matchers.ts`. The repo's
 cruise fails when it gains an import. `scripts/comments.ts` wraps the
 same matchers in Effect for the gate and the backtest.
 
-`checks-lint` runs it over each pull request's range; see "Lint entry point".
+`checks-lint` runs it over each pull request's range.
+See "Run every lint gate".
 
-## Suppressions ratchet
+## Ratchet the suppressions
 
 `scripts/suppressions-ratchet.ts` holds oxlint's bulk-suppression
 baseline, `oxlint-suppressions.json`, to counts that only fall. oxlint
@@ -737,9 +750,10 @@ suppressions-ratchet: 2 count(s) in oxlint-suppressions.json rose or appeared; f
   src/dispatch.ts typescript/no-non-null-assertion rose from 12 to 13
 ```
 
-`checks-lint` runs it over each pull request's range; see "Lint entry point".
+`checks-lint` runs it over each pull request's range.
+See "Run every lint gate".
 
-## Size budget
+## Hold files to a size budget
 
 `checks-size-budget` holds production files to the line budget
 `quality.json` declares, and lists every other file over it without
@@ -790,9 +804,10 @@ glob that matches no file. Moving `applies` from `changed` to `all`
 tightens the budget to every production file, once the advisory list
 names none.
 
-`checks-lint` runs it over each pull request's range; see "Lint entry point".
+`checks-lint` runs it over each pull request's range.
+See "Run every lint gate".
 
-## Feature owners
+## Declare feature owners
 
 A repository opts a feature in by declaring, in `quality.json`, the
 directory it owns, the files code outside it imports it through, the
@@ -891,9 +906,78 @@ repository that declares no feature passes, and `quality.json` refuses
 a `changeSignal` without features, which would map a change to no
 owner.
 
-`checks-lint` runs it over each pull request's range; see "Lint entry point".
+`checks-lint` runs it over each pull request's range.
+See "Run every lint gate".
+
+## Hold docs to their templates
+
+`checks-docs` holds each doc file a change touches to the template for its kind, and lists every other doc file that does not conform yet without failing.
+The package ships one template per kind under `templates/`, and a repository starts a new doc file by copying one:
+
+```sh
+cp node_modules/@avi2dg/checks/templates/how-to.md docs/add-a-supplier.md
+```
+
+| File | Kind | Template |
+| --- | --- | --- |
+| `README.md` | readme | `templates/readme.md` |
+| `CHANGELOG.md` | changelog | `templates/changelog.md` |
+| `AGENTS.md` | agents | `templates/agents.md` |
+| `CLAUDE.md` | claude | `templates/claude.md` |
+| each file in `docs/adr/` but its generated index, `README.md` | adr | `templates/adr.md` |
+| a page `docs.pages` declares | tutorial, how-to, reference or explanation | `templates/<mode>.md` |
+
+The first four are the files at the repository root.
+No other Markdown file is judged, save a page under `docs/`, which needs a mode.
+Which Diátaxis mode a page is written in is a judgment, so `quality.json` declares it:
+
+```json
+"docs": {
+  "pages": {
+    "reference": ["docs/gates/*.md"],
+    "explanation": ["docs/design.md"]
+  }
+}
+```
+
+A template decides a file's structure, and the template file itself is the reference for each kind:
+
+- A file opens with one `# ` title on its first line and has text before its first section.
+  It skips no heading level, and no heading is Overview, Introduction or How it works.
+- Its sections are the template's headings in the template's order.
+  A heading in angle brackets is one the writer names.
+  One marked verb first is left to review, since no program tells a verb from a noun there.
+  A heading the template does not have, in that place, is refused.
+- A record in `docs/adr/` is named for its four-digit number, and its title opens with the same number.
+  A `Date: YYYY-MM-DD` line follows the title, the first word under Status is Proposed, Accepted, Rejected, Deprecated, Superseded or Retired, and no other record holds its number.
+- A changelog lists its releases newest first, each opening with a `Released YYYY-MM-DD.` line.
+- A how-to or tutorial page numbers its steps.
+- `CLAUDE.md` is its template word for word.
+
+```sh
+checks-docs <base-ref> <head-ref>
+checks-docs <ref>
+```
+
+It reads each file from the head commit.
+With two arguments the range starts where the head branched from the base, at their merge-base.
+With one it is that commit against its parent, or against the empty tree for a repository's first commit.
+A file the range adds, changes or renames is held to its template, and a file it deletes is not.
 
-## CI wiring
+```
+docs: 2 violation(s) in the doc files the range touches:
+  README.md:1: lacks `## Where things are`
+  docs/parts.md: is a page under docs/ with no mode; declare it under docs.pages in quality.json as tutorial, how-to, reference, explanation
+docs: advisory, 1 doc file(s) the range leaves alone do not hold to their templates yet:
+  docs/adr/0001-quality-gates.md: 5 violation(s)
+```
+
+It exits 1 on a violation in a file the range touches, and 2 when `quality.json` does not decode or a ref does not resolve.
+
+`checks-lint` runs it over each pull request's range.
+See "Run every lint gate".
+
+## Check the CI wiring
 
 `checks-ci-wiring` fails when a command the repository's CI must run no
 longer runs on pull requests to the default branch. No local check sees
@@ -1010,13 +1094,14 @@ missing `bun test` script and `bunfig.toml`. It declares the gates
     "checks-comment-gate",
     "checks-suppressions-ratchet",
     "checks-ci-wiring",
+    "checks-docs",
     "checks-quality"
   ]
 }
 ```
 
-`checks-lint` runs exactly those, in the "Lint entry point" table's
-order, and all nine when `gates.lint` is absent. A selection in
+`checks-lint` runs exactly those, in the "Run every lint gate" table's
+order, and all ten when `gates.lint` is absent. A selection in
 `quality.json` always keeps `checks-quality`, since the file it sits in
 is what makes that gate apply. A step running
 `checks-lint` then counts only for a declared gate that `gates.lint`
@@ -1032,6 +1117,7 @@ A selection may leave out only a gate that does not apply:
 | `checks-comment-gate` | always |
 | `checks-suppressions-ratchet` | always |
 | `checks-ci-wiring` | always |
+| `checks-docs` | always |
 | `checks-quality` | tracks a `quality.json` |
 | `checks-size-budget` | tracks a `.ts` or `.tsx` file |
 | `checks-feature-owners` | tracks a `.ts` or `.tsx` file |
@@ -1067,7 +1153,7 @@ does not evaluate:
   command itself does, the shell's options, and a step or job that
   fails or times out before the gate step.
 
-## Backtest
+## Backtest the comment check
 
 `scripts/backtest.ts` reports what the comment check would have refused
 at each recent commit, so a repository can measure its own history:
@@ -1083,7 +1169,7 @@ comment text as a share of added lines.
 `generated/`, `vendor/`, `repos/`, `node_modules/` and `dist/` are out
 of reach, so the figures are authored code.
 
-## Mutation compare
+## Compare mutation scores
 
 `checks-mutation-compare` gates a pull request on no-regression rather
 than an absolute threshold: the head mutation score may not fall below
@@ -1129,117 +1215,6 @@ jobs:
 The shared Stryker preset's `json` reporter writes
 `reports/mutation/mutation.json` in each worktree.
 
-## Why it is shaped this way
-
-- 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`; CI fails when the committed bundle
-  is stale. `bun run build` also emits `quality.schema.json`, which is
-  committed the same way, and a test fails when it differs from what
-  the schema emits.
-- `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 (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 above.
-
 ## Develop
 
 ```sh
@@ -1273,3 +1248,20 @@ every later tag publishes through the workflow.
 
 `publishConfig.access` in package.json is what makes the scoped package
 public.
+
+## Where things are
+
+| Path | What it holds |
+| --- | --- |
+| `scripts/` | every bin, and the modules they share |
+| `effect-channel/` | the Effect error-channel oxlint plugin |
+| `dist/` | the committed bundles of the plugin and of `featureRules` |
+| `presets/` | the Effect presets `checks-quality` builds its fragments from |
+| `templates/` | one template per kind of doc file, which `bun run build` renders |
+| `tests/` | the suite, with the tests that spawn a process under `tests/e2e/` |
+| `docs/` | pages for whoever develops the kit |
+| the root configs | `oxlintrc.json`, `tsconfig.effect.json`, `bunfig.toml`, `commitlint.config.js`, `dependency-cruiser.config.js`, `stryker.preset.js` and `quality.schema.json`, which a consuming repository extends or copies |
+
+## Related topics
+
+- [Why it is shaped this way](docs/design.md)

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Deterministic checks shared across the captain's TypeScript repos",
   "license": "MIT",
   "repository": {
@@ -36,6 +36,11 @@
     "scripts/quality.ts",
     "scripts/size-budget.ts",
     "scripts/feature-owners.ts",
+    "scripts/docs.ts",
+    "scripts/doc-outline.ts",
+    "scripts/doc-rules.ts",
+    "scripts/doc-templates.ts",
+    "templates/",
     "presets/effect.oxlint.json",
     "presets/effect.language-service.json",
     "quality.schema.json",
@@ -66,6 +71,16 @@
     "./scripts/quality.ts": "./scripts/quality.ts",
     "./scripts/size-budget.ts": "./scripts/size-budget.ts",
     "./scripts/feature-owners.ts": "./scripts/feature-owners.ts",
+    "./scripts/docs.ts": "./scripts/docs.ts",
+    "./templates/readme.md": "./templates/readme.md",
+    "./templates/changelog.md": "./templates/changelog.md",
+    "./templates/adr.md": "./templates/adr.md",
+    "./templates/agents.md": "./templates/agents.md",
+    "./templates/claude.md": "./templates/claude.md",
+    "./templates/tutorial.md": "./templates/tutorial.md",
+    "./templates/how-to.md": "./templates/how-to.md",
+    "./templates/reference.md": "./templates/reference.md",
+    "./templates/explanation.md": "./templates/explanation.md",
     "./presets/effect.oxlint.json": "./presets/effect.oxlint.json",
     "./presets/effect.language-service.json": "./presets/effect.language-service.json",
     "./quality.schema.json": "./quality.schema.json",
@@ -89,10 +104,11 @@
     "checks-backtest": "scripts/backtest.ts",
     "checks-quality": "scripts/quality.ts",
     "checks-size-budget": "scripts/size-budget.ts",
-    "checks-feature-owners": "scripts/feature-owners.ts"
+    "checks-feature-owners": "scripts/feature-owners.ts",
+    "checks-docs": "scripts/docs.ts"
   },
   "scripts": {
-    "build": "bun build effect-channel/index.ts --outdir dist --target node --format esm && bun build scripts/feature-rules.ts --outdir dist --target node --format esm --packages external && bun scripts/quality-schema.ts",
+    "build": "bun build effect-channel/index.ts --outdir dist --target node --format esm && bun build scripts/feature-rules.ts --outdir dist --target node --format esm --packages external && bun scripts/quality-schema.ts && bun scripts/doc-templates-write.ts",
     "lint": "oxlint --type-aware && bun scripts/lint.ts && depcruise --config .dependency-cruiser.cjs .",
     "typecheck": "tsc --noEmit && effect-tsgo diagnostics --project tsconfig.json --format text --strict",
     "test": "bun scripts/test.ts"