@avi2dg/checks 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.20.0
+
+Released 2026-09-26.
+
+### Features
+
+- **scripts:** pin node from .node-version in the generated CI workflow (#64)
+- **scripts:** add checks-subsumed-tests to report tests another test subsumes in a (#62)
+
+### Fixes
+
+- **scripts:** lint a PR title that starts with # in the generated commitlint workflow (#63)
+
+## 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.

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,10 @@ 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-subsumed-tests`](docs/gates/checks-subsumed-tests.md) lists each test another test subsumes in a mutation run.
 - [`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

@@ -18,6 +18,7 @@ The workflow lints with the installed kit's `commitlint.config.js`, so every rep
 It lints the pull request title and nothing else.
 The title is the enforced subject because a squash merge uses it as the main commit subject, and per-commit messages are not linted.
 GitHub appends ` (#N)` to the squashed subject, so the workflow lints the title with that suffix attached, and the header length limit applies to the landed subject, not the bare title.
+The workflow moves git's comment character off `#`, so a title starting with `#` is linted like any other.
 
 It never sees a commit's author or committer fields, nor the `Co-authored-by` trailer GitHub writes from a foreign author when it squashes, so it cannot enforce who a commit belongs to.
 [checks-commit-identity](../gates/checks-commit-identity.md) is that enforcement.

package/docs/configs/quality-file.md

@@ -46,6 +46,7 @@ The kit's bins find the file at the git root and read it there:
 | `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

@@ -59,7 +59,7 @@ Two details of the fragments are easy to get wrong, so the kit's tests pin both:
 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 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

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-subsumed-tests.md

@@ -0,0 +1,68 @@
+# 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.
+
+## What it checks
+
+It checks nothing and fails nothing.
+It reads one Stryker `mutation.json` report, gives each test the set of mutants it kills, and prints each test whose kill set sits inside the kill set of one other test beside that test, with both kill counts.
+It then prints the tests whose kill sets are identical, then the size of a greedy cover that keeps every kill out of every test the report lists.
+A test is subsumed when its kill set sits inside the kill set of one other test, so dropping every subsumed test loses no kill in this run.
+The report informs a person and decides nothing, so keep a subsumed test unless reading the pair shows the same scenario.
+A subsumed verdict trusts the mutants the run covers, so read the files the report names before judging a test redundant.
+A test judged against a module that is not its subject looks redundant until its own subject is mutated.
+A test whose subject no mutant can touch, such as frontmatter or links, looks redundant because mutation cannot see what it checks.
+
+## What it reads
+
+It reads one Stryker `mutation.json` report built with bail off, which the shared Stryker preset's `json` reporter writes to `reports/mutation/mutation.json`.
+With `disableBail` Stryker runs every covering test for each mutant and records every test that fails as a killer, so each test gets a kill set.
+A report built with bail on records one killer per mutant, which makes every test look unique.
+Stryker writes its options into the report's `config`, so `checks-subsumed-tests` refuses a report whose `config.disableBail` is not `true`.
+A report with no `config` shows nothing about bail, so `checks-subsumed-tests` prints one warning and reads it anyway.
+Build a bail-off report with this command:
+
+```sh
+bunx stryker run --disableBail
+```
+
+The report records each killer as a test index, so it names each test by its file and its name from the report's `testFiles` table.
+
+## Arguments
+
+```sh
+checks-subsumed-tests <mutation-report>
+```
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | the report printed |
+| 2 | the report is not a Stryker mutation report, it was built with bail on, or the arguments do not parse |
+
+## Sample output
+
+It prints the files the run mutated, then each subsumed test beside the test that subsumes it, then the tests whose kill sets are identical, then the greedy cover:
+
+```
+subsumed-tests: 2 file(s) mutated
+  mutated src/add.ts
+  mutated src/mul.ts
+subsumed tests (1):
+  "tests/add.test.ts > add sums two numbers" (1 kill) subsumed by "tests/add.test.ts > add covers every operator" (3 kills)
+identical kill sets (1 group(s)):
+  "tests/mul.test.ts > mul multiplies" (2 kills) = "tests/mul.test.ts > mul multiplies in either order" (2 kills)
+greedy cover: 3 of 6 test(s) keep all 6 kill(s)
+  cover "tests/add.test.ts > add covers every operator"
+  cover "tests/mul.test.ts > mul multiplies"
+  cover "tests/mul.test.ts > mul checks its guard"
+```
+
+## Opting out
+
+Nothing runs it but a person who wants the figures.
+
+## Related topics
+
+- [checks-mutation-compare](checks-mutation-compare.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.18.0",
+  "version": "0.20.0",
   "description": "Deterministic checks shared across the captain's TypeScript repos",
   "license": "MIT",
   "repository": {
@@ -31,6 +31,7 @@
     "scripts/flake.ts",
     "scripts/commit-identity.ts",
     "scripts/mutation-compare.ts",
+    "scripts/subsumed-tests.ts",
     "scripts/ci-wiring.ts",
     "scripts/shell-command.ts",
     "scripts/comment-matchers.ts",
@@ -46,7 +47,9 @@
     "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",
@@ -73,6 +76,7 @@
     "./scripts/flake.ts": "./scripts/flake.ts",
     "./scripts/commit-identity.ts": "./scripts/commit-identity.ts",
     "./scripts/mutation-compare.ts": "./scripts/mutation-compare.ts",
+    "./scripts/subsumed-tests.ts": "./scripts/subsumed-tests.ts",
     "./scripts/ci-wiring.ts": "./scripts/ci-wiring.ts",
     "./scripts/comment-matchers.ts": "./scripts/comment-matchers.ts",
     "./scripts/prose-matchers.ts": "./scripts/prose-matchers.ts",
@@ -85,7 +89,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",
@@ -112,6 +118,7 @@
     "checks-flake": "scripts/flake.ts",
     "checks-commit-identity": "scripts/commit-identity.ts",
     "checks-mutation-compare": "scripts/mutation-compare.ts",
+    "checks-subsumed-tests": "scripts/subsumed-tests.ts",
     "checks-ci-wiring": "scripts/ci-wiring.ts",
     "checks-comment-gate": "scripts/comment-gate.ts",
     "checks-suppressions-ratchet": "scripts/suppressions-ratchet.ts",
@@ -120,9 +127,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",