@avi2dg/checks 0.71.0 → 0.73.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.73.0
+
+Released 2026-11-07.
+
+### Features
+
+- **testing:** run unit tier plus touched e2e files with checks-test --changed [#61](https://github.com/avi2d/checks/pull/61)
+
+## 0.72.0
+
+Released 2026-11-07.
+
+### Features
+
+- **checks-setup:** write root AGENTS.md and CLAUDE.md when absent [#60](https://github.com/avi2d/checks/pull/60)
+
 ## 0.71.0
 
 Released 2026-11-07.

package/docs/bins.md

@@ -44,6 +44,7 @@ A whole-tree-run workflow the repository writes runs them with `checks-lint --wh
 These bins run on their own:
 
 - [`checks-test`](gates/checks-test.md) runs the suite as `scripts.test` and refuses a skip without a reason at its test site.
+  With `--changed` it runs only the unit tier and the e2e test files a change touches.
 - [`checks-flake`](gates/checks-flake.md) runs the suite when started by hand and records the seeds a flaky test fails with.
 - [`checks-mutation`](gates/checks-mutation.md) runs Stryker for scoped checks and refuses a full run outside CI.
 - [`checks-mutation-compare`](gates/checks-mutation-compare.md) compares the mutants of two reports and lists each one that regresses.

package/docs/gates/checks-setup.md

@@ -31,6 +31,7 @@ A `--private` run pins each job to `${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}`.
 Setting the `CI_RUNS_ON` variable to a self-hosted runner label then lands the jobs there.
 A public run pins each job to `ubuntu-latest`.
 It copies each kit template under `dist/templates/` into `templates/`, so a new doc file starts from a copy there.
+It copies `dist/templates/agents.md` to `AGENTS.md` and `dist/templates/claude.md` to `CLAUDE.md` when the root lacks them, and keeps either file it finds.
 It names every file it wrote and every file it kept.
 It tells the owner to declare the repository owners in `package.json` `author` or `contributors` before the first commit.
 
@@ -69,6 +70,8 @@ checks-setup: set the CI_RUNS_ON variable to a self-hosted runner label so the n
 
 A repository owner runs it once in a new repository, before the first install.
 Declare the repository owners in `package.json` `author` or `contributors` before the first commit.
+Fill `AGENTS.md` with what an agent cannot infer from the code before the first commit.
+`checks-docs` fails on the unfilled placeholder entry until it is filled.
 Running it again with the same kit version changes nothing.
 A later kit release arrives through [Upgrade the kit](../how-to/upgrade-the-kit.md).
 

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

@@ -27,7 +27,7 @@ It fails unless the repository holds this shape, and names the file and the path
   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 `checks-test`, optionally with `--parallel=<workers>`, which runs `bun test --randomize --parallel=<workers>` as [checks-test](checks-test.md#parallel-runs) says.
-  It refuses `--full`, so a local run stays capped.
+  It refuses `--full` and `--changed`, so a local run stays capped and CI still runs the suite it reaches.
 - `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.

package/docs/gates/checks-test.md

@@ -8,7 +8,7 @@ audience: consumers
 
 ## What it checks
 
-It runs the unit tier plus the smoke list outside CI and the full suite under CI.
+It runs the unit tier plus the smoke list outside CI and the full suite under CI, except a `--changed` run, as [Changed-file runs](#changed-file-runs) says.
 It runs them with `bun test --randomize --parallel=<workers>`, as [Parallel runs](#parallel-runs) says, and reads Bun's JUnit report from that run.
 It runs Bun with `CI=true`, so `test.only` fails the run in every environment.
 Bun exits zero when tests skip, so `checks-test` checks every skipped test against its source declaration.
@@ -46,13 +46,14 @@ A skipped test or a todo without `skipReason` fails in every environment.
 
 `checks-test` reads test source files and the JUnit report written by its own run.
 A pull request run also reads the event file, the git history between the base and the head, the tracked sources, `package.json` and `bunfig.toml`.
+A `--changed` run also reads the git history since the merge base with `origin/<default branch>`, the working tree diff and the untracked files, as [Changed-file runs](#changed-file-runs) says.
 It reads no skip list from `package.json`, only the smoke list.
 It counts a run as `ci` when `CI` is true and as `local` otherwise.
-A local run covers `./tests/unit` plus the smoke list the repository declares.
+A local run covers `./tests/unit` plus the smoke list the repository declares, except a `--changed` run, as [Changed-file runs](#changed-file-runs) says.
 The smoke list lives in `package.json` under `checks.smoke` as an array of test file paths.
 A repository with no smoke list runs the unit tier alone outside CI.
 A local run with no unit test and no smoke list runs nothing and passes.
-A `ci` run covers the full default suite, unless a pull request narrows it, as [Pull request runs](#pull-request-runs) says.
+A `ci` run covers the full default suite, unless a pull request narrows it or `--changed` narrows it, as [Pull request runs](#pull-request-runs) and [Changed-file runs](#changed-file-runs) say.
 A smoke entry that names no test file fails the run.
 A smoke entry under `tests/quarantine/`, `tests/live/` or `tests/pixel/` fails the run, since Bun's ignored paths would drop it.
 
@@ -98,6 +99,25 @@ A run on any other event, such as `workflow_dispatch` for a release, runs the wh
 `--full` and the live and pixel tiers always run whole.
 A narrowed run judges only the skips the files it ran declare.
 
+## Changed-file runs
+
+`checks-test --changed` runs the unit tier and each e2e test file the change touches, so a desk run stays short.
+The change is every path between where `HEAD` branched from `origin/<default branch>` and `HEAD`, plus the working tree's edits and its untracked files.
+A deleted file drops out, and a renamed file counts under its new name.
+An e2e test file is a `.test.ts` or `.test.tsx` file under `tests/e2e/`, so a helper under `tests/e2e/lib/` and a quarantined test never run.
+The run names each e2e test file it picked, or says the change touches none and only the unit tier runs.
+It judges the skips of the files it ran, as any other run does.
+A clone with no remote-tracking default branch fails before any test runs and asks for a fetch of it.
+A repository runs it from a script of its own, such as:
+
+```json
+{
+  "scripts": {
+    "test:fast": "checks-test --changed"
+  }
+}
+```
+
 ## Test tiers
 
 Tests that need a live machine go in `tests/live/`, and tests that need a screen go in `tests/pixel/`.
@@ -146,9 +166,11 @@ A timings option waits for Bun to honour timings under random order.
 
 ## Arguments
 
-The default command takes no arguments except `--parallel=<workers>`, as [Parallel runs](#parallel-runs) says, `--full` and `--junit=<file>`.
+The default command takes no arguments except `--parallel=<workers>`, as [Parallel runs](#parallel-runs) says, `--full`, `--changed` and `--junit=<file>`.
 `--full` runs the full suite outside CI, so a run started by hand covers what a local run skips.
 A `package.json` script never takes `--full`, as [checks-test-layout](checks-test-layout.md) says of `scripts.test`.
+`--changed` runs the unit tier and the e2e test files the change touches, as [Changed-file runs](#changed-file-runs) says, and takes neither a tier nor `--full`.
+`scripts.test` never takes `--changed` either, so CI still runs the suite it reaches.
 Its named tier options are `--tier=live`, `--tier=pixel`, `--tier=unit` and `--tier=e2e`, and a tier run takes `--parallel=<workers>` too, but not `--full`.
 `--junit=<file>` keeps the JUnit report Bun wrote at `<file>`, whether the tests passed or failed, so a whole-tree run hands it to [checks-whole-tree-run](checks-whole-tree-run.md).
 A `package.json` script never takes `--junit`, as [checks-test-layout](checks-test-layout.md) says of `scripts.test`.
@@ -161,7 +183,7 @@ It refuses test filters because every test excluded by a filter would look skipp
 | --- | --- |
 | 0 | every test passed and every skip has a matching site reason |
 | 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 or the smoke list cannot be read, a smoke entry names no runnable test, `CI` is not a boolean or Bun wrote no report |
+| 2 | an argument is not one it takes, a declaration or the smoke list cannot be read, a smoke entry names no runnable test, `CI` is not a boolean, Bun wrote no report or a `--changed` run cannot find where `HEAD` branched from `origin/<default branch>` |
 
 ## Sample output
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.71.0",
+  "version": "0.73.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "author": {
     "name": "avi2d",
@@ -55,6 +55,7 @@
     "src/testing/test.ts",
     "src/testing/test-skips.ts",
     "src/testing/affected-tests.ts",
+    "src/testing/changed-tests.ts",
     "src/core/swc.ts",
     "src/testing/test-report.ts",
     "src/testing/flake.ts",
@@ -221,7 +222,7 @@
     "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:fast": "bun scripts/test-fast.ts",
+    "test:fast": "bun src/testing/test.ts --changed",
     "test:unit": "bun src/testing/test.ts --tier=unit",
     "test:e2e": "bun src/testing/test.ts --tier=e2e --parallel=4",
     "test:live": "bun src/testing/test.ts --tier=live",

package/src/complexity/graphwalk.ts

@@ -2,7 +2,7 @@
 import { BunServices } from "@effect/platform-bun";
 import { Config, Console, Duration, Effect, FileSystem, Path, Schema } from "effect";
 import { LINTED_SOURCE, TYPESCRIPT_SOURCE, type TrackedContent } from "../core/gates.ts";
-import { checkoutFiles, collect, commitOf, git, pathsAt, rangeEnds, refArgs } from "../core/git.ts";
+import { checkoutFiles, collect, commitOf, existingFiles, git, pathsAt, rangeEnds, refArgs } from "../core/git.ts";
 import { PASSED, runExitMain, UNDECIDED, Usage, VIOLATED } from "../core/main.ts";
 import { knipReport } from "./knip.ts";
 
@@ -233,10 +233,8 @@ const depcruise = Effect.fn("depcruise")(function* () {
 });
 
 const trackedInTree = Effect.fn("trackedInTree")(function* (root: string) {
-  const fs = yield* FileSystem.FileSystem;
-  const path = yield* Path.Path;
   const listed = yield* git(["ls-files", "-z", "--", ...CRUISED], root);
-  return yield* Effect.filter(listed.split("\0").filter(Boolean), (file) => fs.exists(path.join(root, file)), { concurrency: "unbounded" });
+  return yield* existingFiles(root, listed.split("\0").filter(Boolean));
 });
 
 const runSection = Effect.fn("runSection")(function* (

package/src/core/git.ts

@@ -32,13 +32,17 @@ export const collect = Effect.fn("collect")(
   Effect.scoped,
 );
 
-export const workingTreeFiles = Effect.fn("workingTreeFiles")(function* (root: string) {
+// Effect.filter with concurrency keeps the order its checks finish in, not the order it was given.
+export const existingFiles = Effect.fn("existingFiles")(function* (root: string, files: readonly string[]) {
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
+  const exists = yield* Effect.forEach(files, (file) => fs.exists(path.join(root, file)), { concurrency: "unbounded" });
+  return files.filter((_, index) => exists[index]);
+});
+
+export const workingTreeFiles = Effect.fn("workingTreeFiles")(function* (root: string) {
   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",
-  });
+  return yield* existingFiles(root, listed.split("\0").filter(Boolean));
 });
 
 export const git = Effect.fn("git")(function* (args: readonly string[], cwd?: string, feed?: Feed) {

package/src/delivery/setup.ts

@@ -130,11 +130,12 @@ const setupFile = Effect.fn("setupFile")(function* (root: string, relative: stri
   const full = path.join(root, relative);
   if (yield* system.exists(full)) {
     yield* Console.log(NAME + ": kept " + relative + ", already there");
-    return;
+    return false;
   }
   yield* system.makeDirectory(path.dirname(full), { recursive: true });
   yield* system.writeFileString(full, content);
   yield* Console.log(NAME + ": wrote " + relative);
+  return true;
 });
 
 const setupIgnore = Effect.fn("setupIgnore")(function* (root: string) {
@@ -352,10 +353,15 @@ const check = Effect.gen(function* () {
   for (const kind of Object.keys(TEMPLATES)) {
     yield* setupFile(root, "templates/" + kind + ".md", yield* kitText("dist/templates/" + kind + ".md"));
   }
+  const wroteAgents = yield* setupFile(root, "AGENTS.md", yield* kitText("dist/templates/agents.md"));
+  yield* setupFile(root, "CLAUDE.md", yield* kitText("dist/templates/claude.md"));
   if (isPrivate) yield* Console.log(NAME + ": set the CI_RUNS_ON variable to a self-hosted runner label so the new jobs land there");
   if (!outcome.hasOwner) {
     yield* Console.log(NAME + ": declare the repository owners in package.json author or contributors before the first commit");
   }
+  if (wroteAgents) {
+    yield* Console.log(NAME + ": fill AGENTS.md with what an agent cannot infer from the code before the first commit");
+  }
   return true;
 });
 

package/src/testing/changed-tests.ts

@@ -0,0 +1,38 @@
+import { Effect, Schema } from "effect";
+import { changedPaths, defaultBranch, existingFiles, git, rangeEnds, type Change } from "../core/git.ts";
+
+const E2E_PREFIX = "tests/e2e/";
+const TEST_SUFFIXES = [".test.ts", ".test.tsx"] as const;
+
+class BaseUnresolved extends Schema.TaggedError<BaseUnresolved>()("BaseUnresolved", {
+  message: Schema.String,
+}) {}
+
+export function keptPaths(changes: readonly Change[]): readonly string[] {
+  return changes.filter((change) => change.kind !== "deleted").map((change) => change.path);
+}
+
+export function touchedE2eFiles(paths: readonly string[]): readonly string[] {
+  const picked = new Set<string>();
+  for (const path of paths) {
+    if (!path.startsWith(E2E_PREFIX)) continue;
+    if (!TEST_SUFFIXES.some((suffix) => path.endsWith(suffix))) continue;
+    picked.add(path);
+  }
+  return [...picked].sort();
+}
+
+const splitZero = (output: string): readonly string[] => output.split("\0").filter((line) => line !== "");
+
+export const changedE2eFiles = Effect.fn("changedE2eFiles")(function* (root: string) {
+  const target = "origin/" + (yield* defaultBranch(root));
+  const range = yield* rangeEnds(target, "HEAD", root).pipe(
+    Effect.mapError((cause) => new BaseUnresolved({
+      message: "cannot find where HEAD branched from " + target + ", so the e2e files the change touches are unknown; fetch " + target + " and run again: " + cause.message,
+    })),
+  );
+  const committed = keptPaths(yield* changedPaths(range.base, range.head, [], root));
+  const working = splitZero(yield* git(["diff", "--name-only", "-z", "HEAD", "--"], root));
+  const untracked = splitZero(yield* git(["ls-files", "--others", "--exclude-standard", "-z"], root));
+  return yield* existingFiles(root, touchedE2eFiles([...committed, ...working, ...untracked]));
+});

package/src/testing/test-skips.ts

@@ -201,8 +201,12 @@ export function smokeFiles(scanned: readonly string[], smoke: readonly string[])
       message: "checks.smoke cannot name a quarantined, live or pixel test at " + ignored.join(", "),
     };
   }
-  const wanted = new Set(smoke);
-  return { kind: "valid", files: scanned.filter((file) => selectedTierFile(file, "unit") || wanted.has(file)) };
+  return { kind: "valid", files: unitTierPlus(scanned, smoke) };
+}
+
+export function unitTierPlus(scanned: readonly string[], extra: readonly string[]): readonly string[] {
+  const wanted = new Set(extra);
+  return scanned.filter((file) => selectedTierFile(file, "unit") || wanted.has(file));
 }
 
 export const readSmokeDeclarations = Effect.fn("readSmokeDeclarations")(function* (

package/src/testing/test.ts

@@ -5,12 +5,14 @@ import { ChildProcess, ChildProcessSpawner } from "effect/process";
 import { TEST_ENTRY_POINT } from "../core/gates.ts";
 import { runMain, Usage } from "../core/main.ts";
 import { readPullRequestNarrowing } from "./affected-tests.ts";
+import { changedE2eFiles } from "./changed-tests.ts";
 import {
   readDeclarationsIn,
   readSkipDeclarations,
   readSmokeDeclarations,
   scanTestFiles,
   selectedTierFile,
+  unitTierPlus,
   type Environment,
   type SkipDeclaration,
   type TestTier,
@@ -38,8 +40,9 @@ export type TestOptions = {
 };
 
 const NAME = TEST_ENTRY_POINT.bin;
-const USAGE = `usage: ${NAME} [--tier=live | --tier=pixel | --tier=unit | --tier=e2e] [--parallel=<workers>] [--full] [--junit=<file>], and it refuses test filters`;
+const USAGE = `usage: ${NAME} [--tier=live | --tier=pixel | --tier=unit | --tier=e2e | --full | --changed] [--parallel=<workers>] [--junit=<file>], and it refuses test filters`;
 const FULL = "--full";
+const CHANGED = "--changed";
 const TIERS = new Map<string, TestTier>([
   ["--tier=live", "live"],
   ["--tier=pixel", "pixel"],
@@ -68,14 +71,20 @@ export function testOptions(args: readonly string[]): TestOptions | undefined {
   return options;
 }
 
-export type EntryOptions = { readonly options: TestOptions; readonly junit: Option.Option<string> };
+export type EntryOptions = {
+  readonly options: TestOptions;
+  readonly junit: Option.Option<string>;
+  readonly changed: boolean;
+};
 
 // Kept out of testOptions, so checks-test-layout still holds a package.json test script to --parallel alone.
 export function entryOptions(args: readonly string[]): EntryOptions | undefined {
   const junit = args.flatMap((arg) => JUNIT.exec(arg)?.[1] ?? []);
-  const options = testOptions(args.filter((arg) => !JUNIT.test(arg)));
-  if (options === undefined || junit.length > 1) return undefined;
-  return { options, junit: Option.fromNullishOr(junit[0]) };
+  const changed = args.filter((arg) => arg === CHANGED).length;
+  const options = testOptions(args.filter((arg) => !JUNIT.test(arg) && arg !== CHANGED));
+  if (options === undefined || junit.length > 1 || changed > 1) return undefined;
+  if (changed === 1 && (options.tier !== undefined || options.full === true)) return undefined;
+  return { options, junit: Option.fromNullishOr(junit[0]), changed: changed === 1 };
 }
 
 const TEST_SCRIPTS: readonly string[] = [NAME, `bun src/${TEST_ENTRY_POINT.script}`];
@@ -176,7 +185,8 @@ export type SuiteSelection =
   | { readonly kind: "full" }
   | { readonly kind: "tier"; readonly tier: TestTier }
   | { readonly kind: "smoke" }
-  | { readonly kind: "files"; readonly files: readonly string[] };
+  | { readonly kind: "files"; readonly files: readonly string[] }
+  | { readonly kind: "changed"; readonly e2e: readonly string[] };
 
 export function selectSuite(options: TestOptions, environment: Environment): SuiteSelection {
   if (options.tier !== undefined) return { kind: "tier", tier: options.tier };
@@ -195,6 +205,7 @@ export function smokeList(manifest: unknown): readonly string[] | undefined {
 
 export function suiteArgs(selection: SuiteSelection, smoke: readonly string[]): readonly string[] {
   if (selection.kind === "tier") return tierArgs(selection.tier);
+  if (selection.kind === "changed") return suiteArgs({ kind: "smoke" }, selection.e2e);
   if (selection.kind === "smoke") return ["./tests/unit", ...smoke.map((file) => `./${file}`)];
   if (selection.kind === "files") return selection.files.map((file) => `./${file}`);
   return [];
@@ -248,6 +259,10 @@ const narrowSelection = Effect.fn("narrowSelection")(function* (options: TestOpt
 
 const readScope = Effect.fn("readScope")(function* (selection: SuiteSelection, smoke: readonly string[]) {
   if (selection.kind === "smoke") return yield* readSmokeDeclarations(process.cwd(), smoke);
+  if (selection.kind === "changed") {
+    const files = unitTierPlus(yield* scanTestFiles(process.cwd()), selection.e2e);
+    return { files, declarations: yield* readDeclarationsIn(process.cwd(), files) };
+  }
   const declarations =
     selection.kind === "files"
       ? yield* readDeclarationsIn(process.cwd(), selection.files)
@@ -255,6 +270,16 @@ const readScope = Effect.fn("readScope")(function* (selection: SuiteSelection, s
   return { files: undefined, declarations };
 });
 
+const changedSelection = Effect.fn("changedSelection")(function* () {
+  const e2e = yield* changedE2eFiles(process.cwd());
+  yield* Console.log(
+    e2e.length === 0
+      ? `${NAME}: the change touches no e2e test files, so only the unit tier runs`
+      : `${NAME}: the change touches ${e2e.length} e2e test file(s): ${e2e.join(" ")}`,
+  );
+  return { kind: "changed", e2e } satisfies SuiteSelection;
+});
+
 const runSuite = Effect.fn("runSuite")(function* (outfile: string, args: readonly string[], workers: number | undefined) {
   const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
   const command = ["test", "--randomize", `--parallel=${workerCount(workers)}`, ...args, ...reporterArgs(outfile)];
@@ -272,17 +297,23 @@ const runSuite = Effect.fn("runSuite")(function* (outfile: string, args: readonl
 const testEntry = Effect.gen(function* () {
   const entry = entryOptions(process.argv.slice(2));
   if (entry === undefined) return yield* new Usage({ message: USAGE });
-  const { options, junit } = entry;
+  const { options, junit, changed } = entry;
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
   const environment = yield* environmentOf;
-  const selection = yield* narrowSelection(options, selectSuite(options, environment), environment);
+  const selection = changed
+    ? yield* changedSelection()
+    : yield* narrowSelection(options, selectSuite(options, environment), environment);
   if (selection.kind === "files" && selection.files.length === 0) {
     yield* Console.log(`${NAME}: the pull request changes no file a test reads, so no test ran`);
     return true;
   }
   const smoke = selection.kind === "smoke" ? yield* readSmokeList(process.cwd()) : [];
   const scope = yield* readScope(selection, smoke);
+  if (scope.files?.length === 0 && selection.kind === "changed") {
+    yield* Console.log(`${NAME}: no unit test and no e2e test the change touches, so no test ran`);
+    return true;
+  }
   if (scope.files?.length === 0) {
     yield* Console.log(`${NAME}: no unit test and no smoke list, so this local run ran nothing; declare checks.smoke or pass ${FULL}`);
     return true;