@avi2dg/checks 0.42.0 → 0.44.0

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

@@ -0,0 +1,140 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-mutation-scope
+
+`checks-mutation-scope` turns a pull request's diff into the files its mutation runs mutate, and prints them as lines for `GITHUB_ENV`.
+
+## What it checks
+
+It picks a scope rather than judging one, so it fails only when it cannot pick one.
+It reads `git diff --name-status -M` from the merge base of `<base>` and `HEAD` to `HEAD`.
+A changed source enters the scope when the repository's own Stryker `mutate` globs match it, with each negated glob applied in order.
+It resolves each glob and each path against the working directory, as Stryker does, so an absolute glob matches too.
+A `mutate` entry with a mutation range, such as `src/a.ts:1-10`, fails the run, since a scope of whole files cannot keep the range.
+`--mutate` replaces those globs, so a path the config excludes, such as `packages/*/src/live/**` or `packages/*/src/bin.ts`, stays out of the scope.
+A renamed source enters under both names, and a deleted source does not enter.
+
+A unit test is a `.test.ts` or `.test.tsx` file under `tests/unit/`, the files the preset's `unitTestFiles` lists.
+A unit test the pull request adds, edits, deletes or renames is changed.
+A unit test that reads a changed file under `tests/` is changed too.
+It reads a file when it imports it, directly or through another file under `tests/`.
+An import resolves as Bun resolves it, to the file it names, then with an extension added, and only then to the directory's `index`.
+A unit test also reads a changed fixture under `tests/fixtures/` when it names the fixture's path or a directory above it.
+Bun loads each `[test] preload` in `bunfig.toml` before every test file.
+So every unit test is changed when the preload list differs between the merge base and `HEAD`.
+The same holds when the pull request changes a preload or a file a preload imports, wherever that file lives.
+
+Each source whose mutants a changed unit test covers or kills in the full baseline report then enters the scope, when it still exists at `HEAD`.
+So a kill lost through a test change alone still shows in the comparison, in a source the pull request leaves alone.
+A changed unit test with no baseline report fails the run rather than reading incomplete coverage.
+Stryker records each test file's source in the report's `testFiles`.
+A changed unit test the merge base holds must have that recorded source match its content at the merge base.
+Otherwise the report ran an older test, so its coverage cannot say what the test covers now.
+The scope then widens to every file at `HEAD` the `mutate` globs match.
+A unit test the pull request adds is new to every report, so it needs no entry.
+Stryker writes no source without mutants into the report, so a mutated source the report lacks may be newer than it.
+When a unit test changed, each such source that exists at `HEAD` enters the scope.
+A change under `tests/e2e/` changes no unit test, so it needs no baseline report.
+The scope trusts the coverage edges of the latest full baseline.
+So a helper, fixture or preload changed on `main` since that baseline can hide a lost kill until the scheduled full baseline refreshes.
+
+## What it reads
+
+- The diff from the merge base to `HEAD`, and the files git tracks at both.
+- The Stryker config file `stryker run` loads from the working directory, such as `stryker.conf.mjs`, for its `mutate` globs.
+  It imports a JavaScript config, so the step runs after `bun install`.
+  With no config file, or a config with no `mutate`, it takes Stryker's default globs.
+- `bunfig.toml` at the merge base and at `HEAD`, for its `[test] preload` entries.
+- Each preload at `HEAD`, and each file it imports through a relative path, for the files the preloads load.
+- Each tracked `.ts` and `.tsx` file under `tests/` from the working tree, for its relative imports and the fixture paths it names.
+- Each changed unit test at the merge base, to match it against the source the report recorded.
+- The full baseline report that `checks-mutation-baseline --full` restores, for each mutant's `coveredBy` and `killedBy` and the `testFiles` that own those tests.
+
+Stryker leaves `coveredBy` empty on a static mutant, so only `killedBy` names its tests.
+The report must come from a run that restored no state and passed `--disableBail`, which lists every killing test.
+
+## Arguments
+
+```sh
+checks-mutation-scope <base> [<full-baseline-report>]
+```
+
+`<base>` is the branch the pull request merges into, such as `origin/main`, or the merge base itself.
+`<full-baseline-report>` is the path the full baseline was restored to, and a path with no file reads as no report.
+
+## Output
+
+It prints one line for each list, as `NAME=a,b`, with each list sorted by path:
+
+| Line | What it lists |
+| --- | --- |
+| `SCOPE` | the files the base and head runs both mutate, empty when nothing in mutation scope changed |
+| `STALE_TESTS` | the unit tests that count as changed only because they read a changed file |
+
+Stryker reads each `--mutate` entry as a glob and turns each backslash into a `/`.
+So `SCOPE` wraps each glob character in a path in a class of its own.
+`app/routes/[id].ts` prints as `app/routes/[[]id[]].ts`, which matches that file and not `app/routes/i.ts`.
+`STALE_TESTS` names each test by its literal path, as the incremental state keys it.
+
+Stryker compares only a test file's own source when it resumes from incremental state.
+A run that resumes from the merge base's state drops each `STALE_TESTS` entry from that state first, so Stryker retests the mutants those tests cover.
+
+On stderr it names each unit test that reads a changed file, and each source a changed unit test brings in.
+It also names each stale test that widens the scope.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | it printed the scope, an empty one included |
+| 2 | the arguments do not parse, git fails, the Stryker config, `bunfig.toml` or the baseline report does not load, a `mutate` entry names a mutation range, or a unit test changed with no baseline report |
+
+## Sample output
+
+A helper change that reaches a source the pull request leaves alone:
+
+```
+mutation-scope: tests/unit/dashboard/snapshot.test.ts reads tests/lib/session-fixture.ts
+mutation-scope: packages/ui/src/layout.ts enters through tests/unit/dashboard/snapshot.test.ts
+SCOPE=packages/session-quota/src/notes.ts,packages/ui/src/layout.ts
+STALE_TESTS=tests/unit/dashboard/snapshot.test.ts
+```
+
+A changed unit test with no full baseline on `main`, on stderr:
+
+```
+mutation-scope: tests/unit/dashboard/snapshot.test.ts changed, but no baseline report at /runner/temp/baseline-full/mutation.json says which sources they cover
+```
+
+A changed unit test that `main` edited after its newest full baseline, on stderr:
+
+```
+mutation-scope: the baseline report did not run tests/unit/dashboard/snapshot.test.ts as the merge base holds it, so every mutated source enters
+```
+
+## When it runs
+
+Only a CI step the repository writes runs it, in the pull request's mutation comparison, before either Stryker run:
+
+```yaml
+- name: Select mutation scope
+  env:
+    GH_TOKEN: ${{ github.token }}
+  run: |
+    base="$(git merge-base HEAD "origin/$GITHUB_BASE_REF")"
+    echo "BASE_SHA=$base" >> "$GITHUB_ENV"
+    bunx checks-mutation-baseline --full "$RUNNER_TEMP/baseline-full/mutation.json"
+    bunx checks-mutation-scope "$base" "$RUNNER_TEMP/baseline-full/mutation.json" >> "$GITHUB_ENV"
+```
+
+Each later step reads `$SCOPE` from the environment, and a failed scope step adds nothing to it.
+[checks-mutation-compare](checks-mutation-compare.md#running-it-in-ci) shows the whole job.
+The full baseline comes from the `mutation` workflow, as [checks-mutation](checks-mutation.md#running-it-in-ci) shows.
+
+## Related topics
+
+- [checks-mutation-compare](checks-mutation-compare.md)
+- [checks-mutation](checks-mutation.md)
+- [checks-mutation-baseline](checks-mutation-baseline.md)

package/docs/gates/checks-mutation.md

@@ -96,17 +96,20 @@ jobs:
         with:
           bun-version-file: .bun-version
       - run: bun install --frozen-lockfile
-      - run: bunx stryker run
-      - if: always()
-        run: bunx checks-mutation-baseline --slim reports/mutation/mutation.json "$RUNNER_TEMP/report/mutation.json"
+      - run: bunx stryker run --disableBail
+      - run: bunx checks-mutation-baseline --slim reports/mutation/mutation.json "$RUNNER_TEMP/full/mutation.json"
       - uses: actions/upload-artifact@v4
-        if: always()
         with:
-          name: mutation-report
-          path: ${{ runner.temp }}/report/mutation.json
-          retention-days: 7
+          name: mutation-baseline-full
+          path: ${{ runner.temp }}/full/mutation.json
+          retention-days: 30
 ```
 
+The run restores no state and passes `--disableBail`, so its report names every test that covers or kills each mutant.
+The upload is the `mutation-baseline-full` artifact that a pull request's scope step restores with `checks-mutation-baseline --full`.
+[checks-mutation-scope](checks-mutation-scope.md) reads it to bring in the sources a changed unit test covers or kills.
+The restore reads only a successful run of `mutation.yml` on `main`, so a sweep that fails publishes nothing a pull request reads.
+The artifact keeps 30 days, so the newest full baseline outlives the week between full runs.
 The upload holds the report without each mutant's `statusReason`, as [checks-mutation-baseline](checks-mutation-baseline.md#the-saved-baselines) says, since the full report of a large repository passes 100 MB as an artifact.
 
 The job runs on the fleet's self-hosted Linux runner labelled `winbox`, which is where a repository sends its full sweeps.
@@ -118,4 +121,5 @@ GitHub sets `CI=true` on every runner, so the preset lets the full run through t
 ## Related topics
 
 - [checks-mutation-compare](checks-mutation-compare.md)
+- [checks-mutation-scope](checks-mutation-scope.md)
 - [checks-subsumed-tests](checks-subsumed-tests.md)

package/docs/gates/checks-no-plain-js.md

@@ -0,0 +1,60 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-no-plain-js
+
+`checks-no-plain-js` is the gate that refuses a plain JavaScript source file in a repository that tracks TypeScript.
+
+## What it checks
+
+It fails on every `.js` or `.mjs` file in the working tree that none of the exemptions below covers.
+Each line names the file and tells its writer to convert it to TypeScript.
+`dist/` holds the committed build output, so the check passes over it.
+`dependency-cruiser.config.js` at the repository root is written by `bun run build` from the TypeScript builder, so the check passes over that one path.
+`node_modules/` and `repos/` hold installed and vendored trees, so the check passes over both.
+`public/` holds assets the server sends verbatim, which no compiler reads, so the check passes over it.
+`tests/fixtures/` holds data the suite never parses, so the check passes over it.
+Stryker loads its config only as JSON or JavaScript, so the check passes over a config file carrying a Stryker config name, such as `stryker.conf.mjs`.
+The Stryker preset ships as `stryker.preset.js` under its documented import path, so the check passes over that name.
+A JavaScript config whose tool also loads TypeScript fails, such as a commitlint or dependency-cruiser config.
+
+## What it reads
+
+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.
+A local run agrees with CI before `git add`.
+
+## Arguments
+
+```sh
+checks-no-plain-js [<directory>]
+```
+
+It checks the directory it runs in, or the directory it is given.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | the working tree holds no plain JavaScript source |
+| 1 | a file in the working tree is plain JavaScript |
+| 2 | git does not list the working tree |
+
+## Sample output
+
+```
+no-plain-js: 2 violation(s)
+  src/legacy.js: plain JavaScript source in a TypeScript repository; convert it to TypeScript
+  tools/build.mjs: plain JavaScript source in a TypeScript repository; convert it to TypeScript
+```
+
+## When it runs
+
+`checks-lint` runs it when the repository tracks TypeScript.
+
+## Related topics
+
+- [checks-lint](checks-lint.md)
+- [checks-test-layout](checks-test-layout.md)
+- [checks-unused](checks-unused.md)

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

@@ -20,12 +20,13 @@ It fails unless the repository holds this shape, and names the file and the path
   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`.
+  Either tier script may add `--parallel=<workers>`.
 - A test runs in-process or in a process of its own.
   A test outside the `e2e`, `live` and `pixel` levels runs in-process, quarantined or not, 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 at the `e2e`, `live` or `pixel` level may do all of it, under `tests/quarantine/` as well.
   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.test` is `checks-test`, optionally with `--parallel=<workers>`, 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/**", "**/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.
@@ -78,7 +79,7 @@ It checks the directory it runs in, or the directory it is given.
 ```
 test-layout: 4 violation(s)
   src/a.test.ts: a test file must live at tests/<level>/**/*.test.ts, or tests/quarantine/<level>/**/*.test.ts while quarantined, with unit, e2e, live, or pixel as the level; move it to tests/unit/a.test.ts
-  package.json: scripts.test must be exactly "checks-test", which runs bun test --randomize and judges its skips, found "bun test"
+  package.json: scripts.test must be "checks-test", optionally with --parallel=<workers>, which runs bun test --randomize and judges its skips, found "bun test"
   package.json: scripts.lint must run the layout check: add "checks-lint"
   bunfig.toml: bunfig.toml is missing; bun has no bunfig extends, so copy node_modules/@avi2dg/checks/bunfig.toml
 ```

package/docs/gates/checks-test.md

@@ -47,9 +47,11 @@ A skipped test or a todo without `skipReason` fails in every environment.
 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.
+The command takes no arguments for the default suite, except the worker count of [Parallel runs](#parallel-runs).
 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.
+Use `checks-test --tier=unit` or `checks-test --tier=e2e` to run only one level of the default suite.
+A live or pixel run clears Bun's ignored paths, runs only `./tests/live` or `./tests/pixel`, and still checks each skip.
+A unit or e2e run keeps Bun's ignored paths, runs only `./tests/unit` or `./tests/e2e`, and still checks each skip.
 
 Files under `tests/quarantine/` are not run or judged, as [checks-test-layout](checks-test-layout.md) says.
 
@@ -72,10 +74,37 @@ Add the matching package scripts when either directory contains tests:
 Bun ignores both directories during the default run.
 `checks-test-layout` requires each tier script when its directory contains a test file.
 
+## Parallel runs
+
+A repository runs its test files in parallel by passing a worker count in its `test` script:
+
+```json
+{
+  "scripts": {
+    "test": "checks-test --parallel=4"
+  }
+}
+```
+
+`checks-test --parallel=<workers>` runs `bun test --randomize --parallel=<workers>`, so Bun hands each test file to one of that many worker processes.
+Each file then runs in a fresh global, so a file cannot lean on state another file left behind.
+The count is a whole number from 1 up, and without the option the suite runs serially in one process.
+Tests still run in random order, and `test.only` still fails the run.
+Bun merges every worker's results into the one JUnit report, so each skipped test and each todo is judged as in a serial run.
+A tier script takes the same option, as in `checks-test --tier=live --parallel=4`.
+[checks-flake](checks-flake.md#parallel-hunts) hunts with the worker count the `test` script sets.
+
+A file whose worker crashes, for example when a test calls `process.exit`, fails the run.
+Bun reports no result from that file, so its skips are not judged and its declarations are not reported as stale.
+
+`checks-test` takes no timings file, because Bun ignores the order a timings file sets whenever `--randomize` is on.
+A timings option waits for Bun to honour timings under random order.
+
 ## Arguments
 
-The default command takes no arguments.
-Its named tier options are `--tier=live` and `--tier=pixel`.
+The default command takes no arguments except `--parallel=<workers>`, as [Parallel runs](#parallel-runs) says.
+Its named tier options are `--tier=live`, `--tier=pixel`, `--tier=unit` and `--tier=e2e`, and a tier run takes `--parallel=<workers>` too.
+Each option appears at most once.
 It refuses test filters because every test excluded by a filter would look skipped.
 
 ## Exit codes
@@ -83,8 +112,8 @@ It refuses test filters because every test excluded by a filter would look skipp
 | Code | When |
 | --- | --- |
 | 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 |
+| 1 | a test failed, a parallel worker crashed, a skip lacks a site reason or a declaration is stale in CI |
+| 2 | an argument is not one it takes, a declaration cannot be read, `CI` is not a boolean or Bun wrote no report |
 
 ## Sample output
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.42.0",
+  "version": "0.44.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "license": "MIT",
   "repository": {
@@ -17,13 +17,14 @@
     "docs/design.md",
     "docs/gates/",
     "bunfig.toml",
-    "commitlint.config.js",
+    "commitlint.config.ts",
     "dependency-cruiser.config.js",
     "knip-base.json",
     "src/quality/lint-coverage.sh",
     "src/core/main.ts",
     "src/core/git.ts",
     "src/core/gates.ts",
+    "src/core/declared-inputs.ts",
     "src/core/lint.ts",
     "src/delivery/changelog.ts",
     "src/delivery/changelog-write.ts",
@@ -39,13 +40,14 @@
     "src/core/swc.ts",
     "src/testing/test-report.ts",
     "src/testing/flake.ts",
+    "src/testing/flake-preload.ts",
     "src/delivery/commit-identity.ts",
     "src/delivery/commit-title.ts",
     "src/delivery/docs-only.ts",
     "src/testing/mutation.ts",
-    "src/testing/mutation-scope.js",
-    "src/testing/mutation-guard-plugin.js",
+    "src/testing/mutation-refusal.ts",
     "src/testing/mutation-compare.ts",
+    "src/testing/mutation-scope.ts",
     "src/testing/mutation-baseline.ts",
     "src/testing/mutation-baseline-saved.ts",
     "src/testing/subsumed-tests.ts",
@@ -71,6 +73,9 @@
     "src/testing/quarantine-clock.ts",
     "src/docs/sentence-length.ts",
     "src/docs/docs.ts",
+    "src/docs/copy.ts",
+    "src/docs/copy-text.ts",
+    "src/docs/copy-html.ts",
     "src/dependencies/vendor.ts",
     "src/dependencies/vendor-args.ts",
     "src/dependencies/cache-root.ts",
@@ -100,6 +105,7 @@
     "dist/effect-channel/index.js",
     "dist/readability/index.js",
     "dist/data-shape/index.js",
+    "dist/mutation/",
     "dist/presets/"
   ],
   "exports": {
@@ -142,6 +148,7 @@
     "checks-mutation": "src/testing/mutation.ts",
     "checks-mutation-compare": "src/testing/mutation-compare.ts",
     "checks-mutation-baseline": "src/testing/mutation-baseline.ts",
+    "checks-mutation-scope": "src/testing/mutation-scope.ts",
     "checks-subsumed-tests": "src/testing/subsumed-tests.ts",
     "checks-ci-wiring": "src/delivery/ci-wiring.ts",
     "checks-comment-gate": "src/quality/comment-gate.ts",
@@ -151,20 +158,24 @@
     "checks-exports": "src/complexity/exports.ts",
     "checks-quarantine-clock": "src/testing/quarantine-clock.ts",
     "checks-docs": "src/docs/docs.ts",
+    "checks-copy": "src/docs/copy.ts",
     "checks-vendor": "src/dependencies/vendor.ts",
     "checks-advisories": "src/dependencies/advisories.ts",
     "checks-secrets": "src/delivery/secrets.ts",
     "checks-frontend-syntax": "src/quality/frontend-syntax.ts",
+    "checks-no-plain-js": "src/quality/no-plain-js.ts",
     "checks-browser": "src/quality/browser/browser.ts",
     "checks-imports": "src/dependencies/imports.ts",
     "checks-effect-scope": "src/quality/effect-scope.ts"
   },
   "scripts": {
     "prepare": "bun src/dependencies/vendor.ts --library effect --package effect --repository https://github.com/Effect-TS/effect.git --tag 'effect@{version}' --path packages/effect/package.json",
-    "build": "bun build src/quality/effect-channel/index.ts --outdir dist/effect-channel --target node --format esm && bun build src/complexity/readability/index.ts --outdir dist/readability --target node --format esm && bun build src/quality/data-shape/index.ts --outdir dist/data-shape --target node --format esm && bun build src/quality/presets/oxlint.ts src/quality/presets/knip.ts src/quality/presets/dependency-cruiser.ts --outdir dist/presets --target node --format esm && tsc -p tsconfig.presets.json && bun scripts/configs-write.ts && bun src/quality/effect-scope.ts && bun scripts/doc-templates-write.ts && bun src/delivery/changelog-write.ts && bun scripts/doc-blocks-write.ts",
+    "build": "bun build src/quality/effect-channel/index.ts --outdir dist/effect-channel --target node --format esm && bun build src/complexity/readability/index.ts --outdir dist/readability --target node --format esm && bun build src/quality/data-shape/index.ts --outdir dist/data-shape --target node --format esm && bun build src/testing/mutation-guard-plugin.ts src/testing/mutation-refusal.ts --outdir dist/mutation --target node --format esm && bun build src/quality/presets/oxlint.ts src/quality/presets/knip.ts src/quality/presets/dependency-cruiser.ts --outdir dist/presets --target node --format esm && tsc -p tsconfig.presets.json && bun scripts/configs-write.ts && bun src/quality/effect-scope.ts && bun scripts/doc-templates-write.ts && bun src/delivery/changelog-write.ts && bun scripts/doc-blocks-write.ts",
     "lint": "oxlint && bun src/core/lint.ts",
     "typecheck": "tsc --noEmit && effect-tsgo diagnostics --project tsconfig.json --format text --strict",
     "test": "bun src/testing/test.ts",
+    "test:unit": "bun src/testing/test.ts --tier=unit",
+    "test:e2e": "bun src/testing/test.ts --tier=e2e --parallel=4",
     "mutate": "bunx stryker run",
     "mutate:incremental": "bunx stryker run --incremental"
   },
@@ -227,7 +238,8 @@
     "@effect/platform-node-shared": "4.0.0",
     "@total-typescript/ts-reset": "0.6.1",
     "commonmark": "0.31.2",
-    "knip": "6.38.0"
+    "knip": "6.38.0",
+    "minimatch": "10.2.6"
   },
   "overrides": {
     "qs": "6.16.0",

package/src/core/declared-inputs.ts

@@ -0,0 +1,76 @@
+import type { BunServices } from "@effect/platform-bun";
+import { Console, Effect, FileSystem, Path, Schema } from "effect";
+import { runMain, Usage } from "./main.ts";
+
+export type Declared = {
+  readonly name: string;
+  readonly file: string;
+  readonly declares: string;
+};
+
+export type Input = {
+  readonly glob: string;
+  readonly files: readonly string[];
+};
+
+export type Violation = {
+  readonly file: string;
+  readonly line: number;
+  readonly column: number;
+  readonly text: string;
+};
+
+export type Verdict<S> = {
+  readonly report: (scan: S) => string;
+  readonly passes: (scan: S) => boolean;
+};
+
+const Declaration = Schema.Struct({ inputs: Schema.NonEmptyArray(Schema.NonEmptyString) });
+
+const decodeDeclaration = Schema.decodeUnknownEffect(Schema.fromJsonString(Declaration));
+
+const readInputs = Effect.fn("readInputs")(function* (root: string, { file, declares }: Declared) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = (yield* Path.Path).join(root, file);
+  if (!(yield* fs.exists(path))) {
+    return yield* new Usage({ message: `${file} is missing, and a repository opts in to this gate by declaring its ${declares} there` });
+  }
+  const { inputs } = yield* decodeDeclaration(yield* fs.readFileString(path)).pipe(
+    Effect.mapError(({ message }) => new Usage({ message: `${file} does not decode: ${message}` })),
+  );
+  return inputs;
+});
+
+export function emptyInputs(inputs: readonly Input[]): readonly Input[] {
+  return inputs.filter(({ files }) => files.length === 0);
+}
+
+export function violationLine({ file, line, column, text }: Violation): string {
+  return `${file}:${line}:${column} ${text}`;
+}
+
+export function inputsReport(name: string, inputs: readonly Input[], problems: readonly string[]): string {
+  const files = new Set(inputs.flatMap((input) => input.files)).size;
+  const scanned = `${files} file(s) from ${inputs.length} declared input(s)`;
+  if (problems.length === 0) return `${name}: no violation in ${scanned}`;
+  return [`${name}: ${problems.length} problem(s) in ${scanned}:`, ...problems.map((problem) => `  ${problem}`)].join("\n");
+}
+
+const declaredGate = Effect.fn("declaredGate")(function* <S, E>(
+  declared: Declared,
+  scanInputs: (root: string, globs: readonly string[]) => Effect.Effect<S, E, BunServices.BunServices>,
+  { report, passes }: Verdict<S>,
+) {
+  const root = (yield* Path.Path).resolve(process.argv[2] ?? ".");
+  const scan = yield* scanInputs(root, yield* readInputs(root, declared));
+  yield* Console.log(report(scan));
+  return passes(scan);
+});
+
+export function runDeclaredGate<S, E extends { readonly message: string }>(
+  declared: Declared,
+  scanInputs: (root: string, globs: readonly string[]) => Effect.Effect<S, E, BunServices.BunServices>,
+  verdict: Verdict<S>,
+): void {
+  runMain(declared.name, declaredGate(declared, scanInputs, verdict));
+}

package/src/core/gates.ts

@@ -40,6 +40,8 @@ const OXLINT_CONFIG: TrackedContent = { pathspecs: ["oxlint.config.ts"], content
 
 const FRONTEND_SYNTAX_DECLARATION: TrackedContent = { pathspecs: ["frontend-syntax.json"], content: "a frontend syntax declaration" };
 
+const COPY_DECLARATION: TrackedContent = { pathspecs: ["copy.json"], content: "a copy declaration" };
+
 export const KIT_GATES = [
   { bin: "checks-lint-coverage", vector: "quality", file: "lint-coverage.sh", reads: "tree", appliesTo: LINTED_SOURCE },
   { bin: "checks-test-layout", vector: "testing", file: "test-layout.ts", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
@@ -47,10 +49,12 @@ export const KIT_GATES = [
   { bin: "checks-comment-gate", vector: "quality", file: "comment-gate.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-effect-scope", vector: "quality", file: "effect-scope.ts", reads: "tree", args: ["--check"], appliesTo: OXLINT_CONFIG },
   { bin: "checks-frontend-syntax", vector: "quality", file: "frontend-syntax.ts", reads: "tree", appliesTo: FRONTEND_SYNTAX_DECLARATION },
+  { bin: "checks-no-plain-js", vector: "quality", file: "no-plain-js.ts", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-suppressions-ratchet", vector: "complexity", file: "suppressions-ratchet.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-ci-wiring", vector: "delivery", file: "ci-wiring.ts", reads: "tree", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-secrets", vector: "delivery", file: "secrets.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-docs", vector: "docs", file: "docs.ts", reads: "range", alsoReads: "every agent file at the head commit", appliesTo: EVERY_REPOSITORY },
+  { bin: "checks-copy", vector: "docs", file: "copy.ts", reads: "tree", appliesTo: COPY_DECLARATION },
   { bin: "checks-repetition", vector: "complexity", file: "repetition.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-unused", vector: "complexity", file: "unused.ts", reads: "tree", appliesTo: LINTED_SOURCE },
   { bin: "checks-exports", vector: "complexity", file: "exports.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },

package/src/core/git.ts

@@ -29,6 +29,15 @@ export const collect = Effect.fn("collect")(
   Effect.scoped,
 );
 
+export const workingTreeFiles = Effect.fn("workingTreeFiles")(function* (root: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const listed = yield* git(["ls-files", "-z", "--cached", "--others", "--exclude-standard"], root);
+  return yield* Effect.filter(listed.split("\0").filter(Boolean), (file) => fs.exists(path.join(root, file)), {
+    concurrency: "unbounded",
+  });
+});
+
 export const git = Effect.fn("git")(function* (args: readonly string[], cwd?: string, feed?: Feed) {
   const failed = (reason: string): GitFailure => new GitFailure({ message: `git ${args.join(" ")}: ${reason.trim()}` });
   const { stdout, stderr, exitCode } = yield* collect("git", args, cwd, feed).pipe(

package/src/delivery/ci-wiring.ts

@@ -17,6 +17,7 @@ export type Gate = {
   readonly command: string;
   readonly words: Command;
   readonly alternatives: readonly Command[];
+  readonly partition: readonly Command[];
 };
 
 export type Declaration = {
@@ -63,6 +64,8 @@ export class WiringError extends Schema.TaggedError<WiringError>()("WiringError"
 
 const WORKFLOWS = ".github/workflows";
 const SCRIPTED = ["lint", "build", "typecheck", "test"];
+const WHOLE_SUITE = "bun run test";
+const SPLIT_SUITE = ["test:unit", "test:e2e"];
 const BUILT_TREE = "git diff --exit-code";
 const TITLE_LINT = "bunx checks-commit-title";
 // The gate holds until every consumer migrates, so the direct commitlint call still counts.
@@ -196,6 +199,21 @@ function entryPointCommand(gate: Command, lintGates: readonly KitGate[]): Comman
   return index === -1 ? undefined : [...gate.slice(0, index), ENTRY_POINT.bin];
 }
 
+type Invocation = Omit<RunStep, "script">;
+
+function invocations(commands: readonly { command: string; words: Command }[], steps: readonly RunStep[]): readonly Invocation[] {
+  return steps.flatMap(({ location, blocker, script }) => {
+    const plain = plainCommand(script);
+    if (commands.some(({ words }) => invokes(plain, words))) return [{ location, blocker }];
+    const mentioned = commands.find(({ words }) => mentions(script, words));
+    if (mentioned === undefined) return [];
+    const alone = `the step runs more than ${mentioned.command}; give it its own step with nothing else in it`;
+    return [{ location, blocker: blocker ?? alone }];
+  });
+}
+
+const runsUnblocked = (invoking: readonly Invocation[]): boolean => invoking.some((step) => step.blocker === undefined);
+
 function gapsAmong(gates: readonly Gate[], steps: readonly RunStep[], lintGates: readonly KitGate[]): readonly Gap[] {
   return gates.flatMap((gate) => {
     const entryPoint = entryPointCommand(gate.words, lintGates);
@@ -204,16 +222,10 @@ function gapsAmong(gates: readonly Gate[], steps: readonly RunStep[], lintGates:
       ...gate.alternatives.map((words) => ({ command: gate.command, words })),
       ...(entryPoint === undefined ? [] : [{ command: entryPoint.join(" "), words: entryPoint }]),
     ];
-    const invoking = steps.flatMap(({ location, blocker, script }) => {
-      const plain = plainCommand(script);
-      if (commands.some(({ words }) => invokes(plain, words))) return [{ location, blocker }];
-      const mentioned = commands.find(({ words }) => mentions(script, words));
-      if (mentioned === undefined) return [];
-      const alone = `the step runs more than ${mentioned.command}; give it its own step with nothing else in it`;
-      return [{ location, blocker: blocker ?? alone }];
-    });
-    if (invoking.some((step) => step.blocker === undefined)) return [];
-    const blocked = invoking.flatMap(({ location, blocker }) =>
+    const invoking = invocations(commands, steps);
+    const parts = gate.partition.map((words) => invocations([{ command: words.join(" "), words }], steps));
+    if (runsUnblocked(invoking) || (parts.length > 0 && parts.every(runsUnblocked))) return [];
+    const blocked = [...invoking, ...parts.flat()].flatMap(({ location, blocker }) =>
       blocker === undefined ? [] : [{ location, blocker }],
     );
     return [{ gate: gate.command, ...(entryPoint === undefined ? {} : { entryPoint: entryPoint.join(" ") }), blocked }];
@@ -252,11 +264,13 @@ export function requiredCommands(scripts: readonly string[]): readonly string[]
 }
 
 export function declarationFor(scripts: readonly string[], branch: string): Declaration {
+  const tiers = SPLIT_SUITE.every((name) => scripts.includes(name)) ? SPLIT_SUITE.map((name) => ["bun", "run", name]) : [];
   return {
     gates: requiredCommands(scripts).map((command) => ({
       command,
       words: command.split(" "),
       alternatives: command === TITLE_LINT ? TITLE_CALLS.map((call) => call.split(" ")) : [],
+      partition: command === WHOLE_SUITE ? tiers : [],
     })),
     defaultBranch: branch,
     lintGates: KIT_GATES,
@@ -277,7 +291,7 @@ function readsOverride(runsOn: unknown): boolean {
 function runnerFault(runsOn: unknown, mutation: boolean, visibility: Visibility): string | undefined {
   const overridden = readsOverride(runsOn);
   const pin = `set runs-on: [${MUTATION_RUNNER.join(", ")}]`;
-  if (mutation && overridden) return `a mutation job reads CI_RUNS_ON, so an override moves its full sweeps off winbox; ${pin}`;
+  if (mutation && overridden) return `a mutation job reads CI_RUNS_ON, so an override moves its mutation runs off winbox; ${pin}`;
   if (mutation) return visibility === "private" && !sameLabels(runsOn, MUTATION_RUNNER) ? `a mutation job in a private repository runs off winbox; ${pin}` : undefined;
   const hosted = typeof runsOn === "string" && HOSTED_OVERRIDE.test(runsOn.trim());
   if (hosted || (visibility !== "private" && !overridden)) return undefined;

package/src/delivery/commit-title.ts

@@ -23,8 +23,8 @@ const cliOf = Effect.fn("cliOf")(function* () {
 // The config ships with the kit, so it sits two levels above this file wherever the kit is installed.
 const configOf = Effect.fn("configOf")(function* () {
   const file = yield* Effect.try({
-    try: () => new URL("../../commitlint.config.js", import.meta.url),
-    catch: () => setup("cannot resolve commitlint.config.js from the installed kit"),
+    try: () => new URL("../../commitlint.config.ts", import.meta.url),
+    catch: () => setup("cannot resolve commitlint.config.ts from the installed kit"),
   });
   return yield* (yield* Path.Path).fromFileUrl(file);
 });