@avi2dg/checks 0.72.0 → 0.74.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.74.0
+
+Released 2026-11-07.
+
+### Features
+
+- **quality:** refuse folder-level import cycles in the dependency-cruiser preset [#69](https://github.com/avi2d/checks/pull/69)
+
+## 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/dependency-cruiser.config.js

@@ -9,6 +9,16 @@ export default {
         "circular": true
       }
     },
+    {
+      "name": "no-folder-cycle",
+      "severity": "error",
+      "comment": "Folders reach each other in a cycle, so none stands without the others. Move the module that reaches back into the folder it imports, or move what the folders need into a third folder they all import.",
+      "scope": "folder",
+      "from": {},
+      "to": {
+        "circular": true
+      }
+    },
     {
       "name": "no-orphans",
       "severity": "error",

package/dist/presets/dependency-cruiser.js

@@ -13,6 +13,14 @@ var BASE = {
       from: {},
       to: { circular: true }
     },
+    {
+      name: "no-folder-cycle",
+      severity: "error",
+      comment: "Folders reach each other in a cycle, so none stands without the others. Move the module that reaches back into the folder it imports, or move what the folders need into a third folder they all import.",
+      scope: "folder",
+      from: {},
+      to: { circular: true }
+    },
     {
       name: "no-orphans",
       severity: "error",

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/configs/dependency-rules.md

@@ -11,6 +11,7 @@ The kit's dependency-cruiser rules hold a repository's imports, and a repository
 `defineConfig` from `@avi2dg/checks/dependency-cruiser` returns these rules, with or without a config of the repository's own:
 
 - `no-circular`
+- `no-folder-cycle`, which refuses folders that reach each other in a cycle even when no module cycle joins them
 - `no-orphans`, which a repository that depends on `astro` gets only by listing its own, as [checks-graphwalk](../gates/checks-graphwalk.md) explains
 - `not-to-dev-dep`, which refuses shipped source importing a dev-only package, and a package listed in `peerDependencies` too is not dev-only
 - `no-non-package-json`, which refuses an import of an installed package that the nearest `package.json` does not declare, and counts a peer that `peerDependenciesMeta` marks optional as declared
@@ -18,6 +19,8 @@ The kit's dependency-cruiser rules hold a repository's imports, and a repository
 - `no-deep-imports`, which refuses a subpath the package's exports map does not publish
 
 A test file, a config file and every path under `tests/` may import a dev-only package.
+Shipped source may import a dev-only package with `import type` or an inline `type` specifier, since swc tags that import type-only without a TypeScript compiler.
+Both cycle rules count a type-only import as an edge.
 
 The rules parse with swc, so the cruise needs `@swc/core` installed, and without it the cruise silently skips every `.ts` file.
 

package/docs/design.md

@@ -78,6 +78,7 @@ So the fragment lists the rules in `files`, and in `include` beside every file u
 
 The source sits under `src/<vector>/`, one directory for each thing the kit judges a repository on: complexity, quality, testing, docs, delivery and dependencies.
 `src/core/` holds what every vector runs on.
+An area imports `src/core/` and only the other areas listed for it in `AREA_IMPORTS` in the repository's `dependency-cruiser.config.ts`, so code two areas share moves into `src/core/` rather than one area importing the other back.
 `scripts/` holds only the kit's own build and CI tooling, and nothing in it ships.
 Sorting files by what loads them would put both oxlint plugins at the root and every bin in one flat directory.
 Nothing would then say which gate a helper serves.
@@ -96,15 +97,18 @@ A path read without the resolver, such as `node_modules/@avi2dg/checks/scripts/t
 
 ## The package ships built plugins and runnable bins
 
-`files` in `package.json` lists what an install gets.
-`tests/`, `AGENTS.md` and the TypeScript source of the oxlint plugins never reach an install.
+`files` in `package.json` lists what an install gets, and `tests/` and `AGENTS.md` never reach an install.
+It ships `docs/`, `src/` and `dist/`, so a new bin or page ships with no edit to `files`.
+Its `!` entries keep out the decision records under `docs/adr/` and the sources only the build reads.
+A source a shipped bin imports ships even when the build also compiles it.
 npm adds `package.json`, `README.md` and `LICENSE` whatever `files` says.
 `bun pm pack` builds the same tarball the registry serves, and the consumer e2e test installs that tarball.
 
 Each oxlint plugin and each config builder ships compiled under `dist/`, because Node refuses to strip types from a `.ts` file under `node_modules`.
 Stryker loads its config under Node too, so the guard plugin and run-scope helpers the Stryker preset imports ship compiled under `dist/mutation/`.
 oxlint loads `oxlint.config.ts` under Node, so the builders ship as JavaScript beside a `.d.ts` that `tsc` reads.
-`@oxlint/plugins` ships no RuleTester, so each `effect-channel`, `readability` and `data-shape` rule is proven red and green against an installed consumer in `tests/e2e/consumer.test.ts`, except `readability/thin-astro`, which `tests/e2e/astro-consumer.test.ts` proves against a consumer tree linked to the checkout.
+`@oxlint/plugins` ships no RuleTester, so each `effect-channel`, `readability` and `data-shape` rule is proven red and green against an installed consumer in `tests/e2e/package/consumer.test.ts`, except `readability/thin-astro`.
+`readability/thin-astro` is proven against a consumer tree linked to the checkout in `tests/e2e/complexity/astro-consumer.test.ts`.
 `dist/` is committed, with the doc templates in `dist/templates/`, and so is `CHANGELOG.md`, which the same build writes.
 No `prepack` or `prepublishOnly` script rebuilds them, so a publish ships the committed files.
 CI runs `git diff --exit-code` over the whole tree after `bun run build`.

package/docs/gates/checks-graphwalk.md

@@ -17,7 +17,7 @@ A configuration that turns the files rule off still has its files judged.
 It holds each reported symbol against `exports-baseline.json`, and fails on any symbol the baseline does not hold.
 It fails on any baseline entry the range adds unless Knip reports that same symbol unused at the base, so the baseline records debt that already existed and never debt the range creates.
 It fails on any baseline entry Knip no longer reports, so the baseline only shrinks.
-It runs dependency-cruiser over every tracked `.ts`, `.tsx`, `.mts` and `.cts` file and names each violation with its rule, the importing module and the module it reaches.
+It runs dependency-cruiser over every tracked `.ts`, `.tsx`, `.mts` and `.cts` file and names each violation with its rule, the importing module or folder and the module or folder it reaches.
 It fails on a violation whose rule has `error` severity, and lists a `warn` or `info` violation without failing.
 It fails when the repository tracks no `.ts`, `.tsx`, `.astro`, `.mts` or `.cts` file, since an empty scan would pass without judging anything.
 It fails when the repository holds no Knip configuration, since Knip's default entries cannot tell a dead file from an entry point.

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.74.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "author": {
     "name": "avi2d",
@@ -17,126 +17,26 @@
   "type": "module",
   "files": [
     "CHANGELOG.md",
-    "docs/bins.md",
-    "docs/configs/",
-    "docs/design.md",
-    "docs/gates/",
-    "docs/how-to/",
-    "docs/shipped-files.md",
+    "docs/",
+    "!docs/adr/",
     "bunfig.toml",
     ".bun-version",
     "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/core/scope.ts",
-    "src/delivery/changelog.ts",
-    "src/delivery/changelog-write.ts",
-    "src/delivery/release-notes.ts",
-    "src/delivery/release-report.ts",
-    "src/delivery/release.ts",
-    "src/delivery/release-commit.ts",
-    "src/delivery/release-pr.ts",
-    "src/delivery/release-preflight.ts",
-    "src/delivery/release-schedule.ts",
-    "src/delivery/schedule-policy.ts",
-    "src/delivery/release-publish.ts",
-    "src/delivery/release-push.ts",
-    "src/delivery/release-tag.ts",
-    "src/delivery/release-tagging.ts",
-    "src/delivery/github.ts",
-    "src/testing/test-layout.ts",
-    "src/testing/block-screens.ts",
-    "src/testing/test.ts",
-    "src/testing/test-skips.ts",
-    "src/testing/affected-tests.ts",
-    "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-refusal.ts",
-    "src/testing/mutation-compare.ts",
-    "src/testing/mutation-scope.ts",
-    "src/testing/mutation-scope-graph.ts",
-    "src/testing/mutation-baseline.ts",
-    "src/testing/mutation-baseline-full.ts",
-    "src/testing/mutation-baseline-saved.ts",
-    "src/testing/subsumed-tests.ts",
-    "src/testing/whole-tree-run.ts",
-    "src/testing/whole-tree-run-findings.ts",
-    "src/delivery/ci-wiring.ts",
-    "src/delivery/shell-command.ts",
-    "src/delivery/workflow-references.ts",
-    "src/delivery/bun-pin.ts",
-    "src/delivery/mutation-job.ts",
-    "src/delivery/job-timeout.ts",
-    "src/delivery/runner-policy.ts",
-    "src/delivery/runner-pick.ts",
-    "src/delivery/secrets.ts",
-    "src/delivery/secrets-pack.ts",
-    "src/delivery/pr-text.ts",
-    "src/delivery/setup.ts",
-    "src/delivery/setup-workflow.ts",
-    "src/delivery/gitleaks.ts",
-    "src/delivery/gitleaks.toml",
-    "src/quality/comment-matchers.ts",
-    "src/docs/prose-matchers.ts",
-    "src/quality/comments.ts",
-    "src/quality/comment-gate.ts",
-    "src/quality/css-size.ts",
-    "src/quality/frontend-syntax.ts",
-    "src/quality/browser/",
-    "src/complexity/suppressions-ratchet.ts",
-    "src/complexity/repetition.ts",
-    "src/complexity/graphwalk.ts",
-    "src/complexity/knip.ts",
-    "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",
-    "src/dependencies/advisories.ts",
-    "src/dependencies/advisory-rules.ts",
-    "src/dependencies/osv-scanner.ts",
-    "src/dependencies/pinned-binary.ts",
-    "src/docs/doc-agents.ts",
-    "src/docs/doc-outline.ts",
-    "src/docs/doc-rules.ts",
-    "src/docs/doc-references.ts",
-    "src/docs/doc-snapshot.ts",
-    "src/docs/doc-templates.ts",
-    "src/docs/doc-names.ts",
-    "src/docs/doc-versions.ts",
-    "dist/templates/",
-    "src/quality/presets/effect.language-service.json",
-    "src/quality/presets/oxlint.ts",
-    "src/quality/presets/dependency-cruiser.ts",
-    "src/quality/presets/stylelint.ts",
-    "src/quality/effect-scope.ts",
-    "src/quality/jsonc-patch.ts",
-    "src/dependencies/kit-defaults.ts",
+    "src/",
+    "!src/complexity/readability/",
+    "!src/quality/data-shape/",
+    "!src/quality/effect-channel/",
+    "!src/quality/presets/knip.ts",
+    "!src/quality/presets/postcss-value-parser.d.ts",
+    "!src/testing/mutation-guard-plugin.ts",
+    "!src/testing/unit-test-order.ts",
+    "dist/",
     "oxlintrc.json",
     "stryker.preset.js",
     "tsconfig.effect.json",
-    "ts-reset.d.ts",
-    "dist/effect-channel/index.js",
-    "dist/readability/index.js",
-    "dist/data-shape/index.js",
-    "dist/mutation/",
-    "dist/presets/"
+    "ts-reset.d.ts"
   ],
   "exports": {
     "./dependency-cruiser.config.js": "./dependency-cruiser.config.js",
@@ -221,7 +121,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 → core}/github.ts

@@ -1,6 +1,6 @@
 import { Effect, Schema } from "effect";
 import { ChildProcessSpawner } from "effect/process";
-import { collect, type Feed } from "../core/git.ts";
+import { collect, type Feed } from "./git.ts";
 
 export class GitHubFailure extends Schema.TaggedError<GitHubFailure>()("GitHubFailure", {
   message: Schema.String,

package/src/core/release-names.ts

@@ -0,0 +1,14 @@
+export const MANIFEST = "package.json";
+
+export const TAG_PREFIX = "v";
+
+export const RELEASE_TAG_GLOB = `${TAG_PREFIX}[0-9]*.[0-9]*.[0-9]*`;
+
+export function releaseTag(version: string): string {
+  return `${TAG_PREFIX}${version}`;
+}
+
+// The tag starts with TAG_PREFIX.
+export function taggedVersion(tag: string): string {
+  return tag.slice(TAG_PREFIX.length);
+}

package/src/core/test-script.ts

@@ -0,0 +1,45 @@
+import { TEST_ENTRY_POINT } from "./gates.ts";
+
+export type TestTier = "live" | "pixel" | "unit" | "e2e";
+
+export type TestOptions = {
+  readonly tier?: TestTier;
+  readonly workers?: number;
+  readonly full?: boolean;
+};
+
+export const FULL = "--full";
+const TIERS = new Map<string, TestTier>([
+  ["--tier=live", "live"],
+  ["--tier=pixel", "pixel"],
+  ["--tier=unit", "unit"],
+  ["--tier=e2e", "e2e"],
+]);
+const PARALLEL = /^--parallel=([1-9][0-9]*)$/;
+
+function optionOf(arg: string): TestOptions | undefined {
+  const tier = TIERS.get(arg);
+  if (tier !== undefined) return { tier };
+  if (arg === FULL) return { full: true };
+  const workers = PARALLEL.exec(arg)?.[1];
+  return workers === undefined ? undefined : { workers: Number(workers) };
+}
+
+export function testOptions(args: readonly string[]): TestOptions | undefined {
+  let options: TestOptions = {};
+  for (const arg of args) {
+    const option = optionOf(arg);
+    if (option === undefined || Object.keys(option).some((key) => key in options)) return undefined;
+    options = { ...options, ...option };
+  }
+  if (options.tier !== undefined && options.full === true) return undefined;
+  return options;
+}
+
+const TEST_SCRIPTS: readonly string[] = [TEST_ENTRY_POINT.bin, `bun src/${TEST_ENTRY_POINT.script}`];
+
+export function scriptOptions(script: unknown): TestOptions | undefined {
+  if (typeof script !== "string") return undefined;
+  const entry = TEST_SCRIPTS.find((candidate) => script === candidate || script.startsWith(`${candidate} `));
+  return entry === undefined ? undefined : testOptions(script.slice(entry.length).split(" ").filter((arg) => arg !== ""));
+}

package/src/delivery/changelog-write.ts

@@ -2,13 +2,12 @@
 import { Console, DateTime, Effect, FileSystem, Path, Schema } from "effect";
 import { cuts, hasEntries, namesPullRequest, releaseDates, renderChangelog, type Bump, type Cut, type Release } from "./changelog.ts";
 import { git } from "../core/git.ts";
+import { MANIFEST, TAG_PREFIX, taggedVersion } from "../core/release-names.ts";
 import { runMain } from "../core/main.ts";
 
 const NAME = "checks-changelog";
 const CHANGELOG = "CHANGELOG.md";
-const MANIFEST = "package.json";
 const FIELD = "\x1f";
-const TAG_PREFIX = "v";
 
 class ChangelogUnreadable extends Schema.TaggedError<ChangelogUnreadable>()("ChangelogUnreadable", {
   message: Schema.String,
@@ -75,7 +74,7 @@ const readPublishedShas = Effect.fn("readPublishedShas")(function* (root: string
   const tags = yield* git(["for-each-ref", "--format=%(refname:strip=2)", `refs/tags/${TAG_PREFIX}*`], root);
   const published = new Set<string>();
   for (const tag of tags.split("\n").filter((line) => line.startsWith(TAG_PREFIX))) {
-    const version = tag.slice(TAG_PREFIX.length);
+    const version = taggedVersion(tag);
     for (const bump of bumps.filter((one) => one.version === version).toReversed()) {
       if (yield* reaches(root, bump.sha, `refs/tags/${tag}`)) {
         published.add(bump.sha);

package/src/delivery/pr-text.ts

@@ -3,7 +3,7 @@ import { Console, Effect, FileSystem, Path, Schema } from "effect";
 import { runMain, Usage } from "../core/main.ts";
 import { cacheRoot } from "../dependencies/cache-root.ts";
 import { pinnedGitleaks, scanDirectory, type Leak } from "./gitleaks.ts";
-import { gh, gitHubJson, GitHubFailure, REPOSITORY } from "./github.ts";
+import { gh, gitHubJson, GitHubFailure, REPOSITORY } from "../core/github.ts";
 import { scanConfig } from "./secrets-pack.ts";
 
 const NAME = "pr-text";

package/src/delivery/release-commit.ts

@@ -1,8 +1,9 @@
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
 import * as Base64 from "effect/encoding/Base64";
-import { gitHubJson, REPOSITORY } from "./github.ts";
+import { gitHubJson, REPOSITORY } from "../core/github.ts";
 import { nextVersion, type Pending, readPending, releaseTitle, runBuild, withVersion } from "./release.ts";
 import { git } from "../core/git.ts";
+import { MANIFEST, releaseTag, taggedVersion } from "../core/release-names.ts";
 
 export class ReleaseRefused extends Schema.TaggedError<ReleaseRefused>()("ReleaseRefused", {
   message: Schema.String,
@@ -21,7 +22,6 @@ type Built = {
   readonly files: readonly Read[];
 };
 
-export const MANIFEST = "package.json";
 const REGULAR_FILE_MODES = new Set(["100644", "100755"]);
 const RAW_ENTRY = /^:(\d{6}) (\d{6}) [0-9a-f]+ [0-9a-f]+ ([A-Z])/;
 
@@ -56,9 +56,9 @@ export const versionIn = (manifest: string): Effect.Effect<string | undefined> =
 
 const releaseVersion = Effect.fn("releaseVersion")(function* (manifest: string, { since, unreleased }: Pending, untagged: string) {
   const { version } = yield* decodeVersion(manifest).pipe(Effect.mapError((cause) => refused(`${MANIFEST}: ${cause.message}`)));
-  if (since !== undefined && since !== `v${version}`) {
+  if (since !== undefined && since !== releaseTag(version)) {
     return yield* refused(
-      `${MANIFEST} holds ${version}, but the last release tag is ${since}, so v${version} is untagged; ${untagged}, or return its version to ${since.slice(1)}`,
+      `${MANIFEST} holds ${version}, but the last release tag is ${since}, so ${releaseTag(version)} is untagged; ${untagged}, or return its version to ${taggedVersion(since)}`,
     );
   }
   const next = nextVersion(version, unreleased);

package/src/delivery/release-pr.ts

@@ -1,9 +1,10 @@
 #!/usr/bin/env bun
 import { Console, Effect, Schema } from "effect";
-import { dispatch, gitHubJson, REPOSITORY } from "./github.ts";
+import { dispatch, gitHubJson, REPOSITORY } from "../core/github.ts";
 import { releaseTitle, runningWorkflow } from "./release.ts";
-import { buildRelease, commitRelease, hasBranch, MANIFEST, planRelease, pointBranch, versionIn } from "./release-commit.ts";
+import { buildRelease, commitRelease, hasBranch, planRelease, pointBranch, versionIn } from "./release-commit.ts";
 import { git } from "../core/git.ts";
+import { MANIFEST } from "../core/release-names.ts";
 import { runMain, Usage } from "../core/main.ts";
 
 type Remote = {

package/src/delivery/release-preflight.ts

@@ -4,11 +4,11 @@ import { lastTag } from "./release.ts";
 import { refused } from "./release-commit.ts";
 import { fromProgram, shellWords, type Command } from "./shell-command.ts";
 import { git } from "../core/git.ts";
+import { MANIFEST, releaseTag, taggedVersion } from "../core/release-names.ts";
 import { runMain, Usage } from "../core/main.ts";
 
 const LABEL = "release-preflight";
 const USAGE = "usage: release-preflight.ts <release-workflow>";
-const MANIFEST = "package.json";
 const WORKFLOWS = ".github/workflows";
 
 const Manifest = Schema.Struct({
@@ -114,9 +114,9 @@ const checkTag = Effect.fn("checkTag")(function* (root: string) {
   }
   const { version } = yield* readManifest(root);
   const since = yield* lastTag(root);
-  if (since !== undefined && since !== `v${version}`) {
+  if (since !== undefined && since !== releaseTag(version)) {
     return yield* refused(
-      `${MANIFEST} holds ${version}, but the last release tag is ${since}, so v${version} is untagged; rerun the release that bumped it, whose refusal says what to fix, or return ${MANIFEST} to ${since.slice(1)}`,
+      `${MANIFEST} holds ${version}, but the last release tag is ${since}, so ${releaseTag(version)} is untagged; rerun the release that bumped it, whose refusal says what to fix, or return ${MANIFEST} to ${taggedVersion(since)}`,
     );
   }
   yield* Console.log(`${LABEL}: ${MANIFEST} holds ${version}, which ${since === undefined ? "has no release tag yet" : `matches ${since}`}`);

package/src/delivery/release-publish.ts

@@ -2,12 +2,12 @@
 import { Console, Effect, FileSystem, Option, Schema } from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/process";
 import { collect } from "../core/git.ts";
+import { MANIFEST } from "../core/release-names.ts";
 import { runMain, Usage } from "../core/main.ts";
 
 const NAME = "checks-release-publish";
 const LABEL = "release-publish";
 const USAGE = "usage: release-publish.ts";
-const MANIFEST = "package.json";
 
 class PublishFailed extends Schema.TaggedError<PublishFailed>()("PublishFailed", {
   message: Schema.String,

package/src/delivery/release-push.ts

@@ -1,10 +1,11 @@
 #!/usr/bin/env bun
 import { Console, Duration, Effect, Schema } from "effect";
-import { dispatch, gitHubJson, REPOSITORY } from "./github.ts";
+import { dispatch, gitHubJson, REPOSITORY } from "../core/github.ts";
 import { releasedVersionOf } from "./release.ts";
 import { buildRelease, commitRelease, decodeRef, hasBranch, planRelease, pointBranch, refused } from "./release-commit.ts";
 import { pushTag, tagHead, taggedOn } from "./release-tagging.ts";
 import { git } from "../core/git.ts";
+import { releaseTag } from "../core/release-names.ts";
 import { runMain, Usage } from "../core/main.ts";
 
 const NAME = "checks-release-push";
@@ -124,7 +125,7 @@ const releasePush = Effect.gen(function* () {
   const plan = yield* planRelease(LABEL, root, UNTAGGED);
   if (plan === undefined) return true;
   const { base, branch, head, next, bumped } = plan;
-  const tag = `v${next}`;
+  const tag = releaseTag(next);
   const taken = yield* taggedOn(root, tag);
   if (taken !== undefined) return yield* refused(`${tag} already tags ${taken.slice(0, 12)}, so ${next} cannot be released again`);
   const release = yield* commitRelease(root, head, yield* buildRelease(NAME, root, bumped), next);

package/src/delivery/release-schedule.ts

@@ -23,7 +23,7 @@ const PUBLISH_BINS = ["checks-release-publish", "release-publish.ts"];
 const NUMBER = /^\d+$/;
 const BY_HAND = "drop the schedule, so a release runs only when someone starts it";
 
-function isBinIn(bins: readonly string[], word: string): boolean {
+export function isBinIn(bins: readonly string[], word: string): boolean {
   return bins.some((name) => word === name || word.endsWith(`/${name}`));
 }
 
@@ -57,7 +57,7 @@ function workflowRuns(
   });
 }
 
-function crons(document: unknown): readonly unknown[] {
+export function crons(document: unknown): readonly unknown[] {
   const on = isRecord(document) ? document["on"] : undefined;
   const schedule = isRecord(on) ? on["schedule"] : undefined;
   return Array.isArray(schedule) ? schedule.map((entry) => (isRecord(entry) ? entry["cron"] : undefined)) : [];

package/src/delivery/release-tagging.ts

@@ -1,14 +1,14 @@
 import { Console, Effect, FileSystem, Path, Schema } from "effect";
-import { dispatch, GitHubFailure } from "./github.ts";
+import { dispatch, GitHubFailure } from "../core/github.ts";
 import { ChildProcessSpawner } from "effect/process";
 import { lastTag, releasedVersionOf, runBuild } from "./release.ts";
 import { git } from "../core/git.ts";
+import { MANIFEST, releaseTag, taggedVersion } from "../core/release-names.ts";
 
 class TagRefused extends Schema.TaggedError<TagRefused>()("TagRefused", {
   message: Schema.String,
 }) {}
 
-const MANIFEST = "package.json";
 
 const decodeVersion = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Struct({ version: Schema.String })));
 
@@ -48,7 +48,7 @@ export const tagHead = Effect.fn("tagHead")(function* (
   const manifest = yield* (yield* FileSystem.FileSystem).readFileString((yield* Path.Path).join(root, MANIFEST));
   const { version: held } = yield* decodeVersion(manifest).pipe(Effect.mapError((cause) => new TagRefused({ message: `${MANIFEST}: ${cause.message}` })));
   if (held !== version) return yield* new TagRefused({ message: `${head.slice(0, 12)} releases ${version}, but ${MANIFEST} holds ${held}` });
-  const tag = `v${version}`;
+  const tag = releaseTag(version);
   const tagged = yield* taggedOn(root, tag);
   if (tagged === head) {
     yield* Console.log(`${label}: ${tag} already tags ${head.slice(0, 12)}`);
@@ -59,7 +59,7 @@ export const tagHead = Effect.fn("tagHead")(function* (
   const rebuilt = (yield* git(["diff", "--name-only"], root)).trim().split("\n").filter((file) => file !== "");
   if (rebuilt.length > 0) {
     const since = yield* lastTag(root);
-    const returned = since === undefined ? "the version it held before this release" : since.slice(1);
+    const returned = since === undefined ? "the version it held before this release" : taggedVersion(since);
     return yield* new TagRefused({
       message: `the build rewrites ${rebuilt.join(", ")} at ${head.slice(0, 12)}, which the release workflow's build check refuses; open a \`chore: cancel the unpublished ${version}\` pull request that returns ${MANIFEST} to ${returned} and commits what \`bun run build\` then writes to CHANGELOG.md, and the next ${cuttingWorkflow} run cuts the release again with every change since ${since ?? "the first commit"}`,
     });

package/src/delivery/release.ts

@@ -2,6 +2,7 @@ import { Config, Effect, Schema } from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/process";
 import { groupOf } from "./changelog.ts";
 import { git } from "../core/git.ts";
+import { RELEASE_TAG_GLOB } from "../core/release-names.ts";
 
 class ReleaseUnreadable extends Schema.TaggedError<ReleaseUnreadable>()("ReleaseUnreadable", {
   message: Schema.String,
@@ -16,7 +17,6 @@ export type Pending = {
   readonly unreleased: readonly string[];
 };
 
-const RELEASE_TAG = "v[0-9]*.[0-9]*.[0-9]*";
 const PLAIN_VERSION = /^(\d+)\.(\d+)\.(\d+)$/;
 const RELEASE_SUBJECT = /^chore: release (\d+\.\d+\.\d+)(?: \(#\d+\))?$/;
 
@@ -59,7 +59,7 @@ export const runBuild = Effect.fn("runBuild")(function* (root: string) {
 });
 
 export const lastTag = Effect.fn("lastTag")(function* (root: string) {
-  const described = yield* git(["describe", "--tags", "--abbrev=0", `--match=${RELEASE_TAG}`, "HEAD"], root).pipe(
+  const described = yield* git(["describe", "--tags", "--abbrev=0", `--match=${RELEASE_TAG_GLOB}`, "HEAD"], root).pipe(
     Effect.map((tag) => tag.trim()),
     Effect.catchTag("GitFailure", () => Effect.succeed("")),
   );

package/src/delivery/schedule-policy.ts

@@ -1,8 +1,8 @@
 import { runsBin } from "./mutation-job.ts";
-import { releasesOnSchedule, schedules } from "./release-schedule.ts";
+import { crons, isBinIn, releasesOnSchedule, schedules } from "./release-schedule.ts";
 import { jobRuns } from "./runner-policy.ts";
 import { invokes, plainCommand, type Command } from "./shell-command.ts";
-import { isRecord, locate, workflowJobs, type Workflow } from "./workflow-references.ts";
+import { locate, workflowJobs, type Workflow } from "./workflow-references.ts";
 import type { ScheduleContext, ScheduleOwner } from "./release-schedule.ts";
 
 export type ScheduledRun = {
@@ -17,13 +17,7 @@ const WEEKDAY = /^(?:[0-7]|sun|mon|tue|wed|thu|fri|sat)$/i;
 const BY_HAND = "drop the schedule, so it runs only when someone starts it with gh workflow run";
 
 function isAdvisoryBin([head = ""]: Command): boolean {
-  return ADVISORY_BINS.some((name) => head === name || head.endsWith(`/${name}`));
-}
-
-function crons(document: unknown): readonly unknown[] {
-  const on = isRecord(document) ? document["on"] : undefined;
-  const schedule = isRecord(on) ? on["schedule"] : undefined;
-  return Array.isArray(schedule) ? schedule.map((entry) => (isRecord(entry) ? entry["cron"] : undefined)) : [];
+  return isBinIn(ADVISORY_BINS, head);
 }
 
 // Once a week is one minute, one hour and one weekday, on any day of any month.

package/src/delivery/setup.ts

@@ -3,7 +3,7 @@ import { Console, Effect, FileSystem, Path, Schema } from "effect";
 import { runMain, Usage } from "../core/main.ts";
 import { ciWorkflow } from "./setup-workflow.ts";
 import { TEMPLATES } from "../docs/doc-templates.ts";
-import { scriptOptions } from "../testing/test.ts";
+import { scriptOptions } from "../core/test-script.ts";
 import { withServiceOverrides, type ServiceOverride } from "../quality/effect-scope.ts";
 import { SOURCES, TESTS } from "../quality/presets/oxlint.ts";
 import severities from "../quality/presets/effect.language-service.json" with { type: "json" };

package/src/docs/doc-agents.ts

@@ -102,9 +102,12 @@ function cellsOf(raw: string): readonly string[] {
 
 const DELIMITER_CELL = /^\s*:?-+:?\s*$/;
 
+function isQuoteOrIndentedCode(raw: string): boolean {
+  return /^\s*>/.test(raw) || /^(?: {4}|\t)/.test(raw);
+}
+
 function isDelimiterRow(raw: string): boolean {
-  if (/^\s*>/.test(raw)) return false;
-  if (/^(?: {4}|\t)/.test(raw)) return false;
+  if (isQuoteOrIndentedCode(raw)) return false;
   const trimmed = raw.trim();
   if (!trimmed.includes("|") || !trimmed.includes("-")) return false;
   const inner = trimmed.replace(/^\|/, "").replace(/\|$/, "");
@@ -125,22 +128,18 @@ function codeLinesIn(scanned: readonly MarkdownLine[]): ReadonlySet<number> {
   return excluded;
 }
 
+function isOutsideCodeAndQuote(line: MarkdownLine, code: ReadonlySet<number>): boolean {
+  return !code.has(line.line) && !isQuoteOrIndentedCode(line.raw);
+}
+
 function isTableCandidate(line: MarkdownLine, code: ReadonlySet<number>): boolean {
-  if (line.kind !== "prose" && line.kind !== "table") return false;
-  if (code.has(line.line)) return false;
-  if (/^\s*>/.test(line.raw)) return false;
-  if (/^(?: {4}|\t)/.test(line.raw)) return false;
-  return true;
+  return (line.kind === "prose" || line.kind === "table") && isOutsideCodeAndQuote(line, code);
 }
 
 type TableRow = { readonly line: number; readonly raw: string; readonly width: number };
 
 function isBodyLine(line: MarkdownLine, code: ReadonlySet<number>): boolean {
-  if (line.raw.trim() === "") return false;
-  if (code.has(line.line)) return false;
-  if (/^\s*>/.test(line.raw)) return false;
-  if (/^(?: {4}|\t)/.test(line.raw)) return false;
-  return true;
+  return line.raw.trim() !== "" && isOutsideCodeAndQuote(line, code);
 }
 
 type HeaderMatch = { readonly header: MarkdownLine; readonly delimiterLine: number; readonly width: number };

package/src/quality/presets/dependency-cruiser.ts

@@ -32,6 +32,15 @@ const BASE = {
       from: {},
       to: { circular: true },
     },
+    {
+      name: "no-folder-cycle",
+      severity: "error",
+      comment:
+        "Folders reach each other in a cycle, so none stands without the others. Move the module that reaches back into the folder it imports, or move what the folders need into a third folder they all import.",
+      scope: "folder",
+      from: {},
+      to: { circular: true },
+    },
     {
       name: "no-orphans",
       severity: "error",

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/flake.ts

@@ -3,7 +3,8 @@ import { Config, Console, Effect, FileSystem, Option, Path, Random, Schema } fro
 import { ChildProcess, ChildProcessSpawner } from "effect/process";
 import { runMain, Usage } from "../core/main.ts";
 import { NAME_SEPARATOR, parseReport, ReportError, reporterArgs, type TestResult } from "./test-report.ts";
-import { scriptOptions, workerCount } from "./test.ts";
+import { scriptOptions } from "../core/test-script.ts";
+import { workerCount } from "./test.ts";
 
 export type Run = {
   readonly seed: number;

package/src/testing/test-layout.ts

@@ -4,7 +4,7 @@ import { workingTreeFiles } from "../core/git.ts";
 import { runMain } from "../core/main.ts";
 import { ENTRY_POINT, TEST_ENTRY_POINT } from "../core/gates.ts";
 import { identifierName, isRecord, lineOf, parseTypeScript, spanStart, stringValue } from "../core/swc.ts";
-import { scriptOptions } from "./test.ts";
+import { scriptOptions } from "../core/test-script.ts";
 
 export type Violation = {
   readonly file: string;

package/src/testing/test-skips.ts

@@ -1,8 +1,9 @@
 import { Effect, FileSystem, Path, Schema } from "effect";
 import { identifierName, isRecord, lineOf, parseTypeScript, spanStart, stringValue } from "../core/swc.ts";
+import type { TestTier } from "../core/test-script.ts";
 
 export type Environment = "ci" | "local";
-export type TestTier = "live" | "pixel" | "unit" | "e2e";
+export type { TestTier };
 export type SkipDeclaration = {
   readonly file: string;
   readonly line: number;
@@ -201,8 +202,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

@@ -4,20 +4,23 @@ import { Config, Console, Effect, FileSystem, Option, Path, Schema } from "effec
 import { ChildProcess, ChildProcessSpawner } from "effect/process";
 import { TEST_ENTRY_POINT } from "../core/gates.ts";
 import { runMain, Usage } from "../core/main.ts";
+import { FULL, testOptions, type TestOptions, type TestTier } from "../core/test-script.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,
 } from "./test-skips.ts";
 import { NAME_SEPARATOR, parseReport, ReportError, reporterArgs, type TestResult } from "./test-report.ts";
 
 export type { Environment, SkipDeclaration } from "./test-skips.ts";
+export { scriptOptions, testOptions, type TestOptions } from "../core/test-script.ts";
 
 export type Verdict = {
   readonly environment: Environment;
@@ -31,59 +34,25 @@ export class SkipGateError extends Schema.TaggedError<SkipGateError>()("SkipGate
   message: Schema.String,
 }) {}
 
-export type TestOptions = {
-  readonly tier?: TestTier;
-  readonly workers?: number;
-  readonly full?: boolean;
-};
-
 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 FULL = "--full";
-const TIERS = new Map<string, TestTier>([
-  ["--tier=live", "live"],
-  ["--tier=pixel", "pixel"],
-  ["--tier=unit", "unit"],
-  ["--tier=e2e", "e2e"],
-]);
-const PARALLEL = /^--parallel=([1-9][0-9]*)$/;
+const USAGE = `usage: ${NAME} [--tier=live | --tier=pixel | --tier=unit | --tier=e2e | --full | --changed] [--parallel=<workers>] [--junit=<file>], and it refuses test filters`;
+const CHANGED = "--changed";
 const JUNIT = /^--junit=(.+)$/;
 
-function optionOf(arg: string): TestOptions | undefined {
-  const tier = TIERS.get(arg);
-  if (tier !== undefined) return { tier };
-  if (arg === FULL) return { full: true };
-  const workers = PARALLEL.exec(arg)?.[1];
-  return workers === undefined ? undefined : { workers: Number(workers) };
-}
-
-export function testOptions(args: readonly string[]): TestOptions | undefined {
-  let options: TestOptions = {};
-  for (const arg of args) {
-    const option = optionOf(arg);
-    if (option === undefined || Object.keys(option).some((key) => key in options)) return undefined;
-    options = { ...options, ...option };
-  }
-  if (options.tier !== undefined && options.full === true) return 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 TEST_SCRIPTS: readonly string[] = [NAME, `bun src/${TEST_ENTRY_POINT.script}`];
-
-export function scriptOptions(script: unknown): TestOptions | undefined {
-  if (typeof script !== "string") return undefined;
-  const entry = TEST_SCRIPTS.find((candidate) => script === candidate || script.startsWith(`${candidate} `));
-  return entry === undefined ? undefined : testOptions(script.slice(entry.length).split(" ").filter((arg) => arg !== ""));
+  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 };
 }
 
 function matches(declaration: SkipDeclaration, result: TestResult): boolean {
@@ -176,7 +145,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 +165,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 +219,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 +230,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 +257,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;

package/src/testing/whole-tree-run.ts

@@ -3,7 +3,7 @@ import { Config, Console, Context, Effect, FileSystem, Layer, Option, Path, Sche
 import { ChildProcessSpawner } from "effect/process";
 import { DEFAULT_BRANCH } from "../core/gates.ts";
 import { runMain, Usage } from "../core/main.ts";
-import { gh, type GitHubFailure, gitHubJson, REPOSITORY } from "../delivery/github.ts";
+import { gh, type GitHubFailure, gitHubJson, REPOSITORY } from "../core/github.ts";
 import { parseReport as parseMutationReport, type ReportFile } from "./mutation-compare.ts";
 import { cleared, type Finding, findingsOf, gatesDecided, gatesOf, keyOf, WholeTreeRecordSchema, noted, type Observed, type WholeTreeRecord, percent, type PreviousRun, scoresOf, type TestReport } from "./whole-tree-run-findings.ts";
 import { parseReport as parseTestReport } from "./test-report.ts";