@avi2dg/checks 0.20.0 → 0.22.0

package/docs/gates/checks-quality.md

@@ -1,109 +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.
-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)