@avi2dg/checks 0.72.0 → 0.73.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 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.

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-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.72.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/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;