@avi2dg/checks 0.21.0 → 0.23.0

package/docs/configs/quality-file.md

@@ -1,103 +0,0 @@
-# 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"]
-  },
-  "runsOn": ["self-hosted", "Linux", "X64", "winbox"],
-  "commitIdentity": { "authors": [{ "name": "avi2d", "email": "avi2dg@gmail.com" }] },
-  "sources": {
-    "production": ["src/**/*.ts"],
-    "effect": { "paths": ["src/**/*.ts"], "exempt": ["src/host/*.ts"] }
-  },
-  "size": { "applies": "ratchet", "tests": { "fileLines": 800 } },
-  "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`, `checks-quality` | the branch pull requests merge into, `main` when absent |
-| `gates.ci` | `checks-ci-wiring`, `checks-quality` | 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 |
-| `runsOn` | `checks-quality` | the runner labels every job the ci and commitlint workflows run on, `ubuntu-latest` when absent |
-| `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-repetition`, `checks-quality` | the source the repository ships, as [checks-size-budget](../gates/checks-size-budget.md) and [checks-repetition](../gates/checks-repetition.md) say |
-| `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 |
-| `sources.libraries` | `checks-vendor`, `checks-test-layout` | the libraries pinned to a shared read-only clone, as [checks-vendor](../gates/checks-vendor.md) says |
-| `size` | `checks-size-budget` | the size budget of production and test files, and how a change is held to it, as [checks-size-budget](../gates/checks-size-budget.md) says |
-| `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 |
-| `docs.forConsumers` | `checks-docs` | the living docs that speak to a repository installing this one, by glob, whose `bun run` commands name that repository's scripts |
-
-<!-- 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/gates/checks-feature-owners.md

@@ -1,113 +0,0 @@
-# checks-feature-owners
-
-`checks-feature-owners` is the gate that holds each declared feature to a runnable proof and lists the feature owners a change touches, and a reader looks it up to declare a feature.
-
-## What it checks
-
-A repository opts a feature in by declaring, in `quality.json`, the directory it owns, the files code outside it imports it through, the files that may reach past those, and the end-to-end test that proves it runs:
-
-```json
-"features": [
-  {
-    "name": "billing",
-    "root": "src/billing",
-    "entries": ["src/billing/index.ts"],
-    "allowFrom": ["src/main.ts", "src/cli/*.ts"],
-    "proof": "tests/e2e/billing.test.ts"
-  }
-],
-"changeSignal": "advisory"
-```
-
-`root` is a directory and `entries` are files under it, both without globs.
-`allowFrom` holds globs of the same shape as `sources`.
-`proof` is a `.test.ts` or `.test.tsx` file under `tests/e2e/`.
-Nothing moves, since a root is wherever the feature already lives.
-`quality.json` refuses an entry outside its root, a name used twice, and two features sharing a root or one root inside another, so a file has at most one owner.
-
-The gate fails when a feature's proof cannot prove it:
-
-- the proof or an entry is not in the head commit
-- the proof does not parse
-- the proof imports none of the feature's entries
-
-An import counts when it is a runtime `import`, `export ... from` or `export * from` of a relative path that names an entry.
-It names the entry by its own name, by the `.js`, `.jsx`, `.mjs` or `.cjs` spelling of it, or without an extension, the way a directory `index` is imported.
-`.js` names a `.tsx` entry as well as a `.ts` one.
-`import type` does not count, and neither does a path alias.
-The proof runs in `bun run test` like any end-to-end test, which is what shows it passes.
-
-With `changeSignal` set to `advisory` it also lists each owner the range touches, with the paths it touched under the owner's root or at its proof, and still passes.
-Whether a change that spans owners is one coherent slice is for a reviewer to judge.
-A rename counts at both of its paths.
-
-## What it reads
-
-It reads `features` and `changeSignal` from `quality.json`, each proof and entry from the head commit, and the paths the range touches.
-
-## Arguments
-
-```sh
-checks-feature-owners <base-ref> <head-ref>
-checks-feature-owners <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 feature's proof imports one of its entries |
-| 1 | a feature's proof cannot prove it |
-| 2 | `quality.json` does not decode, which is where a proof outside `tests/e2e/` is refused, or a ref does not resolve |
-
-## Sample output
-
-```
-feature-owners: 1 problem(s) with the features' runnable proofs:
-  billing: proof tests/e2e/billing.test.ts imports none of its entries, src/billing/index.ts
-```
-
-With `changeSignal` set to `advisory`:
-
-```
-feature-owners: advisory, the range touches 2 feature owner(s); a reviewer judges whether they make one slice:
-  billing: src/billing/charge.ts, src/billing/tax.ts
-  invoices: src/invoices/tax.ts, tests/e2e/invoices.test.ts
-```
-
-## Opting out
-
-A repository that declares no feature passes.
-`quality.json` refuses a `changeSignal` without features, which would map a change to no owner.
-A repository that tracks no `.ts` or `.tsx` file leaves it out of `gates.lint`, as [Gate selection](checks-lint.md#gate-selection) says.
-
-## Import boundary
-
-`dist/feature-rules.js` compiles `features` into one dependency-cruiser rule per feature, which `.dependency-cruiser.cjs` spreads beside its own:
-
-```js
-const { featureRules } = require("@avi2dg/checks/dist/feature-rules.js");
-
-module.exports = {
-  extends: "./node_modules/@avi2dg/checks/dependency-cruiser.config.js",
-  forbidden: [...featureRules(require("./quality.json"))],
-};
-```
-
-A module outside a feature's root that imports a file inside it must import one of the feature's `entries`.
-Modules under `tests/` and the files `allowFrom` matches, such as a CLI or a harness, may import any file in it:
-
-```
-error feature-billing-entries: src/report.ts → src/billing/charge.ts
-```
-
-`featureRules` decodes its argument with the schema the bins use and throws the schema's refusal when it does not decode, which stops the cruise.
-It is an ES module, as `effect` is, so a `.cjs` config loads it through `require`, which needs node 20.19, 22.12 or later.
-
-## Related topics
-
-- [The dependency rules](../configs/dependency-rules.md)
-- [The quality file](../configs/quality-file.md)

package/docs/gates/checks-quality.md

@@ -1,111 +0,0 @@
-# checks-quality
-
-`checks-quality` is the bin that writes what `quality.json` declares into generated fragments and workflows and checks them, and a reader looks it up when generated text 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"]
-}
-```
-
-GitHub Actions reads its own YAML and nothing else, so `checks-quality generate` also writes the kit recipe workflows whole.
-`.github/workflows/ci.yml` runs every `gates.ci` command but the title lint as its own step after a frozen install.
-`.github/workflows/commitlint.yml` lints the pull request title with the installed kit config.
-Both jobs run on the runner labels `quality.json` `runsOn` lists, or on `ubuntu-latest` when the key is absent.
-A self-hosted runner in a public repository runs the code of any pull request from a fork.
-A step one repository alone needs lives in another workflow file, never in the recipe.
-All generated workflows are committed.
-
-`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`.
-- A generated workflow is missing, or differs from what `generate` would write from `quality.json` and the kit recipe.
-- `.oxlintrc.json` or `tsconfig.json` does not list its fragment in `extends`, so the tool never reads it.
-- `.oxlintrc.json` does not extend `./node_modules/@avi2dg/checks/oxlintrc.json`, so the kit's oxlint rules are not loaded.
-- `tsconfig.json` does not extend `@avi2dg/checks/tsconfig.effect.json`, the one accepted spelling of the kit's Effect config.
-- A `sources.effect.paths` or `sources.production` glob 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`, the two fragments and the generated workflows.
-It reads the root `package.json` name, since only the kit's own tree lints titles with its root `commitlint.config.js`.
-The name also decides which kit configs `extends` must list, since the kit's own tree extends its root `oxlintrc.json` and `tsconfig.effect.json`.
-It looks for `.bun-version` and `.node-version`, and the suite pins its bun and its node to whichever of the two files exists.
-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 and the workflows, removes a left-over one, then runs the same check as `--check`.
-`--check` writes nothing.
-
-## Exit codes
-
-| Code | When |
-| --- | --- |
-| 0 | the generated files hold what `quality.json` declares |
-| 1 | a generated file is stale, missing or left over, a fragment is not extended, the kit's config is 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 generated files hold:
-
-```
-checks-quality: oxlintrc.quality.json and tsconfig.quality.json and .github/workflows/ci.yml and .github/workflows/commitlint.yml hold what quality.json declares
-```
-
-A stale workflow is reported the same way as a stale fragment.
-
-## 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 refuses a left-over one.
-Every repository gets the title lint workflow, and one with `gates.ci` gets the suite with it.
-
-## 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

@@ -1,107 +0,0 @@
-# checks-size-budget
-
-`checks-size-budget` is the gate that holds production and test files to the size 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 and test files to the size budget, and lists every other file over it without failing:
-
-```json
-"sources": { "production": ["src/**/*.ts"] },
-"size": { "applies": "ratchet" }
-```
-
-A production file is one under `sources.production`, and a test file is a tracked `.ts` or `.tsx` file under `tests/`.
-A test file keeps to the tests budget, and every other file keeps to the production budget.
-It runs oxlint with a configuration of five rules, one for each limit, and the kit's own plugin bundle, which holds the complexity rule.
-The kit sets each limit:
-
-<!-- generated size-limits: bun run build writes it from SIZE_RULES and SIZE_DEFAULTS in scripts/size-rules.ts and scripts/doc-blocks.ts -->
-
-| Key | Limits | oxlint rule | Production | Tests |
-| --- | --- | --- | --- | --- |
-| `fileLines` | The most lines a file may hold, blank and comment lines counted | `max-lines` | 400 | 600 |
-| `functionLines` | The most lines a function may span, blank and comment lines counted | `max-lines-per-function` | 100 | none |
-| `statements` | The most statements a function may hold | `max-statements` | 30 | 50 |
-| `complexity` | The highest cognitive complexity a function may reach, a switch counted once | `effect-channel/cognitive-complexity` | 15 | 15 |
-| `depth` | The deepest a block may nest inside a function | `max-depth` | 4 | 4 |
-
-<!-- end generated size-limits -->
-
-`size.production` and `size.tests` state only a limit that differs from the kit's:
-
-```json
-"size": {
-  "applies": "ratchet",
-  "production": { "complexity": 12 },
-  "tests": { "fileLines": 800 }
-}
-```
-
-`applies` decides which files the gate holds and what fails them:
-
-- `ratchet` holds each production and test file the range adds or changes, a rename that edits the file included.
-  For each file and each rule, it sums how far every site runs over its limit, and fails when that sum is higher at the head than at the base of the range.
-  A file the range adds starts from zero, so it has to keep within the budget.
-  A file already over the budget passes while its overrun does not grow, and an edit that shrinks the overrun passes.
-  An edited rename is compared with the file it was renamed from.
-  Nothing is committed as a baseline, because the base of the range holds it.
-- `all` holds every production and test file, and fails on any overrun in them.
-
-`applies` is `ratchet` when `size` leaves it out.
-A file the range deletes or only renames is not held.
-Every other tracked `.ts` or `.tsx` file over the budget, tooling and unchanged files alike, is listed as advisory and never fails the gate.
-Under `ratchet` the advisory list also names each site in a held file whose overrun did not grow.
-`.d.ts` files are not measured.
-
-`quality.json` refuses `applies: "changed"`, which `ratchet` replaces.
-It refuses a limit set directly under `size`, since each limit goes in `size.production` or `size.tests`.
-
-## 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.
-Under `ratchet` it also reads each held file from the base of the range, under the path the file has at the head, so a file keeps the same budget at both ends.
-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, or under `ratchet` no file's overrun grows |
-| 1 | a file it holds runs over the budget, or under `ratchet` a file's overrun grows |
-| 2 | `quality.json` does not decode, a ref does not resolve, or oxlint cannot run |
-
-## Sample output
-
-```
-size-budget: 2 overrun(s) grew past the base in the production and test files the range adds or changes:
-  src/billing/invoice.ts: max-lines over by 31 in total, up from 19
-    src/billing/invoice.ts: File has too many lines (431). Maximum allowed is 400.
-  src/billing/ledger.ts: cognitive-complexity over by 3 in total, up from 0
-    src/billing/ledger.ts:12: function `settle` has a cognitive complexity of 18. Maximum allowed is 15.
-size-budget: advisory, 1 overrun(s) where the budget does not hold yet:
-  tests/e2e/billing.test.ts: File has too many lines (612). Maximum allowed is 600.
-```
-
-## Opting out
-
-A repository that declares no `size` passes.
-`quality.json` refuses a `size` without `sources.production`, and `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 `ratchet` to `all` tightens the budget to every production and test file, once the advisory list names none.
-
-## Related topics
-
-- [The quality file](../configs/quality-file.md)
-- [checks-lint](checks-lint.md)