@avi2dg/checks 0.13.0 → 0.14.0

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.13.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",
@@ -108,7 +113,7 @@
     "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 && bun scripts/doc-templates-write.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/scripts/doc-rules.ts

@@ -26,14 +26,15 @@ export type Doc = {
 
 export const ADR_DIRECTORY = "docs/adr/";
 // A generated index takes its shape from its generator.
-const ADR_INDEX = `${ADR_DIRECTORY}README.md`;
+export const ADR_INDEX = `${ADR_DIRECTORY}README.md`;
 const DOCS_DIRECTORY = "docs/";
 
-const ROOT_FILES = new Map<string, Kind>([
+export const ROOT_FILES: ReadonlyMap<string, Kind> = new Map<string, Kind>([
   ["README.md", "readme"],
   ["CHANGELOG.md", "changelog"],
   ["AGENTS.md", "agents"],
   ["CLAUDE.md", "claude"],
+  ["CONTRIBUTING.md", "how-to"],
 ]);
 
 export function placementOf(path: string, docs: Docs | undefined): Placement {
@@ -113,7 +114,7 @@ function adrProblems(path: string, outline: Outline, records: readonly string[])
   return violations;
 }
 
-const RELEASED = /^Released (\S+)\.$/;
+export const RELEASED = /^Released (\S+)\.$/;
 
 function changelogProblems({ sections }: Outline): readonly Violation[] {
   const releases = sections.filter(({ heading }) => VERSION.test(heading.title));

package/scripts/doc-templates.ts

@@ -40,7 +40,7 @@ function open(placeholder: string, rule: HeadingRule, presence: Presence, body:
   return { type: "open", placeholder, rule, presence, body, ...more };
 }
 
-function listed(words: readonly string[]): string {
+export function listed(words: readonly string[]): string {
   return words.length < 2 ? words.join("") : `${words.slice(0, -1).join(", ")} or ${words.at(-1) ?? ""}`;
 }
 
@@ -64,7 +64,8 @@ const MAINTAINING = [
   "When updating this file, preserve this bar for all agents and keep entries concise.",
 ];
 
-const CHANGE_GROUPS = ["Breaking changes", "Features", "Fixes", "Performance", "Reverts"];
+export const CHANGE_GROUPS = ["Breaking changes", "Features", "Fixes", "Performance", "Reverts"] as const;
+export type ChangeGroup = (typeof CHANGE_GROUPS)[number];
 
 export const TEMPLATES: Readonly<Record<Kind, Template>> = {
   readme: {
@@ -74,7 +75,11 @@ export const TEMPLATES: Readonly<Record<Kind, Template>> = {
     sections: [
       BEFORE_YOU_BEGIN,
       fixed("Install", REQUIRED, ["To install <name>:", "", "1. <step>", "1. <step>", "", "<What you see when it worked.>"]),
-      open("<Everyday task, verb first>", "any", REQUIRED, STEPS),
+      open("<Everyday task, verb first, or what the reader looks up>", "any", REQUIRED, [
+        ...STEPS,
+        "",
+        "<Or, for what the reader looks up, a table or a list with no steps.>",
+      ]),
       fixed("Where things are", REQUIRED, ["| Path | What it holds |", "| --- | --- |"]),
       TROUBLESHOOTING,
       RELATED_TOPICS,
@@ -87,7 +92,7 @@ export const TEMPLATES: Readonly<Record<Kind, Template>> = {
     sections: [
       open("<version>", "version", REQUIRED, ["Released <YYYY-MM-DD>."], {
         subsections: CHANGE_GROUPS.map((group) =>
-          fixed(group, optional("the release holds no such commit"), ["- <the commit's subject>"]),
+          fixed(group, optional("the release holds no such commit"), ["- **<the commit's scope, when it has one>:** <its description>"]),
         ),
       }),
     ],
@@ -121,7 +126,7 @@ export const TEMPLATES: Readonly<Record<Kind, Template>> = {
   },
   claude: {
     shape: "exact",
-    text: "<!-- Points Claude at AGENTS.md via import. Edit AGENTS.md, not this file. -->\n@AGENTS.md\n",
+    text: "<!-- Points Claude at AGENTS.md via import; edit AGENTS.md, not this file. -->\n@AGENTS.md\n",
   },
   tutorial: {
     shape: "outline",

package/scripts/quality-file.ts

@@ -221,7 +221,7 @@ export const Quality = Schema.Struct({
   );
 export type Quality = typeof Quality.Type;
 
-const LegacyManifest = Schema.Struct({
+export const LegacyManifest = Schema.Struct({
   ciWiring: Schema.optionalKey(
     Schema.Struct({
       gates: Schema.optionalKey(Schema.NonEmptyArray(Command)),

package/templates/changelog.md

@@ -10,28 +10,28 @@ Released <YYYY-MM-DD>.
 
 <Leave this section out when the release holds no such commit.>
 
-- <the commit's subject>
+- **<the commit's scope, when it has one>:** <its description>
 
 ### Features
 
 <Leave this section out when the release holds no such commit.>
 
-- <the commit's subject>
+- **<the commit's scope, when it has one>:** <its description>
 
 ### Fixes
 
 <Leave this section out when the release holds no such commit.>
 
-- <the commit's subject>
+- **<the commit's scope, when it has one>:** <its description>
 
 ### Performance
 
 <Leave this section out when the release holds no such commit.>
 
-- <the commit's subject>
+- **<the commit's scope, when it has one>:** <its description>
 
 ### Reverts
 
 <Leave this section out when the release holds no such commit.>
 
-- <the commit's subject>
+- **<the commit's scope, when it has one>:** <its description>

package/templates/claude.md

@@ -1,2 +1,2 @@
-<!-- Points Claude at AGENTS.md via import. Edit AGENTS.md, not this file. -->
+<!-- Points Claude at AGENTS.md via import; edit AGENTS.md, not this file. -->
 @AGENTS.md

package/templates/readme.md

@@ -15,13 +15,15 @@ To install <name>:
 
 <What you see when it worked.>
 
-## <Everyday task, verb first>
+## <Everyday task, verb first, or what the reader looks up>
 
 To <do the task>:
 
 1. <step>
 1. <step>
 
+<Or, for what the reader looks up, a table or a list with no steps.>
+
 ## Where things are
 
 | Path | What it holds |