@avi2dg/checks 0.49.0 → 0.50.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.50.0
+
+Released 2026-10-20.
+
+### Features
+
+- **testing:** cap local checks-test at the unit tier plus a declared smoke list [#191](https://github.com/avi2d/checks/pull/191)
+
 ## 0.49.0
 
 Released 2026-10-20.

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

@@ -27,6 +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.
 - `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,8 @@ audience: consumers
 
 ## What it checks
 
-It runs the default suite with `bun test --randomize --parallel=<workers>`, as [Parallel runs](#parallel-runs) says, and reads Bun's JUnit report from that run.
+It runs the unit tier plus the smoke list outside CI and the full suite under CI.
+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.
 A test that `test.skip`, `test.skipIf`, `test.if`, `test.todo` or an enclosing `describe.skip` skips fails unless the test declares its reason.
@@ -44,10 +45,25 @@ A skipped test or a todo without `skipReason` fails in every environment.
 ## What it reads
 
 `checks-test` reads test source files and the JUnit report written by its own run.
-It does not read a skip list from `package.json`.
+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.
+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.
+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.
 
-The command takes no arguments for the default suite, except the worker count of [Parallel runs](#parallel-runs) and the file `--junit` keeps the report at.
+```json
+{
+  "checks": {
+    "smoke": ["tests/e2e/checkout.test.ts"]
+  }
+}
+```
+
+The default suite takes only the arguments [Arguments](#arguments) lists.
 Use `checks-test --tier=live` or `checks-test --tier=pixel` for a named test tier.
 Use `checks-test --tier=unit` or `checks-test --tier=e2e` to run only one level of the default suite.
 A live or pixel run clears Bun's ignored paths, runs only `./tests/live` or `./tests/pixel`, and still checks each skip.
@@ -103,8 +119,10 @@ 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, and `--junit=<file>`.
-Its named tier options are `--tier=live`, `--tier=pixel`, `--tier=unit` and `--tier=e2e`, and a tier run takes `--parallel=<workers>` too.
+The default command takes no arguments except `--parallel=<workers>`, as [Parallel runs](#parallel-runs) says, `--full` and `--junit=<file>`.
+`--full` runs the full suite outside CI, so a night run 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`.
+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 night run hands it to [checks-night-run](checks-night-run.md).
 A `package.json` script never takes `--junit`, as [checks-test-layout](checks-test-layout.md) says of `scripts.test`.
 Each option appears at most once.
@@ -116,7 +134,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 cannot be read, `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 or Bun wrote no report |
 
 ## Sample output
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.49.0",
+  "version": "0.50.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "license": "MIT",
   "repository": {

package/src/testing/test-layout.ts

@@ -252,7 +252,7 @@ export function scriptViolations(manifest: unknown, files: readonly string[] = [
   const lint = isRecord(scripts) ? scripts["lint"] : undefined;
   const violations: Violation[] = [];
   const options = scriptOptions(test);
-  if (options === undefined || options.tier !== undefined) {
+  if (options === undefined || options.tier !== undefined || options.full === true) {
     violations.push({
       file,
       line: undefined,

package/src/testing/test-skips.ts

@@ -144,21 +144,21 @@ function selectedTierFile(file: string, tier: TestTier | undefined): boolean {
   return file.startsWith(`tests/${tier}/`);
 }
 
-export const readSkipDeclarations = Effect.fn("readSkipDeclarations")(function* (
-  root: string,
-  tier: TestTier | undefined,
-) {
-  const fs = yield* FileSystem.FileSystem;
-  const path = yield* Path.Path;
-  const files = yield* Effect.tryPromise({
+const scanTestFiles = Effect.fn("scanTestFiles")(function* (root: string) {
+  return yield* Effect.tryPromise({
     try: () =>
       Promise.all(
         TEST_FILES.map((pattern) =>
           Array.fromAsync(new Bun.Glob(pattern).scan({ cwd: root, onlyFiles: true })),
         ),
-      ).then((groups) => groups.flat().filter((file) => selectedTierFile(file, tier)).sort()),
-    catch: (cause) => new SkipDeclarationError({ message: `cannot find test files: ${String(cause)}` }),
+      ).then((groups) => groups.flat().sort()),
+    catch: (cause) => new SkipDeclarationError({ message: "cannot find test files: " + String(cause) }),
   });
+});
+
+const readDeclarationsIn = Effect.fn("readDeclarationsIn")(function* (root: string, files: readonly string[]) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
   const declarations: SkipDeclaration[] = [];
   for (const file of files) {
     const source = yield* fs.readFileString(path.join(root, file)).pipe(
@@ -178,3 +178,38 @@ export const readSkipDeclarations = Effect.fn("readSkipDeclarations")(function*
   }
   return declarations;
 });
+
+export const readSkipDeclarations = Effect.fn("readSkipDeclarations")(function* (
+  root: string,
+  tier: TestTier | undefined,
+) {
+  const files = (yield* scanTestFiles(root)).filter((file) => selectedTierFile(file, tier));
+  return yield* readDeclarationsIn(root, files);
+});
+
+export type SmokeScope =
+  | { readonly kind: "valid"; readonly files: readonly string[] }
+  | { readonly kind: "invalid"; readonly message: string };
+
+export function smokeFiles(scanned: readonly string[], smoke: readonly string[]): SmokeScope {
+  const missing = smoke.filter((file) => !scanned.includes(file));
+  if (missing.length > 0) return { kind: "invalid", message: "checks.smoke names no test file at " + missing.join(", ") };
+  const ignored = smoke.filter((file) => !selectedTierFile(file, undefined));
+  if (ignored.length > 0) {
+    return {
+      kind: "invalid",
+      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)) };
+}
+
+export const readSmokeDeclarations = Effect.fn("readSmokeDeclarations")(function* (
+  root: string,
+  smoke: readonly string[],
+) {
+  const scoped = smokeFiles(yield* scanTestFiles(root), smoke);
+  if (scoped.kind === "invalid") return yield* new SkipDeclarationError({ message: scoped.message });
+  return { files: scoped.files, declarations: yield* readDeclarationsIn(root, scoped.files) };
+});

package/src/testing/test.ts

@@ -4,7 +4,13 @@ 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 { readSkipDeclarations, type Environment, type SkipDeclaration, type TestTier } from "./test-skips.ts";
+import {
+  readSkipDeclarations,
+  readSmokeDeclarations,
+  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";
@@ -24,10 +30,12 @@ export class SkipGateError extends Schema.TaggedError<SkipGateError>()("SkipGate
 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>] [--junit=<file>], and it refuses test filters`;
+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"],
@@ -40,6 +48,7 @@ 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) };
 }
@@ -51,6 +60,7 @@ export function testOptions(args: readonly string[]): TestOptions | undefined {
     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;
 }
 
@@ -158,6 +168,32 @@ const environmentOf = Config.Boolean("CI").pipe(
   Effect.mapError((cause) => new SkipGateError({ message: `cannot tell a ci run from a local one: ${cause.message}` })),
 );
 
+export type SuiteSelection =
+  | { readonly kind: "full" }
+  | { readonly kind: "tier"; readonly tier: TestTier }
+  | { readonly kind: "smoke" };
+
+export function selectSuite(options: TestOptions, environment: Environment): SuiteSelection {
+  if (options.tier !== undefined) return { kind: "tier", tier: options.tier };
+  if (options.full === true || environment === "ci") return { kind: "full" };
+  return { kind: "smoke" };
+}
+
+const SmokeManifest = Schema.Struct({
+  checks: Schema.optional(Schema.Struct({ smoke: Schema.optional(Schema.Array(Schema.NonEmptyString)) })),
+});
+
+export function smokeList(manifest: unknown): readonly string[] | undefined {
+  if (!Schema.is(SmokeManifest)(manifest)) return undefined;
+  return manifest.checks?.smoke ?? [];
+}
+
+export function suiteArgs(selection: SuiteSelection, smoke: readonly string[]): readonly string[] {
+  if (selection.kind === "tier") return tierArgs(selection.tier);
+  if (selection.kind === "smoke") return ["./tests/unit", ...smoke.map((file) => `./${file}`)];
+  return [];
+}
+
 function tierArgs(tier: TestTier | undefined): readonly string[] {
   if (tier === undefined) return [];
   // The preset ignores tests/live and tests/pixel, so only those tiers clear the ignore list.
@@ -169,11 +205,24 @@ export function workerCount(workers: number | undefined): number {
   return workers ?? availableParallelism();
 }
 
-const runSuite = Effect.fn("runSuite")(function* (outfile: string, { tier, workers }: TestOptions) {
+const readSmokeList = Effect.fn("readSmokeList")(function* (root: string) {
+  const file = (yield* Path.Path).join(root, "package.json");
+  const text = yield* (yield* FileSystem.FileSystem).readFileString(file);
+  const manifest = yield* Schema.decodeEffect(Schema.fromJsonString(Schema.Unknown))(text).pipe(
+    Effect.mapError((cause) => new SkipGateError({ message: "cannot read " + file + " as JSON: " + cause.message })),
+  );
+  const smoke = smokeList(manifest);
+  if (smoke === undefined) {
+    return yield* new SkipGateError({ message: file + ": checks.smoke must be an array of test file paths" });
+  }
+  return smoke;
+});
+
+const runSuite = Effect.fn("runSuite")(function* (outfile: string, args: readonly string[], workers: number | undefined) {
   const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-  const args = ["test", "--randomize", `--parallel=${workerCount(workers)}`, ...tierArgs(tier), ...reporterArgs(outfile)];
+  const command = ["test", "--randomize", `--parallel=${workerCount(workers)}`, ...args, ...reporterArgs(outfile)];
   return yield* spawner.exitCode(
-    ChildProcess.make(process.execPath, args, {
+    ChildProcess.make(process.execPath, command, {
       stdin: "ignore",
       stdout: "inherit",
       stderr: "inherit",
@@ -189,11 +238,25 @@ const testEntry = Effect.gen(function* () {
   const { options, junit } = entry;
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
-  const declarations = yield* readSkipDeclarations(process.cwd(), options.tier);
   const environment = yield* environmentOf;
+  const selection = selectSuite(options, environment);
+  const smoke = selection.kind === "smoke" ? yield* readSmokeList(process.cwd()) : [];
+  const scope =
+    selection.kind === "smoke"
+      ? yield* readSmokeDeclarations(process.cwd(), smoke)
+      : {
+          files: undefined,
+          declarations: yield* readSkipDeclarations(process.cwd(), selection.kind === "tier" ? selection.tier : undefined),
+        };
+  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;
+  }
+  const { declarations } = scope;
 
   const outfile = path.join(yield* fs.makeTempDirectoryScoped({ prefix: "checks-test-" }), "junit.xml");
-  const suitePassed = (yield* runSuite(outfile, options)) === ChildProcessSpawner.ExitCode(0);
+  const suitePassed =
+    (yield* runSuite(outfile, suiteArgs(selection, smoke), options.workers)) === ChildProcessSpawner.ExitCode(0);
   const written = yield* fs.exists(outfile);
   if (written && Option.isSome(junit)) {
     yield* fs.makeDirectory(path.dirname(junit.value), { recursive: true });