@avi2dg/checks 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.19.0
+
+Released 2026-09-26.
+
+### Features
+
+- **scripts:** judge checks-mutation-compare mutant by mutant instead of by score (#58)
+- **scripts:** fail a test left in tests/quarantine past 30 days (#59)
+- **scripts:** pin shared read-only library clones with checks-vendor (#57)
+
+## 0.18.0
+
+Released 2026-09-26.
+
+### Features
+
+- **scripts:** generate commitlint and CI workflows with checks-quality (#54)
+
+### Fixes
+
+- **scripts:** make checks-quality refuse a config that drops the kit's extends (#55)
+
 ## 0.17.0
 
 Released 2026-09-25.

package/README.md

@@ -123,6 +123,7 @@ A repository leaves out a gate that does not apply to it through `gates.lint`, a
 | [`checks-size-budget`](docs/gates/checks-size-budget.md) | the range | a repository tracking `*.ts` or `*.tsx` |
 | [`checks-repetition`](docs/gates/checks-repetition.md) | the range | a repository tracking `*.ts` or `*.tsx` |
 | [`checks-feature-owners`](docs/gates/checks-feature-owners.md) | the range | a repository tracking `*.ts` or `*.tsx` |
+| [`checks-quarantine-clock`](docs/gates/checks-quarantine-clock.md) | the range | every repository |
 
 <!-- end generated gates -->
 
@@ -130,8 +131,9 @@ These bins run on their own:
 
 - [`checks-test`](docs/gates/checks-test.md) runs the suite as `scripts.test` and refuses a skip the repository has not declared.
 - [`checks-flake`](docs/gates/checks-flake.md) runs the suite on a schedule and records the seeds a flaky test fails with.
-- [`checks-mutation-compare`](docs/gates/checks-mutation-compare.md) holds a pull request's mutation score to no regression.
+- [`checks-mutation-compare`](docs/gates/checks-mutation-compare.md) holds every mutant in a pull request to no regression.
 - [`checks-backtest`](docs/gates/checks-backtest.md) reports what the comment check would have refused in recent history.
+- [`checks-vendor`](docs/gates/checks-vendor.md) pins each library `quality.json` declares to a shared read-only clone and links it under `repos/`.
 
 `checks-lint` has [its own page](docs/gates/checks-lint.md), which says which range it resolves.
 The oxlint base, the dependency-cruiser base and the commitlint config run through their own tools, as the pages under Related topics say.

package/bunfig.toml

@@ -1,2 +1,2 @@
 [test]
-pathIgnorePatterns = ["**/tests/quarantine/**"]
+pathIgnorePatterns = ["**/tests/quarantine/**", "repos/**"]

package/dependency-cruiser.config.js

@@ -72,6 +72,8 @@ export default {
     parser: "swc",
     builtInModules: { add: ["bun"] },
     doNotFollow: { path: ["node_modules"] },
+    // The cruise follows the repos/ links without this.
+    exclude: { path: "^repos/" },
     enhancedResolveOptions: {
       exportsFields: ["exports"],
       conditionNames: ["types", "import", "require", "node", "default"],

package/dist/feature-rules.js

@@ -21,7 +21,8 @@ var KIT_GATES = [
   { bin: "checks-quality", script: "quality.ts", reads: "tree", args: ["--check"], appliesTo: QUALITY_DECLARATION },
   { bin: "checks-size-budget", script: "size-budget.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-repetition", script: "repetition.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
-  { bin: "checks-feature-owners", script: "feature-owners.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE }
+  { bin: "checks-feature-owners", script: "feature-owners.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
+  { bin: "checks-quarantine-clock", script: "quarantine-clock.ts", reads: "range", appliesTo: EVERY_REPOSITORY }
 ];
 var UNCONDITIONAL = KIT_GATES.filter((gate) => gate.appliesTo === EVERY_REPOSITORY).map((gate) => gate.bin);
 var LintGates = Schema.Array(Schema.Literals(KIT_GATES.map((gate) => gate.bin))).check(Schema.makeFilter((selected) => {
@@ -158,8 +159,21 @@ var EffectSources = Schema3.Struct({
   }),
   exempt: Schema3.optionalKey(Schema3.Array(PathGlob).annotate({ description: "Files under paths the Effect rules pass over" }))
 });
+var Library = Schema3.Struct({
+  name: Schema3.String.check(Schema3.isPattern(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, { expected: "a library name in kebab case" })).annotate({ description: "The link checks-vendor manages under repos/" }),
+  package: Schema3.NonEmptyString.annotate({ description: "The npm package whose installed version picks the tag" }),
+  repository: Schema3.NonEmptyString.annotate({ description: "The git remote checks-vendor clones the tag from" }),
+  tag: Schema3.String.check(Schema3.isPattern(/\{version\}/, { expected: "a tag template holding {version}" })).annotate({
+    description: "The tag template, with {version} for the installed version"
+  }),
+  path: Schema3.optionalKey(FilePath.annotate({ description: "The manifest inside the clone holding the version; package.json when absent" }))
+}).annotate({ identifier: "Library" });
 var Sources = Schema3.Struct({
   production: Schema3.optionalKey(Schema3.Array(PathGlob).annotate({ description: "The source the repository ships, as against tests and tooling" })),
+  libraries: Schema3.optionalKey(Schema3.Array(Library).check(Schema3.makeFilter((libraries) => {
+    const repeated = duplicates(libraries.map((library) => library.name));
+    return repeated === undefined || `names ${repeated} more than once`;
+  })).annotate({ description: "The libraries checks-vendor pins to a shared read-only clone" })),
   effect: Schema3.optionalKey(EffectSources)
 });
 var Feature = Schema3.Struct({
@@ -179,11 +193,14 @@ var Feature = Schema3.Struct({
 function nests(outer, inner) {
   return outer === inner || inner.startsWith(`${outer}/`);
 }
-var Features = Schema3.Array(Feature).check(Schema3.makeFilter((features) => {
-  const names = features.map((feature) => feature.name);
+function duplicates(names) {
   const repeated = names.filter((name, index) => names.indexOf(name) !== index);
-  if (repeated.length > 0)
-    return `names ${[...new Set(repeated)].join(", ")} more than once`;
+  return repeated.length === 0 ? undefined : [...new Set(repeated)].join(", ");
+}
+var Features = Schema3.Array(Feature).check(Schema3.makeFilter((features) => {
+  const repeated = duplicates(features.map((feature) => feature.name));
+  if (repeated !== undefined)
+    return `names ${repeated} more than once`;
   for (const outer of features) {
     const inner = features.find((other) => other !== outer && nests(outer.root, other.root));
     if (inner !== undefined)

package/docs/configs/commit-messages.md

@@ -10,24 +10,8 @@ It arrives with the kit, since `@commitlint/cli` and `@commitlint/config-convent
 ## Workflow
 
 The lint runs in CI on pull requests, because `jj` never fires a git hook.
-A repository adds this workflow:
-
-```yaml
-on:
-  pull_request:
-    types: [opened, edited, synchronize, reopened]
-jobs:
-  commitlint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v5
-      - uses: oven-sh/setup-bun@v2
-      - run: bun install --frozen-lockfile
-      - run: printf '%s' "$PR_TITLE (#0000)" > "$RUNNER_TEMP/pr-title"
-        env:
-          PR_TITLE: ${{ github.event.pull_request.title }}
-      - run: ./node_modules/.bin/commitlint --config ./node_modules/@avi2dg/checks/commitlint.config.js --edit "$RUNNER_TEMP/pr-title"
-```
+`checks-quality generate` writes the workflow whole into `.github/workflows/commitlint.yml`, as [checks-quality](../gates/checks-quality.md) says.
+The workflow lints with the installed kit's `commitlint.config.js`, so every repository holds titles to the same rules.
 
 ## What it lints
 

package/docs/configs/quality-file.md

@@ -39,13 +39,14 @@ The kit's bins find the file at the git root and read it there:
 
 | Key | Read by | Holds |
 | --- | --- | --- |
-| `defaultBranch` | `checks-lint`, `checks-ci-wiring` | the branch pull requests merge into, `main` when absent |
-| `gates.ci` | `checks-ci-wiring` | the commands CI runs on every pull request, as [checks-ci-wiring](../gates/checks-ci-wiring.md) says |
+| `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 |
 | `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 |

package/docs/gates/checks-lint.md

@@ -64,7 +64,7 @@ It prints the range, the declared selection if there is one, each gate's own rep
 ```
 checks-lint: range 2504acf098d120e73a8ece3c96f22b934f35c6a8..10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD against origin/main
 ...
-checks-lint: 3 of 11 gate(s) failed: checks-commit-identity, checks-comment-gate, checks-suppressions-ratchet
+checks-lint: 3 of 12 gate(s) failed: checks-commit-identity, checks-comment-gate, checks-suppressions-ratchet
 ```
 
 ## Opting out
@@ -86,6 +86,7 @@ It declares the gates `checks-lint` runs as `gates.lint`:
     "checks-suppressions-ratchet",
     "checks-ci-wiring",
     "checks-docs",
+    "checks-quarantine-clock",
     "checks-quality"
   ]
 }

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

@@ -1,12 +1,22 @@
 # checks-mutation-compare
 
-`checks-mutation-compare` is the gate that holds a pull request's mutation score to no regression rather than an absolute threshold, and a reader looks it up to wire mutation testing into CI.
+`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.
 
 ## What it checks
 
-The head mutation score may not fall below the score at the merge-base.
-The score is Stryker's, `Killed` and `Timeout` over those plus `Survived` and `NoCoverage`, so `CompileError`, `RuntimeError`, `Ignored` and `Pending` mutants leave it.
-Every file in a report counts toward that report's score, including files present in only one of the two.
+A mutant regresses when it is `Killed` or `Timeout` at the base and `Survived` or `NoCoverage` at the head.
+The gate matches mutants between the two reports and judges each match, so a lost kill cannot hide behind mutants that move into the score and a mutant leaving the score cannot manufacture a false regression.
+A matched mutant that moves into or out of `RuntimeError`, `CompileError`, `Ignored` or `Pending` is reported apart from a regression, because that move only changes which mutants leave the score.
+A mutant present in only one report is listed and never fails the comparison.
+
+## How it matches mutants
+
+The gate aligns each file's base and head source, which it reads from the report's copy of the file, by a line diff.
+It maps each base mutant to the place its lines moved to in the head, so a line added or removed above a mutant leaves it matched.
+It then matches a mutant in the base report to a mutant in the head report by its file, that mapped location, its mutator and its replacement.
+Two mutants in the same report can share all four, so the gate also counts the position of each mutant among others with the same four, in the order the report lists them, and adds that position to the key.
+A mutant on a line the pull request added, removed or changed has no counterpart in the other report and lands in the unmatched list.
+Each list prints in order of file, then line, then column, and a matched mutant prints at its place in the head.
 
 ## What it reads
 
@@ -37,19 +47,18 @@ checks-mutation-compare [--advisory] <base-report> <head-report>
 
 | Code | When |
 | --- | --- |
-| 0 | the head score is not below the base score, or `--advisory` is given |
-| 1 | the head score is below the base score |
+| 0 | no mutant regressed, or `--advisory` is given |
+| 1 | a mutant regressed |
 | 2 | a report is not a Stryker mutation report, or the arguments do not parse |
 
 ## Sample output
 
-It prints the overall score of each report and the per-file scores that differ:
+It prints the verdict first, then each regression, each move into or out of a status that leaves the score, and each unmatched mutant:
 
 ```
-mutation-compare: base 83.33% (5/6) head 66.67% (4/6) delta -16.67pp
-  src/billing.ts: 75.00% (3/4) -> 50.00% (2/4)
-  1 unchanged file(s)
-mutation-compare: REGRESSION (-16.67pp)
+mutation-compare: REGRESSION (1 mutant(s))
+  regression src/billing.ts:12:5 ConditionalExpression "true": Killed -> Survived
+  moved src/loader.ts:4:1 ClassDeclaration "class {}": Killed -> RuntimeError
 ```
 
 ## Opting out

package/docs/gates/checks-quality.md

@@ -1,6 +1,6 @@
 # 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.
+`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
 
@@ -29,11 +29,20 @@ A rule only this repository needs stays in its own `.oxlintrc.json`, whose overr
 }
 ```
 
+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:
@@ -47,7 +56,10 @@ Two details of the fragments are easy to get wrong, so the kit's tests pin both:
 
 ## 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 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 the suite pins its bun to that file when the file exists.
 It lists the tracked and untracked files to see what each declared glob matches.
 
 ## Arguments
@@ -57,15 +69,15 @@ checks-quality generate
 checks-quality --check
 ```
 
-`generate` writes the fragments, removes a left-over one, then runs the same check as `--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 fragments hold what `quality.json` declares |
-| 1 | a fragment is stale, missing, left over or not extended, or a declared glob matches no file |
+| 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
@@ -76,16 +88,19 @@ checks-quality: 2 problem(s) with what quality.json declares:
   tsconfig.json does not extend ./tsconfig.quality.json, so the language service never reads it
 ```
 
-A passing run says what the fragments hold:
+A passing run says what the generated files hold:
 
 ```
-checks-quality: oxlintrc.quality.json and tsconfig.quality.json hold what quality.json declares
+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 only refuses a left-over one.
+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
 

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

@@ -0,0 +1,54 @@
+# 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.
+
+## What it checks
+
+It fails naming each test that entered `tests/quarantine/` more than 30 days before the head.
+`checks-test-layout` pins `tests/quarantine/` out of every default run, so a test there protects nothing until it moves back.
+Each failure names the file, the day it entered quarantine, and what to do, which is to fix it and move it back, or delete it.
+The limit is 30 days for every test, with no setting to raise it.
+GitLab quarantines fast for 3 days and long term for at most 3 months, then opens a deletion merge request automatically.
+
+## What it reads
+
+It lists the test files under `tests/quarantine/` at the head, by the name pattern `checks-test-layout` uses, so a helper or fixture there never ages out.
+It walks each file's history with `git log --follow`, so a move or a copy into quarantine starts the clock there rather than at the test's creation.
+It measures the age from the author date of the commit that put the file there to the later of the head's author and committer dates, so the same commit always gets the same verdict.
+A rebase keeps the entry's author date and moves the head's committer date forward, so rebasing neither restarts the clock nor stops it.
+
+## Arguments
+
+```sh
+checks-quarantine-clock <base-ref> <head-ref>
+checks-quarantine-clock <ref>
+```
+
+With two arguments it judges the head, and the base only satisfies the range `checks-lint` hands every range gate.
+With one it judges that commit, including a repository's first commit.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | no test in `tests/quarantine/` is past 30 days |
+| 1 | a test in `tests/quarantine/` is past 30 days |
+| 2 | a ref does not resolve, or the history ends before a file's entry into quarantine, as in a shallow clone |
+
+## Sample output
+
+```
+quarantine-clock: 1 test(s) in tests/quarantine/ is past 30 days; fix each and move it back, or delete it:
+  tests/quarantine/billing.test.ts entered quarantine on 2026-08-01 (45 days ago)
+```
+
+## Opting out
+
+It applies to every repository, so no selection leaves it out.
+A repository with no test file under `tests/quarantine/` passes with nothing checked.
+`checks-lint` runs it over each pull request's range, as [checks-lint](checks-lint.md) says.
+
+## Related topics
+
+- [checks-test-layout](checks-test-layout.md)
+- [checks-lint](checks-lint.md)

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

@@ -18,19 +18,23 @@ It fails unless the repository holds this shape, and names the file and the path
 - `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.
+  `[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/**`.
   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.
+The preset also skips `tests/quarantine/**` and `repos/**` on a default run.
+The `repos/**` entry keeps the suite from following the library links `checks-vendor` manages into trees whose tests are not this repository's.
 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
 ```
 
+A test left there past 30 days fails [checks-quarantine-clock](checks-quarantine-clock.md).
+
 ## What it reads
 
 It reads the working tree.
@@ -38,6 +42,7 @@ It scans the tracked and untracked files that `git ls-files --exclude-standard`
 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.
 
 ## Arguments
 
@@ -53,7 +58,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 or `package.json` does not parse |
+| 2 | a test, a helper, `package.json` or `quality.json` does not parse |
 
 ## Sample output
 
@@ -75,3 +80,4 @@ A repository that tracks one keeps it.
 - [checks-test](checks-test.md)
 - [checks-flake](checks-flake.md)
 - [checks-mutation-compare](checks-mutation-compare.md)
+- [checks-quarantine-clock](checks-quarantine-clock.md)

package/docs/gates/checks-vendor.md

@@ -0,0 +1,97 @@
+# checks-vendor
+
+`checks-vendor` pins each library `quality.json` declares to one shared read-only clone on the machine 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.
+`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.
+Every later run verifies the link rather than trusting it, and does so without contacting the remote.
+It confirms the tree sits on the recorded commit.
+It confirms the manifest inside the tree still names the installed version.
+It confirms no write bit came back and no write landed outside the recorded commit.
+It never follows a link inside the tree, so no mode outside the cache is touched.
+Any failed confirmation fails the run.
+A failed library drops its `repos/<name>` link, so a reader falls back to `node_modules/<package>` rather than a tree the run could not vouch for.
+A missing tag, an unknown installed version or a manifest naming another version fails it too.
+A tag moved upstream after the first fetch is not followed, since a cached tree stays on its recorded commit.
+Clearing the tree with `chmod -R u+w <dir> && rm -rf <dir>` keeps the record, so the next fetch fails when the tag now lands elsewhere.
+A deliberate move also deletes `<tag>.commit` by hand before `checks-vendor` runs again.
+The cache lives at `~/.cache/avi2dg-checks/repos/<host>/<owner>/<repo>/<tag>/`.
+A read through the link resolves outside the checkout, so a reader that must stay inside the tree falls back to `node_modules/<package>`.
+
+## 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.
+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.
+
+## Arguments
+
+```sh
+checks-vendor
+```
+
+It takes no arguments, since `quality.json` names the libraries.
+
+## 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 |
+| 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 |
+
+## Sample output
+
+```
+checks-vendor: cloned effect@4.0.0-rc.115 from https://github.com/Effect-TS/effect.git and linked repos/effect
+```
+
+A fresh fetch reports the tag it cloned and the link it made.
+
+```
+checks-vendor: repos/effect still holds effect@4.0.0-rc.115, verified against its recorded commit
+```
+
+A later run reports the link it kept.
+
+## Wiring
+
+A consuming repository runs it from its `prepare` script, so every install pins and verifies the trees.
+
+```json
+{ "scripts": { "prepare": "checks-vendor" } }
+```
+
+An install offline still passes.
+A cached tree verifies with no network, and a tag that is not cached yet warns, stays unlinked and leaves readers on `node_modules/<package>` until a later install can fetch it.
+An install outside a git checkout, or with no `git` on the path, warns once, links nothing and passes too.
+
+It ignores the links in `.gitignore` with `repos/*`, because `repos/*/` does not match a link.
+
+```gitignore
+repos/*
+```
+
+TypeScript does not read `.gitignore`, and its default `include` follows the links into each library tree.
+A consumer whose `tsconfig.json` has no explicit `include` keeps the trees out with an `exclude` entry.
+
+```json
+{ "exclude": ["node_modules", "repos"] }
+```
+
+## 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.
+
+## Related topics
+
+- [The quality file](../configs/quality-file.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Deterministic checks shared across the captain's TypeScript repos",
   "license": "MIT",
   "repository": {
@@ -32,6 +32,7 @@
     "scripts/commit-identity.ts",
     "scripts/mutation-compare.ts",
     "scripts/ci-wiring.ts",
+    "scripts/shell-command.ts",
     "scripts/comment-matchers.ts",
     "scripts/prose-matchers.ts",
     "scripts/comments.ts",
@@ -41,10 +42,13 @@
     "scripts/quality-file.ts",
     "scripts/quality.ts",
     "scripts/size-budget.ts",
+    "scripts/range-gate.ts",
     "scripts/size-rules.ts",
     "scripts/repetition.ts",
     "scripts/feature-owners.ts",
+    "scripts/quarantine-clock.ts",
     "scripts/docs.ts",
+    "scripts/vendor.ts",
     "scripts/doc-outline.ts",
     "scripts/doc-rules.ts",
     "scripts/doc-references.ts",
@@ -83,7 +87,9 @@
     "./scripts/size-budget.ts": "./scripts/size-budget.ts",
     "./scripts/repetition.ts": "./scripts/repetition.ts",
     "./scripts/feature-owners.ts": "./scripts/feature-owners.ts",
+    "./scripts/quarantine-clock.ts": "./scripts/quarantine-clock.ts",
     "./scripts/docs.ts": "./scripts/docs.ts",
+    "./scripts/vendor.ts": "./scripts/vendor.ts",
     "./templates/readme.md": "./templates/readme.md",
     "./templates/changelog.md": "./templates/changelog.md",
     "./templates/adr.md": "./templates/adr.md",
@@ -118,9 +124,12 @@
     "checks-size-budget": "scripts/size-budget.ts",
     "checks-repetition": "scripts/repetition.ts",
     "checks-feature-owners": "scripts/feature-owners.ts",
-    "checks-docs": "scripts/docs.ts"
+    "checks-quarantine-clock": "scripts/quarantine-clock.ts",
+    "checks-docs": "scripts/docs.ts",
+    "checks-vendor": "scripts/vendor.ts"
   },
   "scripts": {
+    "prepare": "bun scripts/vendor.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",