@avi2dg/checks 0.21.0 → 0.22.0

package/docs/gates/checks-lint.md

@@ -1,43 +1,25 @@
+---
+kind: reference
+audience: consumers
+---
 # checks-lint
 
-`checks-lint` is the entry point that runs every lint gate of the kit over one range, and a reader looks it up to learn which range it resolves and how a repository selects its gates.
+`checks-lint` runs every applicable kit lint gate over one range and reports each failure.
 
 ## What it checks
 
-It runs each gate the table under [What runs](../../README.md#what-runs) lists, in that table's order, and names every one that fails rather than stopping at the first.
-Each gate runs as its own bin in a child process, with its output passed straight through, so a gate behaves the same called alone or through `checks-lint`.
-`checks-ci-wiring` always runs, so a repository on `checks-lint` declares `gates.ci`, as [checks-ci-wiring](checks-ci-wiring.md) says.
-It holds the test layout unless the selection leaves out `checks-test-layout`.
+It runs the gates under [What runs](../../README.md#what-runs) in table order, each in its own process.
+Gates requiring tracked TypeScript files begin running when the repository tracks TypeScript.
+All other gates run for every repository.
 
 ## What it reads
 
-It reads `quality.json` for `defaultBranch` and `gates.lint`, and resolves the range once, handing the same one to every range gate.
-A tree gate reads the working tree and is handed no range.
-
-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.
-That branch is `origin/HEAD`.
-When `origin/HEAD` is not set, as in an `actions/checkout` clone, it is `origin/<defaultBranch>` from `quality.json`, and `origin/main` when that is not declared.
-
-In a GitHub Actions pull request, where `GITHUB_EVENT_NAME` is `pull_request`, the range ends at the event's head sha and starts where that branched from `origin/<base branch>`, so GitHub's merge commit is never in it.
-The base branch is read from the fetch, not from the event's recorded base sha, which GitHub leaves stale once the base branch advances after the pull request opens.
-
-The range always starts at the merge base, never at the base branch's tip, since commits the base branch gained after the head branched off would otherwise count against the head.
-When the head is the merge base, as on a push to the default branch or a local run on it, the range would be empty.
-Each range gate is then handed that tip commit alone, and checks it against its parent, or against the empty tree when it is a repository's first commit:
-
-```
-checks-lint: tip 10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD against origin/main
-```
-
-A clone with no remote-tracking refs at all has no default branch to start from, such as a freshly initialised repository with no remote or one whose remote was never fetched.
-Each range gate is then handed `HEAD` alone the same way:
-
-```
-checks-lint: tip 10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD alone, as the clone has no remote-tracking refs
-```
-
-Once any ref sits under `refs/remotes/`, a missing `origin/<default branch>` exits 2 instead.
-That is the shape of a shallow CI checkout, where `HEAD` alone would leave the commits before it unchecked.
+The range ends at `HEAD` and starts at the merge base with `origin/HEAD` for a local run.
+If remote HEAD is absent, the range starts at the default branch GitHub's event names in CI, or at `origin/main`.
+A local run with `GITHUB_BASE_REF` set starts at that branch on `origin` instead.
+A clone with no remote tracking refs checks `HEAD` alone.
+On a pull request the range ends at the event's head commit and starts at its merge base with the event's base branch.
+Tree gates read the working tree rather than the range.
 
 ## Arguments
 
@@ -46,93 +28,29 @@ checks-lint
 checks-lint <base-ref> <head-ref>
 ```
 
-With no arguments it resolves the range as What it reads says.
-A base and a head override that resolution.
+With two arguments, the base and head override range discovery.
 
 ## Exit codes
 
-| Code | When |
+| Code | Result |
 | --- | --- |
-| 0 | every gate passed |
-| 1 | a gate found a violation |
-| 2 | the range or the selection does not resolve, or no failing gate could decide |
+| 0 | Every applicable gate passed. |
+| 1 | At least one gate found a violation. |
+| 2 | The range could not resolve or no failed gate could decide. |
 
 ## Sample output
 
-It prints the range, the declared selection if there is one, each gate's own report, then its verdict:
-
 ```
 checks-lint: range 2504acf098d120e73a8ece3c96f22b934f35c6a8..10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD against origin/main
-...
-checks-lint: 3 of 12 gate(s) failed: checks-commit-identity, checks-comment-gate, checks-suppressions-ratchet
+checks-lint: 1 of 9 gate(s) failed: checks-comment-gate
 ```
 
 ## Opting out
 
-A repository leaves out a gate that does not apply to it, as Gate selection says.
-A repository that runs its gates without `checks-lint` calls each gate's bin in its own CI step and declares each command in `gates.ci`.
-
-## Gate selection
-
-A repository with no TypeScript source gives `checks-lint-coverage`, `checks-test-layout`, `checks-size-budget`, `checks-repetition` and `checks-feature-owners` nothing to check, and test-layout would still refuse its missing `bun test` script and `bunfig.toml`.
-It declares the gates `checks-lint` runs as `gates.lint`:
-
-```json
-"gates": {
-  "ci": ["bun run lint"],
-  "lint": [
-    "checks-commit-identity",
-    "checks-comment-gate",
-    "checks-suppressions-ratchet",
-    "checks-ci-wiring",
-    "checks-docs",
-    "checks-quarantine-clock",
-    "checks-quality"
-  ]
-}
-```
-
-`checks-lint` runs exactly those, in the order of the table under What runs, and every gate 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` keeps.
-
-A selection may leave out only a gate that does not apply, and the Runs in column of the table under What runs says where each gate applies.
-Both `checks-lint` and `checks-ci-wiring` exit 2 on a `gates.lint` that names an unknown gate or leaves out one that applies to every repository.
-`checks-ci-wiring` exits 1 when the selection leaves out a gate the repository's tracked files make applicable, and names the gate and the files:
-
-```
-ci-wiring: quality.json gates.lint leaves out 5 gate(s) this repository's contents make applicable:
-  checks-lint-coverage: the repository tracks TypeScript source (src/widget.ts)
-  checks-test-layout: the repository tracks TypeScript source (src/widget.ts)
-  checks-size-budget: the repository tracks TypeScript source (src/widget.ts)
-  checks-repetition: the repository tracks TypeScript source (src/widget.ts)
-  checks-feature-owners: the repository tracks TypeScript source (src/widget.ts)
-```
-
-It reads the files tracked at the checkout, so the pull request that adds the first TypeScript file is the one refused.
-
-## Running it in CI
-
-CI runs it through `lint`.
-The checkout fetches the whole history, which the merge base needs:
-
-```yaml
-on:
-  pull_request:
-jobs:
-  lint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v5
-        with:
-          fetch-depth: 0
-      - uses: oven-sh/setup-bun@v2
-      - run: bun install --frozen-lockfile
-      - run: bun run lint
-```
+A repository runs `checks-lint` in a pull request workflow with the full git history fetched.
+The gate automatically omits TypeScript gates when no TypeScript file is tracked.
 
 ## Related topics
 
 - [What runs](../../README.md#what-runs)
 - [checks-ci-wiring](checks-ci-wiring.md)
-- [The quality file](../configs/quality-file.md)

package/docs/gates/checks-mutation-compare.md

@@ -1,3 +1,7 @@
+---
+kind: reference
+audience: consumers
+---
 # checks-mutation-compare
 
 `checks-mutation-compare` is the gate that holds every mutant in a pull request to no regression rather than an absolute score, and a reader looks it up to wire mutation testing into CI.

package/docs/gates/checks-quarantine-clock.md

@@ -1,3 +1,7 @@
+---
+kind: reference
+audience: consumers
+---
 # checks-quarantine-clock
 
 `checks-quarantine-clock` is the gate that fails a test left in `tests/quarantine/` past 30 days, and a reader looks it up when a quarantined test went red.

package/docs/gates/checks-repetition.md

@@ -1,32 +1,29 @@
+---
+kind: reference
+audience: consumers
+---
 # checks-repetition
 
-`checks-repetition` is the gate that fails a change adding repeated lines to production code, and a reader looks it up when a production file repeats more lines than it did where the range starts.
+`checks-repetition` refuses an increase in repeated lines across a commit range, in the files `.jscpd.json` holds.
 
 ## What it checks
 
-It runs jscpd over the files `quality.json` declares as production:
+The gate runs jscpd at 50 tokens and 5 lines against the base and head revisions.
+It compares repeated lines for each file, so a decrease in another file never offsets a rise.
+It follows an edited rename back to the original file.
+A file that repeats lines without a rise is advisory.
 
-```json
-"sources": { "production": ["src/**/*.ts"] }
-```
-
-jscpd finds each block of at least 50 tokens and 5 lines that appears twice, within one file or across two.
-A repeated line is a line of a file inside such a block.
-The gate counts the repeated lines of each production file at the head and where the range starts, and fails when a file counts more at the head.
-A renamed file is compared with its count under the old path.
-A block counts only when both copies are in production files, so a test that copies production code changes no count.
-Each file whose count rose is listed with the blocks it repeats and where the other copy is.
+## What it reads
 
-Every other file that repeats lines is listed as advisory and never fails the gate.
-The advisory list names the production files whose count did not rise, and every other tracked `.ts` or `.tsx` file that repeats a block within itself or from another such file.
-`.d.ts` files are not measured.
-Nothing is committed as a baseline, because each run measures where the range starts as well as the head.
+jscpd reads the head's `.jscpd.json` at both ends, so its `path` and `ignore` globs select the files to measure.
 
-## What it reads
+```json
+{ "path": ["src"], "format": ["typescript"], "ignore": ["**/*.d.ts"] }
+```
 
-It reads each file from the commits at the two ends of the range 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` from `quality.json`.
-jscpd must be on `PATH`, as it is under a package script.
+The gate sets the 50 tokens and 5 lines itself, over any the file names.
+A `threshold` the file names never fails the gate, which reads jscpd's report once the scan finishes.
+The bin reads the base and head commits rather than the working tree's file contents.
 
 ## Arguments
 
@@ -35,38 +32,26 @@ checks-repetition <base-ref> <head-ref>
 checks-repetition <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 |
+| Code | Result |
 | --- | --- |
-| 0 | no production file repeats more lines than where the range starts |
-| 1 | a production file repeats more lines than where the range starts |
-| 2 | `quality.json` does not decode, a ref does not resolve, or jscpd cannot run |
+| 0 | No measured file repeated more lines. |
+| 1 | At least one measured file repeated more lines. |
+| 2 | A config or ref is invalid, or jscpd cannot run. |
 
 ## Sample output
 
 ```
-repetition: 1 production file(s) repeat more lines than where the range starts, at 50 tokens and 5 lines:
-  src/billing/refund.ts: 11 repeated line(s), up from 0
-    src/billing/refund.ts:1-11 repeats src/billing/legacy.ts:1-11
-repetition: advisory, 4 file(s) repeat lines the hold does not fail:
-  src/billing/ledger.ts: 11 repeated line(s)
-  src/billing/legacy.ts: 21 repeated line(s)
-  tests/one.test.ts: 11 repeated line(s)
-  tests/two.test.ts: 11 repeated line(s)
+repetition: 1 file(s) .jscpd.json holds repeat more lines than where the range starts, at 50 tokens and 5 lines:
+  src/copy.ts: 10 repeated line(s), up from 0
 ```
 
 ## Opting out
 
-A repository that declares no `sources.production` passes.
-`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.
+When the head holds no `.jscpd.json`, the gate reports that no file was measured.
 
 ## Related topics
 
-- [The quality file](../configs/quality-file.md)
-- [checks-size-budget](checks-size-budget.md)
-- [checks-lint](checks-lint.md)
+- [Native settings](../configs/native-settings.md)
+- [checks-suppressions-ratchet](checks-suppressions-ratchet.md)

package/docs/gates/checks-subsumed-tests.md

@@ -1,3 +1,7 @@
+---
+kind: reference
+audience: consumers
+---
 # checks-subsumed-tests
 
 `checks-subsumed-tests` is the report that lists each test another test subsumes in a Stryker mutation run, and a reader looks it up to judge whether the suite carries tests it no longer needs.

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

@@ -1,3 +1,7 @@
+---
+kind: reference
+audience: consumers
+---
 # 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.

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

@@ -1,3 +1,7 @@
+---
+kind: reference
+audience: consumers
+---
 # 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.
@@ -10,16 +14,20 @@ It fails unless the repository holds this shape, and names the file and the path
   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.
+- `tests/live/**` holds tests that need a live machine, and `tests/pixel/**` holds tests that need a display.
+  Bun ignores both directories in the default suite.
+  A live tier with test files requires `test:live` set to `checks-test --tier=live`.
+  A pixel tier with test files requires `test:pixel` set to `checks-test --tier=pixel`.
 - 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`.
+  A test outside `tests/e2e/`, `tests/live/` and `tests/pixel/` 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.
+  A test inside `tests/e2e/`, `tests/live/` or `tests/pixel/` 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 the preset's `["**/tests/quarantine/**", "repos/**"]`, which the check pins itself, so the kit's own repository, whose bunfig is the preset, cannot drift it either.
-  A repository whose `quality.json` declares no `sources.libraries` may hold `["**/tests/quarantine/**"]` instead, and one that declares them must keep `repos/**`.
+  `[test].pathIgnorePatterns` is the preset's `["**/tests/quarantine/**", "**/tests/live/**", "**/tests/pixel/**", "repos/**"]`, which the check pins itself, so the kit's own repository, whose bunfig is the preset, cannot drift it either.
+  The check also accepts the list without `repos/**`, so a repository that links no library under `repos/` may drop it.
   Other tables, and extra `[test]` keys, are the repository's own.
 
 The in-process half is what a mutation run can mutate.
@@ -41,8 +49,8 @@ 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.
-It reads `quality.json` for `sources.libraries`, which decides whether `repos/**` is pinned.
+It reads `package.json` for `scripts.test` and `scripts.lint`.
+It also checks `test:live` and `test:pixel` when their directories contain test files, and compares `bunfig.toml` with the preset the installed kit ships.
 
 ## Arguments
 
@@ -58,7 +66,7 @@ It checks the directory it runs in, or the directory it is given.
 | --- | --- |
 | 0 | the repository holds the layout |
 | 1 | a file breaks the layout |
-| 2 | a test, a helper, `package.json` or `quality.json` does not parse |
+| 2 | a test, a helper or `package.json` does not parse |
 
 ## Sample output
 
@@ -72,7 +80,7 @@ test-layout: 4 violation(s)
 
 ## 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`.
+`checks-lint` runs this gate when the repository tracks TypeScript, so a repository without TypeScript needs neither the test script nor bunfig.
 A repository that tracks one keeps it.
 
 ## Related topics

package/docs/gates/checks-test.md

@@ -1,64 +1,96 @@
+---
+kind: reference
+audience: consumers
+---
 # 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.
+`checks-test` runs the test suite and rejects skips without a reason at the test site.
 
 ## 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`.
+It runs the default suite with `bun test --randomize` and reads Bun's JUnit report from that run.
+Bun exits zero when tests skip, so `checks-test` checks every skipped test against its source declaration.
+A test that `test.skip`, `test.skipIf`, `test.if`, `test.todo` or an enclosing `describe.skip` skips fails unless the test declares its reason.
 
-A declaration names the test and says why it skips:
+Import `skipReason` from `@avi2dg/checks/scripts/test-skips.ts` beside the native Bun test call:
 
-```json
-"testSkips": [
-  {
-    "file": "tests/e2e/docker.test.ts",
-    "test": "images > builds the release image",
-    "reason": "the runner has no docker daemon",
-    "when": "ci"
-  }
-]
+```ts
+import { skipReason } from "@avi2dg/checks/scripts/test-skips.ts";
+
+test.skipIf(!hasNix)(
+  skipReason("Nix is unavailable", "loads the theme"),
+  () => loadTheme(),
+);
 ```
 
-`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.
+`skipReason` requires a literal reason and a literal test name.
+It returns the test name unchanged, and `checks-test` reads the reason, the name and the source line from the test file.
+The Bun call stays at the test site so the JUnit report points to the line where its first argument starts.
+Use `test.skip(skipReason(reason, name), fn)` for an unconditional skip and `test.todo(skipReason(reason, name))` for a todo.
+A skip is declared on the test itself and only there.
+`checks-test` refuses `skipReason` on `describe.skip`, `describe.skipIf` or `describe.if`, so declare each test inside the describe instead.
+
+Add `"ci"` or `"local"` as the third `skipReason` argument when a declaration applies to one environment.
+Omit the third argument when it applies in both environments.
+A declaration for the other environment is not judged in the current run.
 
-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.
+A declaration whose test passes or does not register fails a CI run.
+A local run warns about the same declaration because a condition can depend on the machine.
+A skipped test or a todo without `skipReason` fails in every environment.
 
 ## 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.
+`checks-test` reads test source files and the JUnit report written by its own run.
+It does not read a skip list from `package.json`.
+It counts a run as `ci` when `CI` is true and as `local` otherwise.
+
+The command takes no arguments for the default suite.
+Use `checks-test --tier=live` or `checks-test --tier=pixel` for a named test tier.
+A tier run clears Bun's ignored paths, runs only `./tests/live` or `./tests/pixel`, and still checks each skip.
+
+Files under `tests/quarantine/` are not run or judged, as [checks-test-layout](checks-test-layout.md) says.
+
+## Test tiers
+
+Tests that need a live machine go in `tests/live/`, and tests that need a screen go in `tests/pixel/`.
+For example, a test under `tests/e2e/stack/` that skips when Nix is missing moves to the same path under `tests/live/stack/`.
+Its skip declares `skipReason("Nix is unavailable", name)` inside its `test.skipIf` call.
+Add the matching package scripts when either directory contains tests:
+
+```json
+{
+  "scripts": {
+    "test:live": "checks-test --tier=live",
+    "test:pixel": "checks-test --tier=pixel"
+  }
+}
+```
+
+Bun ignores both directories during the default run.
+`checks-test-layout` requires each tier script when its directory contains a test file.
 
 ## 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.
+The default command takes no arguments.
+Its named tier options are `--tier=live` and `--tier=pixel`.
+It refuses test filters because every test excluded by a filter would look skipped.
 
 ## 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 |
+| 0 | every test passed and every skip has a matching site reason |
+| 1 | a test failed, a skip lacks a site reason or a declaration is stale in CI |
+| 2 | a declaration cannot be read, `CI` is not a boolean or Bun wrote no 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
+checks-test: 1 skipped test(s) undeclared in this local run:
+  tests/pricing.test.ts:12 rounds half to even: skipped with no reason at its test site; use test.skipIf(condition)(skipReason(reason, name), fn)
 ```
 
-A run with nothing skipped ends with:
+A run with no skipped tests ends with:
 
 ```
 checks-test: no test skipped
@@ -66,10 +98,10 @@ 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.
+A repository that tracks no TypeScript source does not need `checks-test`, as [checks-test-layout](checks-test-layout.md) says.
 
 ## Related topics
 
 - [checks-test-layout](checks-test-layout.md)
 - [checks-flake](checks-flake.md)
+- [checks-quarantine-clock](checks-quarantine-clock.md)

package/docs/gates/checks-vendor.md

@@ -1,11 +1,15 @@
+---
+kind: reference
+audience: consumers
+---
 # checks-vendor
 
-`checks-vendor` pins each library `quality.json` declares to one shared read-only clone on the machine and links it under `repos/`.
+`checks-vendor` pins each library its arguments name to one shared read-only clone and links it under `repos/`.
 
 ## What it checks
 
-Each entry under `sources.libraries` names an npm package, a git remote and a tag template holding `{version}`.
-Its `name` is the link under `repos/`, and its optional `path` is the manifest inside the clone that holds the version, `package.json` when absent.
+Each `--library` names an npm package, a git remote and a tag template holding `{version}`.
+Its name is the link under `repos/`, and its optional `--path` is the manifest inside the clone that holds the version, `package.json` when absent.
 `checks-vendor` reads the installed version from `node_modules/<package>/package.json` and resolves the template to one tag.
 It clones that tag once into a cache shared across repositories, records the landed commit in `<tag>.commit` beside the tree, strips every write bit and links `repos/<name>` to the tree.
 The clone is staged beside its cache entry and moves into place only once it is recorded, checked and read only, so a concurrent or killed first run never leaves a half built tree there.
@@ -26,7 +30,7 @@ A read through the link resolves outside the checkout, so a reader that must sta
 ## What it reads
 
 It reads the working tree.
-That is `quality.json`, `node_modules/<package>/package.json` for each declared library and the `repos/` links.
+That is `node_modules/<package>/package.json` for each named library and the `repos/` links.
 It reads the shared cache outside the checkout.
 That is each tag tree, its recorded commit and its manifest.
 It contacts a remote only when a tag is not cached yet, to confirm the tag exists and to clone it.
@@ -34,18 +38,21 @@ It contacts a remote only when a tag is not cached yet, to confirm the tag exist
 ## Arguments
 
 ```sh
-checks-vendor
+checks-vendor [--library <name> --package <package> --repository <remote> --tag <template> [--path <manifest>]]...
 ```
 
-It takes no arguments, since `quality.json` names the libraries.
+Each `--library` opens one library, and the flags after it up to the next `--library` describe it.
+`--package`, `--repository` and `--tag` are required, and `--path` is optional.
+A name is lowercase words joined by hyphens, and no two libraries share one.
+With no arguments it pins nothing.
 
 ## Exit codes
 
 | Code | When |
 | --- | --- |
-| 0 | every declared library links a verified tree, its remote could not be reached for a first fetch, or no git checkout holds the run |
+| 0 | every named library links a verified tree, its remote could not be reached for a first fetch, or no git checkout holds the run |
 | 1 | a tag is missing or lands elsewhere than its record, an installed version is unknown, a tree was written to, a record disagrees with its tree, a version disagrees or a link is blocked |
-| 2 | `quality.json` does not decode, `HOME` is unset, or arguments were passed |
+| 2 | an argument is unknown, missing, repeated or malformed, or `HOME` is unset |
 
 ## Sample output
 
@@ -66,7 +73,7 @@ A later run reports the link it kept.
 A consuming repository runs it from its `prepare` script, so every install pins and verifies the trees.
 
 ```json
-{ "scripts": { "prepare": "checks-vendor" } }
+{ "scripts": { "prepare": "checks-vendor --library effect --package effect --repository https://github.com/Effect-TS/effect.git --tag 'effect@{version}' --path packages/effect/package.json" } }
 ```
 
 An install offline still passes.
@@ -88,10 +95,10 @@ A consumer whose `tsconfig.json` has no explicit `include` keeps the trees out w
 
 ## Opting out
 
-It runs only in a repository that declares `sources.libraries`.
-A repository without that key reports nothing to pin and changes nothing.
-A repository that declares no library needs no `prepare` entry for it.
+It pins sources only for the libraries its arguments name.
+A run with no arguments reports nothing to pin and changes nothing.
+A repository that pins no library needs no `prepare` entry for it.
 
 ## Related topics
 
-- [The quality file](../configs/quality-file.md)
+- [Native settings](../configs/native-settings.md)