@avi2dg/checks 0.12.0 → 0.14.0

package/docs/gates/checks-quality.md

@@ -0,0 +1,94 @@
+# checks-quality
+
+`checks-quality` is the bin that writes what `quality.json` declares for oxlint and tsc into generated fragments and checks them, and a reader looks it up when a fragment is stale.
+
+## What it checks
+
+oxlint and tsc read their own JSON and nothing else, so `checks-quality generate` writes what `sources.effect` declares into two fragments at the repository root, and the hand-written configs extend them.
+Both fragments are committed.
+
+`oxlintrc.quality.json` holds one override: the declared paths as `files`, the exempt ones as `excludeFiles`, and the kit's Effect rule block, `presets/effect.oxlint.json`.
+`tsconfig.quality.json` holds the language-service override: the same paths as `include`, the exempt ones as `exclude`, and `presets/effect.language-service.json`.
+A kit release that changes a preset reaches the repository through its next `generate`.
+A rule only this repository needs stays in its own `.oxlintrc.json`, whose overrides come after the fragment's and so win.
+
+`.oxlintrc.json` extends its fragment:
+
+```json
+{
+  "extends": ["./node_modules/@avi2dg/checks/oxlintrc.json", "./oxlintrc.quality.json"],
+  "plugins": ["typescript", "oxc", "eslint", "import"]
+}
+```
+
+`tsconfig.json` extends its fragment:
+
+```json
+{
+  "extends": ["@avi2dg/checks/tsconfig.effect.json", "./tsconfig.quality.json"]
+}
+```
+
+`checks-quality --check` fails when any of these holds:
+
+- A fragment is missing, or differs from what `generate` would write from `quality.json` and the installed kit's presets.
+- A fragment is left over once `quality.json` stops declaring `sources.effect`.
+- `.oxlintrc.json` or `tsconfig.json` does not list its fragment in `extends`, so the tool never reads it.
+- A `sources.effect.paths` glob, or a `sources.production` glob while `size` is declared, matches no tracked or untracked file, so it holds nothing.
+
+Two details of the fragments are easy to get wrong, so the kit's tests pin both:
+
+- A fragment sits at the repository root.
+  oxlint resolves an override's `files`, and the language service an override's `include`, against the directory of the config holding it.
+  From `.quality/` the language service reports no error at all on an `async function` planted under a declared path.
+- The oxlint fragment always sets `plugins`, to the kit's.
+  A config in `extends` that sets none brings in oxlint's default plugins, whose category rules then fire across the whole tree.
+  The override names the kit's plugins beside the preset's `node`, `promise` and `unicorn`, because one that leaves any of the kit's out turns on the category rules of the plugins it adds under every declared path.
+
+## What it reads
+
+It reads the working tree: `quality.json`, the presets of the installed kit, `.oxlintrc.json`, `tsconfig.json` and the two fragments.
+It lists the tracked and untracked files to see what each declared glob matches.
+
+## Arguments
+
+```sh
+checks-quality generate
+checks-quality --check
+```
+
+`generate` writes the fragments, removes a left-over one, then runs the same check as `--check`.
+`--check` writes nothing.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | the fragments hold what `quality.json` declares |
+| 1 | a fragment is stale, missing, left over or not extended, or a declared glob matches no file |
+| 2 | `quality.json` does not decode, or the arguments are neither `generate` nor `--check` |
+
+## Sample output
+
+```
+checks-quality: 2 problem(s) with what quality.json declares:
+  oxlintrc.quality.json is stale against quality.json and the kit's presets; run checks-quality generate
+  tsconfig.json does not extend ./tsconfig.quality.json, so the language service never reads it
+```
+
+A passing run says what the fragments hold:
+
+```
+checks-quality: oxlintrc.quality.json and tsconfig.quality.json hold what quality.json declares
+```
+
+## Opting out
+
+It runs only in a repository that tracks `quality.json`, and a selection in `quality.json` always keeps it, since the file it sits in is what makes it apply.
+A repository that declares no `sources.effect` gets no fragment, and the check then only refuses a left-over one.
+
+## Related topics
+
+- [The quality file](../configs/quality-file.md)
+- [The Effect rules](../configs/effect-rules.md)
+- [checks-lint](checks-lint.md)

package/docs/gates/checks-size-budget.md

@@ -0,0 +1,64 @@
+# checks-size-budget
+
+`checks-size-budget` is the gate that holds production files to the line budget `quality.json` declares, and a reader looks it up when a file or a function runs over it.
+
+## What it checks
+
+It holds production files to the line budget `quality.json` declares, and lists every other file over it without failing:
+
+```json
+"sources": { "production": ["src/**/*.ts"] },
+"size": { "fileLines": 400, "functionLines": 100, "applies": "changed" }
+```
+
+It runs oxlint with a configuration of two rules and nothing else, `max-lines` at `fileLines` and `max-lines-per-function` at `functionLines`, both counting blank and comment lines.
+With `applies` set to `changed` it holds the files under `sources.production` that the range adds or changes, a rename that edits the file included.
+With `all` it holds every file under `sources.production`.
+A file the range deletes or only renames is not held.
+Every other tracked `.ts` or `.tsx` file over the budget, tests and unchanged production files alike, is listed as advisory and never fails the gate.
+`.d.ts` files are not measured.
+
+## What it reads
+
+It reads each file from the head commit rather than the working tree, so an uncommitted edit neither fails nor passes a range, and a pull request's merge checkout measures what the pull request holds.
+It reads `sources.production` and `size` from `quality.json`.
+oxlint must be on `PATH`, as it is under a package script.
+
+## Arguments
+
+```sh
+checks-size-budget <base-ref> <head-ref>
+checks-size-budget <ref>
+```
+
+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.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | every file it holds keeps within the budget |
+| 1 | a file it holds runs over the budget |
+| 2 | `quality.json` does not decode, a ref does not resolve, or oxlint cannot run |
+
+## Sample output
+
+```
+size-budget: 1 overrun(s) of 400 lines per file and 100 per function in the production files the range adds or changes:
+  src/billing/ledger.ts:12: The function `settle` has too many lines (131). Maximum allowed is 100.
+size-budget: advisory, 1 overrun(s) where the budget does not hold yet:
+  tests/e2e/billing.test.ts: File has too many lines (512).
+```
+
+## Opting out
+
+A repository that declares no `size` passes.
+`quality.json` refuses a `size` without `sources.production`, which would hold nothing, and with `size` declared `checks-quality` refuses a `sources.production` glob that matches no file.
+A repository that tracks no `.ts` or `.tsx` file leaves it out of `gates.lint`, as [Gate selection](checks-lint.md#gate-selection) says.
+Moving `applies` from `changed` to `all` tightens the budget to every production file, once the advisory list names none.
+
+## Related topics
+
+- [The quality file](../configs/quality-file.md)
+- [checks-lint](checks-lint.md)

package/docs/gates/checks-suppressions-ratchet.md

@@ -0,0 +1,51 @@
+# checks-suppressions-ratchet
+
+`checks-suppressions-ratchet` is the gate that holds oxlint's bulk-suppression baseline to counts that only fall, and a reader looks it up when a change raised a count.
+
+## What it checks
+
+oxlint accepts whatever `oxlint --suppress-all` writes to `oxlint-suppressions.json`, so raising a count to let a new site through passes the lint.
+The ratchet fails naming each file and rule whose count rose or that appeared.
+A count that fell and an entry that went both pass.
+
+## What it reads
+
+It reads `oxlint-suppressions.json` at a base and at a head, from the directory the command runs in, which is where oxlint writes it.
+A commit without the file counts as empty, so the commit that first adds a baseline fails with every entry appearing.
+
+## Arguments
+
+```sh
+checks-suppressions-ratchet <base-ref> <head-ref>
+checks-suppressions-ratchet <ref>
+```
+
+With two arguments it reads the base where the head branched off, at their merge-base, so a count the base branch lowered since does not read as a rise at the head.
+With one it compares that commit with its parent, or with the empty tree for a repository's first commit.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | no count rose and no entry appeared |
+| 1 | a count rose or an entry appeared |
+| 2 | a ref does not resolve, the parent exists but is not in the clone, or the file is not oxlint's count per rule per file |
+
+## Sample output
+
+```
+suppressions-ratchet: 2 count(s) in oxlint-suppressions.json rose or appeared; fix the site instead of suppressing it:
+  src/added.ts typescript/no-unsafe-type-assertion appeared with 1
+  src/dispatch.ts typescript/no-non-null-assertion rose from 12 to 13
+```
+
+## Opting out
+
+It applies to every repository, so no selection leaves it out.
+A repository with no `oxlint-suppressions.json` passes, since both ends count as empty.
+`checks-lint` runs it over each pull request's range, as [checks-lint](checks-lint.md) says.
+
+## Related topics
+
+- [The Effect rules](../configs/effect-rules.md)
+- [checks-lint](checks-lint.md)

package/docs/gates/checks-test-layout.md

@@ -0,0 +1,77 @@
+# checks-test-layout
+
+`checks-test-layout` is the gate that holds a repository's tests to one layout, and a reader looks it up to learn where a test file goes and what it may import.
+
+## What it checks
+
+It fails unless the repository holds this shape, and names the file and the path to move it to when it does not.
+
+- Every test file is `tests/**/*.test.ts` or `.tsx`.
+  A `*.test.ts`, `*.spec.ts` or `*_test.ts` under `src/`, `test/`, `__tests__/` or the repository root fails.
+- `tests/lib/**` holds helpers and `tests/fixtures/**` holds data, and neither may hold a test file.
+  Every other directory directly under `tests/` is a test group and may nest as deep as it likes.
+- A test runs at one of two levels.
+  A test outside `tests/e2e/` runs in-process, so it may not import `node:child_process`, `net`, `http`, `https`, `http2`, `tls` or `dgram`.
+  It may not import `$`, `spawn`, `spawnSync`, `connect`, `serve` or `listen` from `bun`, may not touch `Bun.$` or `Bun.spawn`, and may not call `fetch`.
+  A test inside `tests/e2e/` may do all of it.
+  Helpers in `tests/lib/**` answer to the same rule, since an in-process test reaches them.
+- `scripts.test` is exactly `checks-test`, which runs `bun test --randomize` as [checks-test](checks-test.md) says.
+- `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.
+  `[test].pathIgnorePatterns` is always `["**/tests/quarantine/**"]`, which the check pins itself, so the kit's own repository, whose bunfig is the preset, cannot drift it either.
+  Other tables, and extra `[test]` keys, are the repository's own.
+
+The in-process half is what a mutation run can mutate.
+`tests/e2e/**` is left out of a mutate scope by construction, because a subprocess kills both the speed and the coverage signal a mutant needs.
+
+The preset also skips `tests/quarantine/**` on a default run.
+A test that turns flaky moves there, so the suite stays trustworthy, and the flake still runs on demand:
+
+```sh
+bun test --path-ignore-patterns='' tests/quarantine
+```
+
+## What it reads
+
+It reads the working tree.
+It scans the tracked and untracked files that `git ls-files --exclude-standard` reports, so `node_modules/` and every gitignored tree are out of reach, and a local run agrees with CI before `git add`.
+It parses each test and helper 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.
+`tests/fixtures/**` is data and is not parsed.
+It reads `package.json` for `scripts.test` and `scripts.lint`, and compares `bunfig.toml` with the preset the installed kit ships.
+
+## Arguments
+
+```sh
+checks-test-layout [<directory>]
+```
+
+It checks the directory it runs in, or the directory it is given.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | the repository holds the layout |
+| 1 | a file breaks the layout |
+| 2 | a test, a helper or `package.json` does not parse |
+
+## Sample output
+
+```
+test-layout: 4 violation(s)
+  src/a.test.ts: a test file must live at tests/**/*.test.ts; move it to tests/a.test.ts
+  package.json: scripts.test must be exactly "checks-test", which runs bun test --randomize and judges its skips, found "bun test"
+  package.json: scripts.lint must run the layout check: add "checks-lint"
+  bunfig.toml: bunfig.toml is missing; bun has no bunfig extends, so copy node_modules/@avi2dg/checks/bunfig.toml
+```
+
+## Opting out
+
+A repository that tracks no `.ts` or `.tsx` file leaves it out of `gates.lint`, as [Gate selection](checks-lint.md#gate-selection) says, and then needs no `checks-test` script and no `bunfig.toml`.
+A repository that tracks one keeps it.
+
+## Related topics
+
+- [checks-test](checks-test.md)
+- [checks-flake](checks-flake.md)
+- [checks-mutation-compare](checks-mutation-compare.md)

package/docs/gates/checks-test.md

@@ -0,0 +1,75 @@
+# checks-test
+
+`checks-test` is the entry point that runs the whole suite and refuses a skip the repository has not declared, and a reader looks it up to declare a skip.
+
+## What it checks
+
+It runs the whole suite with `bun test --randomize`, passes bun's output through, and then reads bun's JUnit report of the same run.
+bun exits 0 with tests skipped, so a green run says nothing about the tests that never ran.
+`checks-test` fails when a test failed, or when a test was skipped without a declaration in `package.json`.
+A test counts as skipped through `test.skip`, `test.skipIf`, `test.if`, `describe.skip` or `test.todo`.
+
+A declaration names the test and says why it skips:
+
+```json
+"testSkips": [
+  {
+    "file": "tests/e2e/docker.test.ts",
+    "test": "images > builds the release image",
+    "reason": "the runner has no docker daemon",
+    "when": "ci"
+  }
+]
+```
+
+`file` is the path bun reports, relative to the package root.
+`test` is the name bun's console prints, the describe blocks and the test name joined by ` > `.
+`reason` is required.
+`when` is `ci` or `local` for a test skipped only there, and a declaration without it holds in both.
+
+A declaration that holds for the run but matches no skipped test fails a ci run too, so a fixed or renamed test takes its declaration with it.
+A local run only warns about it, because whether a test skips there can hang on the machine, such as a docker daemon being up.
+Files under `tests/quarantine/` are never run and so never reported, as [checks-test-layout](checks-test-layout.md) says.
+
+## What it reads
+
+It reads bun's JUnit report of its own run, which bun writes to a temporary directory, and `testSkips` in `package.json`.
+It counts a run as `ci` when `CI` is set true, as GitHub Actions sets it, and as `local` otherwise.
+
+## Arguments
+
+It takes none.
+A `-t` filter would report every test it leaves out as skipped, and a path filter would drop files a declaration names.
+A narrowed run is therefore plain `bun test --randomize` with the arguments.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | every test that ran passed, and every skip is declared |
+| 1 | a test failed, a skip is undeclared, or in a ci run a declaration is stale |
+| 2 | `testSkips` does not parse, `CI` is set to something other than a boolean, or bun passed without writing its report |
+
+## Sample output
+
+```
+checks-test: 1 skipped test(s) undeclared and 1 declaration(s) matching no skipped test in this ci run:
+  tests/pricing.test.ts:12 pricing > rounds half to even: skipped with no declaration; run it, or declare it in package.json testSkips with its reason
+  tests/e2e/docker.test.ts > images > builds the release image: declared, but no such test skipped; delete the declaration
+```
+
+A run with nothing skipped ends with:
+
+```
+checks-test: no test skipped
+```
+
+## Opting out
+
+A test opts out of a run through its declaration in `testSkips`.
+A repository that tracks TypeScript source runs `checks-test` as `scripts.test`, since [checks-test-layout](checks-test-layout.md) requires it.
+
+## Related topics
+
+- [checks-test-layout](checks-test-layout.md)
+- [checks-flake](checks-flake.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Deterministic checks shared across the captain's TypeScript repos",
   "license": "MIT",
   "repository": {
@@ -12,6 +12,11 @@
   },
   "type": "module",
   "files": [
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "docs/configs/",
+    "docs/design.md",
+    "docs/gates/",
     "bunfig.toml",
     "commitlint.config.js",
     "dependency-cruiser.config.js",
@@ -36,6 +41,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 +76,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 +109,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 && bun scripts/changelog-write.ts && bun scripts/doc-blocks-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"

package/quality.schema.json

@@ -44,6 +44,7 @@
               "checks-comment-gate",
               "checks-suppressions-ratchet",
               "checks-ci-wiring",
+              "checks-docs",
               "checks-quality",
               "checks-size-budget",
               "checks-feature-owners"
@@ -69,6 +70,11 @@
               "contains": {
                 "const": "checks-ci-wiring"
               }
+            },
+            {
+              "contains": {
+                "const": "checks-docs"
+              }
             }
           ]
         }
@@ -241,6 +247,48 @@
         }
       },
       "additionalProperties": false
+    },
+    "docs": {
+      "type": "object",
+      "properties": {
+        "pages": {
+          "type": "object",
+          "properties": {
+            "tutorial": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/PathGlob"
+              },
+              "description": "The pages written as a tutorial, which teaches by building one thing"
+            },
+            "how-to": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/PathGlob"
+              },
+              "description": "The pages written as a how-to, which walks one task"
+            },
+            "reference": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/PathGlob"
+              },
+              "description": "The pages written as reference, which describes a thing to be looked up"
+            },
+            "explanation": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/PathGlob"
+              },
+              "description": "The pages written as an explanation, which says why"
+            }
+          },
+          "additionalProperties": false,
+          "description": "The Diátaxis mode of each page, whose template checks-docs holds the page to; a page under docs/ needs one"
+        }
+      },
+      "additionalProperties": false,
+      "description": "What checks-docs reads to map a doc file to its template"
     }
   },
   "additionalProperties": false,