@ultimat3/cli 23.0.0 → 25.0.0

package/src/test-only-shipped.ts

@@ -0,0 +1,193 @@
+// `package-shape`'s third rule of "test code does not ship": a `src/` module only tests (and
+// fixtures) import is test code under a name `files` cannot see. The tarball excludes `*.test.ts`
+// and `*-fixture.ts`, so a fake, a probe or a `bun:test` helper named anything else rode into
+// every install — 20 of them across eleven packages until 2026-10. The defect is the name.
+
+import { ERROR_DOCS_URL, renderFixShellArg } from '@ultimat3/core';
+import type { ClosureHost } from './import-closure';
+import { resolveSpec } from './import-closure';
+import type { Finding } from './output';
+import { FIXTURE_SUFFIX } from './publish-closure';
+import { eachSourceFile, isGenerated, isTest } from './source-files';
+
+/** A published package: its directory under `packages/` and the files its manifest names. */
+export interface ShippedPackage {
+  readonly dir: string;
+  /** Package-relative (`src/index.ts`), and may be a glob (`src/icons/glyphs/*.ts`). */
+  readonly entries: readonly string[];
+}
+
+export interface TestOnlyModule {
+  readonly path: string;
+  /** Every file that imports or names it — all of them tests, fixtures or test-only modules. */
+  readonly importers: readonly string[];
+}
+
+/**
+ * Every `src/` file a manifest names anywhere — `exports`, `bin`, the `browser` map, a `scripts`
+ * command (`bun run src/icons/build-icons.ts`). Read off the whole document rather than field by
+ * field: a module the manifest names is shipped on purpose, whichever field names it.
+ */
+export function entryPatternsOf(manifest: unknown): readonly string[] {
+  const text = JSON.stringify(manifest ?? null);
+  const found = [...text.matchAll(/(?:\.\/)?(src\/[\w./*-]+?\.tsx?)(?![\w.])/g)];
+  return [...new Set(found.map((match) => match[1] ?? ''))].sort();
+}
+
+// Type-only imports count: the package ships `.ts` source, so a consumer's `tsc` opens the file a
+// shipped `import type` names. One pattern for `from '.'`, `import('.')` and `import '.'`, relative
+// specifiers only: over-matching an importer only ever clears a module, never flags one.
+const RELATIVE = /(?:\bfrom|\bimport)\s*\(?\s*(['"])(\.\.?\/[^'"]*)\1/g;
+/**
+ * A template-literal `import(\`./drivers/${n}\`)`: the static head up to the first `${` names a
+ * DIRECTORY prefix, and any module under it may be the one loaded. With no `${` the closing
+ * backtick ends it and it is an ordinary specifier.
+ */
+const TEMPLATE = /\bimport\s*\(\s*`(\.\.?\/[^`$]*)(\$\{|`)/g;
+/** A file named in a string — `join(import.meta.dir, 'probe.ts')`, `new URL('./worker.ts', …)`. */
+const NAMED = /['"`/]([\w.-]+\.tsx?)['"`]/g;
+
+/**
+ * Whether the match at `index` sits on a line that IS a comment — `//`, a doc comment's `*`, a
+ * `/*` opener. Line-wise and not core's `stripComments`, which is exact and costs ~1.1 s over the
+ * repo's 6,000 files (measured 2026-10-05); asked only of a match, never of every line. The lines
+ * this skips are where a commented-out or quoted-in-prose import lives, and one it keeps can only
+ * clear a module, never flag one.
+ */
+function onCommentLine(text: string, index: number): boolean {
+  let at = text.lastIndexOf('\n', index - 1) + 1;
+  while (text[at] === ' ' || text[at] === '\t') at += 1;
+  const head = text.slice(at, at + 2);
+  return head === '//' || head === '/*' || head.startsWith('*');
+}
+
+/** `from`'s directory joined with a relative `head`, `.` and `..` folded; a trailing `/` kept. */
+function prefixFrom(from: string, head: string): string {
+  const parts = from.split('/').slice(0, -1);
+  const segments = head.split('/');
+  const last = segments.pop() ?? '';
+  for (const segment of segments) {
+    if (segment === '..') parts.pop();
+    else if (segment !== '.' && segment !== '') parts.push(segment);
+  }
+  return `${parts.join('/')}/${last}`;
+}
+
+const isFixture = (path: string): boolean => path.endsWith(FIXTURE_SUFFIX);
+const baseName = (path: string): string => path.slice(path.lastIndexOf('/') + 1);
+
+const add = (map: Map<string, Set<string>>, key: string, value: string): void => {
+  const set = map.get(key);
+  if (set === undefined) map.set(key, new Set([value]));
+  else set.add(value);
+};
+
+/** Who imports each file, and which files name each basename in a string. One pass per file. */
+function referrersOf(sources: ReadonlyMap<string, string>): {
+  readonly imports: ReadonlyMap<string, ReadonlySet<string>>;
+  readonly named: ReadonlyMap<string, ReadonlySet<string>>;
+} {
+  const host: ClosureHost = { read: (path) => sources.get(path), alias: () => undefined };
+  const imports = new Map<string, Set<string>>();
+  const named = new Map<string, Set<string>>();
+  const prefixes: { readonly prefix: string; readonly from: string }[] = [];
+  for (const [from, text] of sources) {
+    for (const match of text.matchAll(RELATIVE)) {
+      if (onCommentLine(text, match.index)) continue;
+      const target = resolveSpec(host, from, match[2] ?? '');
+      if (target !== undefined && target !== from) add(imports, target, from);
+    }
+    for (const match of text.matchAll(TEMPLATE)) {
+      if (onCommentLine(text, match.index)) continue;
+      const head = match[1] ?? '';
+      if (match[2] === '`') {
+        const target = resolveSpec(host, from, head);
+        if (target !== undefined && target !== from) add(imports, target, from);
+      } else prefixes.push({ prefix: prefixFrom(from, head), from });
+    }
+    for (const match of text.matchAll(NAMED)) {
+      if (!onCommentLine(text, match.index)) add(named, match[1] ?? '', from);
+    }
+  }
+  // Few computed imports in any repo, so a scan of every path per prefix costs nothing measurable.
+  for (const { prefix, from } of prefixes) {
+    for (const path of sources.keys()) {
+      if (path !== from && path.startsWith(prefix)) add(imports, path, from);
+    }
+  }
+  return { imports, named };
+}
+
+/**
+ * The shipped `.ts` modules of the given packages whose every importer is a test, a fixture or
+ * another such module — a greatest fixed point, so a helper only a fake imports is caught with the
+ * fake. A module nobody references is not this rule's question, and an entry point is shipped by
+ * definition. `.tsx` is not judged: `FIXTURE_EXCLUSION` matches `-fixture.ts` alone.
+ */
+export function testOnlyModules(
+  sources: ReadonlyMap<string, string>,
+  packages: readonly ShippedPackage[],
+): readonly TestOnlyModule[] {
+  const { imports, named } = referrersOf(sources);
+  const entryGlobs = new Map(
+    packages.map((pkg) => [
+      pkg.dir,
+      pkg.entries.map((entry) => new Bun.Glob(`packages/${pkg.dir}/${entry}`)),
+    ]),
+  );
+  const referrers = new Map<string, ReadonlySet<string>>();
+  for (const path of sources.keys()) {
+    const dir = /^packages\/([^/]+)\/src\//.exec(path)?.[1];
+    const globs = dir === undefined ? undefined : entryGlobs.get(dir);
+    if (globs === undefined || !path.endsWith('.ts') || isGenerated(path)) continue;
+    if (isTest(path) || isFixture(path) || globs.some((glob) => glob.match(path))) continue;
+    const from = new Set([...(imports.get(path) ?? []), ...(named.get(baseName(path)) ?? [])]);
+    from.delete(path);
+    if (from.size > 0) referrers.set(path, from);
+  }
+  const testOnly = new Set(referrers.keys());
+  const live = (path: string): boolean => !isTest(path) && !isFixture(path) && !testOnly.has(path);
+  for (let changed = true; changed; ) {
+    changed = false;
+    for (const path of testOnly) {
+      if (![...(referrers.get(path) ?? [])].some(live)) continue;
+      testOnly.delete(path);
+      changed = true;
+    }
+  }
+  return [...testOnly].sort().map((path) => ({
+    path,
+    importers: [...(referrers.get(path) ?? [])].sort(),
+  }));
+}
+
+/** `X_PACKAGE_TEST_ONLY_SHIPPED`, its fix the registered rename with the real paths in it. */
+export const testOnlyShippedFinding = (module: TestOnlyModule): Finding => {
+  const shown = module.importers.slice(0, 3).join(', ');
+  const more = module.importers.length > 3 ? ` and ${module.importers.length - 3} more` : '';
+  return {
+    code: 'X_PACKAGE_TEST_ONLY_SHIPPED',
+    cause: `${module.path} is imported only by tests and fixtures (${shown}${more}), and "files" publishes it — test scaffolding in every install`,
+    fix: `git mv ${renderFixShellArg(module.path, '<the module above>')} ${renderFixShellArg(module.path.replace(/\.ts$/, FIXTURE_SUFFIX), '<its name>-fixture.ts')}   # and update its importers`,
+    docs: ERROR_DOCS_URL,
+    at: module.path,
+    meta: { importers: [...module.importers] },
+  };
+};
+
+/**
+ * The rule over a repo on disk. Every source file is a possible importer — a script reading a
+ * package's module by relative path is a shipped use of it — so the walk is the gate's own
+ * (`eachSourceFile`), tests included. A repo with no published package reads nothing.
+ */
+export async function checkTestOnlyShipped(
+  root: string,
+  packages: readonly ShippedPackage[],
+): Promise<readonly Finding[]> {
+  if (packages.length === 0) return [];
+  const paths: string[] = [];
+  for await (const path of eachSourceFile(root)) if (!isGenerated(path)) paths.push(path);
+  const texts = await Promise.all(paths.map((path) => Bun.file(`${root}/${path}`).text()));
+  const sources = new Map(paths.map((path, index) => [path, texts[index] ?? '']));
+  return testOnlyModules(sources, packages).map(testOnlyShippedFinding);
+}

package/src/test-passes.ts

@@ -24,8 +24,6 @@ export interface PassInput {
   readonly workers: number;
   /** The positional, when there was one. A pass over one type keeps it; the split never adds one. */
   readonly type?: TestType;
-  /** Set for a `--worker I` rerun, which is one process by construction. */
-  readonly shard?: number;
 }
 
 const widthFor = (files: readonly TestFile[], workers: number): number =>
@@ -45,22 +43,9 @@ const widthFor = (files: readonly TestFile[], workers: number): number =>
  *
  * Each serial type is its own pass rather than one pass over both, because the pass's `type` is
  * what its failure reproduces with: `x test live --workers 1` selects exactly the files that ran.
- *
- * A `--worker I` rerun is left whole: it is a single `bun test --isolate --shard=i/N` process, so
- * nothing inside it runs beside anything else, and splitting it would make shard i of the rerun a
- * different set of files from shard i of the run it reproduces.
  */
 export function testPasses(input: PassInput): readonly TestPass[] {
   const serialTypes = new Set<TestType>(SERIAL_TYPES);
-  if (input.shard !== undefined) {
-    return [
-      {
-        files: input.files,
-        workers: widthFor(input.files, input.workers),
-        ...(input.type === undefined ? {} : { type: input.type }),
-      },
-    ];
-  }
   const shared = input.files.filter((file) => !serialTypes.has(ownerOf(file.path)));
   const passes: TestPass[] = [];
   // Cheapest first, and the widest first: the pool run is most of the corpus and most of the

package/src/test-select.ts

@@ -6,11 +6,13 @@ import { join } from 'node:path';
 // Bun ships no equivalent: `join` builds the host-separator path from the scan root to a hit.
 // Sizing is Bun's own (`Bun.file().size`), so nothing here reaches for `node:fs`.
 import { nearestName, renderFixShellArg } from '@ultimat3/core';
+import { TEST_TYPES } from '@ultimat3/testing';
 import { BadFlagError } from './errors';
 import type { ParsedArgs } from './parse';
 import { flagString } from './parse';
+import { isIgnoredTestPath } from './test-ignores';
 import type { TestType } from './verify-tests';
-import { ownerOf, TEST_TYPES } from './verify-tests';
+import { ownerOf } from './verify-tests';
 
 export interface TestFile {
   readonly path: string;
@@ -27,20 +29,10 @@ const TEST_GLOB = '**/*.test.{ts,tsx}';
 
 /**
  * The root `test` script's ignore list, kept identical so `x test` and `bun run test` see one
- * suite. `e2e/` is NOT on it: an opt-in suite that the gate runs but `x test` silently drops is
- * a suite nobody runs until CI says so. `examples/` is, because the reference app is a separate
- * project with its own gate — `x verify` there, not `x test` here.
- *
- * `dummy/` and `build/` complete the list `verify-tests.ts` already excluded (`NEVER_A_TEST`). The
- * comment above claimed the two agreed and they did not: `x test unit` discovered 464 files where
- * the gate's `unit` step ran 441, so the gate's own test steps — which now select through this
- * function — would have started running a nested demo app's suite on the framework's gate.
- *
- * Both directories are gated where they belong, by `scripts/reference-app-gate.ts` running
- * `x verify` inside each app — see `NEVER_A_TEST` for why that is the only place they run.
+ * suite — `test-ignores.ts` holds it, and the serial steps' argv projects the same policy. `e2e/`
+ * is NOT on it: an opt-in suite that the gate runs but `x test` silently drops is a suite nobody
+ * runs until CI says so.
  */
-const IGNORED = ['/dist/', '/build/', '/node_modules/', '/examples/', '/dummy/'];
-
 /**
  * File size stands in for duration: cheap to read, and it correlates far better than file count.
  * `type`, when given, narrows to exactly the files verify-tests.ts would run for that suite — one
@@ -58,7 +50,7 @@ export async function discoverTests(
   const files: TestFile[] = [];
   for await (const found of new Bun.Glob(TEST_GLOB).scan({ cwd: root, absolute: false })) {
     const path = found.split('\\').join('/');
-    if (IGNORED.some((part) => `/${path}`.includes(part))) continue;
+    if (isIgnoredTestPath(path)) continue;
     if (filters !== undefined && !filters.some((part) => path.includes(part))) continue;
     if (type !== undefined && !belongsToType(path, type)) continue;
     files.push({ path, bytes: Bun.file(join(root, path)).size });

package/src/test-shards.ts

@@ -39,12 +39,12 @@
 // `@ultimat3/testing`'s preload clears the plugins after each file (`isolated-plugins.ts`). And the
 // per-WORKER database survives untouched: `@ultimat3/testing`'s `workerId` already read
 // `BUN_TEST_WORKER_ID` as its second key, which is exactly what Bun sets, 1..N, one per real
-// process (probed on 1.4.0). `ULTIMATE_TEST_WORKER` stays the first key and is what `--worker`
-// still sets, so a single-shard rerun keeps naming its own database.
+// process (probed on 1.4.0).
 
 // why: Bun ships no path-join primitive; the timings cache lives under the run's root.
 import { join } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
+import { ISOLATED_ENV } from '@ultimat3/testing';
 import type { AffectedSelection } from './affected';
 import type { Runner } from './exec';
 import { msg } from './messages';
@@ -52,9 +52,6 @@ import type { CommandResult, Finding, JsonValue, StepResult } from './output';
 import { quoteArg } from './shell-quote';
 import { testEnvOverrides } from './test-dotenv';
 
-/** `@ultimat3/testing`'s `ISOLATED_ENV`, restated: `cli → testing` is a runtime edge, kept to fixtures. */
-export const ISOLATED_TEST_ENV = 'ULTIMATE_TEST_ISOLATED';
-
 /** Bun's per-file durations, cached under the run's root and refreshed by every parallel run. */
 export const TEST_TIMINGS_FILE = '.x/test-timings.json';
 
@@ -68,24 +65,13 @@ import type { TestType } from './verify-tests';
  * The argv for one run. An explicit file list, never a re-glob: discovery already decided which
  * files belong to this type, and a child that globs again can pick up a file the selection removed.
  *
- * `--parallel=N` for the whole selection, `--shard=i+1/N` for one slice of it. The shard form is
- * `--worker`'s, and it carries `--isolate` in its own right — only `--parallel` implies it, and a
- * partition without a fresh module registry per file is the failure mode this whole design exists
- * to remove: measured on this repo, an 8-way split turned 0 failures into 36, every one
- * `X_PERMISSION_UNKNOWN` in `@ultimat3/query` because the `packages/cli` file that had been
- * declaring `feed:read` for it landed elsewhere. Half a dozen registries here are process-global by
- * design — the permission set, the roles, the entity/action/query tables, the error-code titles,
- * the fixture bag — and a serial `bun test` only passes because glob order happens to put every
- * declaring file before every file that reads what it left behind.
- *
- * Bun's shard partition is round-robin over the list it is given, so the sorted list this hands it
- * makes `--shard=2/8` the same 1/8 on CI and on a laptop (probed on 1.4.0).
+ * `--parallel=N` over the selection, sorted, so two runs over one corpus hand Bun the same list.
+ * One CI job's share of the corpus is `x verify --only unit --shard i/n` (`verify-shard.ts`), never
+ * a flag here: `x test --worker I` was a second, 0-based, unhashed split of the same suite.
  */
 export function testArgs(input: {
   readonly files: readonly string[];
   readonly workers: number;
-  /** 0-based, matching `--worker`. Absent runs the whole selection across `workers` processes. */
-  readonly shard?: number;
   /**
    * Everything after a bare `--`, handed to `bun test` verbatim and BEFORE the file list, which is
    * where bun reads its flags. `ParsedArgs.passthrough` had no reader anywhere until 2026-09, so
@@ -114,32 +100,23 @@ export function testArgs(input: {
   const isolate =
     extra.includes('--isolate') || (input.isolate === true && !extra.includes('--no-isolate'));
   const bare = extra.filter((arg) => arg !== '--isolate' && arg !== '--no-isolate');
-  return input.shard === undefined
-    ? [
-        'bun',
-        'test',
-        `--parallel=${String(input.workers)}`,
-        ...(isolate ? [] : ['--no-isolate']),
-        ...(input.timings === undefined || bare.some((arg) => arg.startsWith('--timings'))
-          ? []
-          : [`--timings=${input.timings}`, '--update-timings']),
-        ...bare,
-        ...files,
-      ]
-    : [
-        'bun',
-        'test',
-        ...(isolate ? ['--isolate'] : []),
-        `--shard=${String(input.shard + 1)}/${String(input.workers)}`,
-        ...bare,
-        ...files,
-      ];
+  return [
+    'bun',
+    'test',
+    `--parallel=${String(input.workers)}`,
+    ...(isolate ? [] : ['--no-isolate']),
+    ...(input.timings === undefined || bare.some((arg) => arg.startsWith('--timings'))
+      ? []
+      : [`--timings=${input.timings}`, '--update-timings']),
+    ...bare,
+    ...files,
+  ];
 }
 
 /**
  * The files an argv selects, flags stripped. `bun test` takes its file list positionally, so this
  * is the inverse of `testArgs` and the one thing a test asserting "what did the child get?" needs
- * — the flag COUNT is not fixed (`--parallel=N` is one token, a shard run carries two more), and a
+ * — the flag COUNT is not fixed (`--no-isolate` and the timings pair come and go), and a
  * test slicing a hardcoded prefix length reads a flag as a filename the day that changes.
  */
 export const filesIn = (command: readonly string[]): readonly string[] =>
@@ -154,12 +131,9 @@ export interface ReproduceOptions {
   readonly sample?: number;
   /**
    * The `--affected` narrowing, when there was one. The input most easily forgotten: `--affected`
-   * decides which files exist to run at all, so a rerun without it selects the WHOLE corpus and
-   * its shard 2 is a different shard 2.
+   * decides which files exist to run at all, so a rerun without it selects the WHOLE corpus.
    */
   readonly affected?: AffectedSelection;
-  /** 0-based, when reproducing ONE shard. Absent reproduces the whole selection. */
-  readonly shard?: number;
   /** What the caller put after `--`. It reaches `bun test`, so a rerun without it runs differently. */
   readonly passthrough?: readonly string[];
   /** The run was isolated per file; the rerun must be too. */
@@ -185,7 +159,6 @@ export function reproduceFor(options: ReproduceOptions): string {
     ...(options.affected?.dirty === true ? ['--dirty'] : []),
     '--workers',
     String(options.workers),
-    ...(options.shard === undefined ? [] : ['--worker', String(options.shard)]),
     ...(options.isolate === true ? ['--isolate'] : []),
     // Last, and after a `--` of its own, because that is where the caller typed it and where the
     // parser will find it again. Quoted for `shell-quote.ts`'s reason: a reproduce line is pasted.
@@ -200,14 +173,11 @@ export interface RunShardsOptions {
   readonly runner: Runner;
   readonly files: readonly TestFile[];
   readonly workers: number;
-  /** Run exactly one shard of the same N-way split, not a one-worker run of everything. */
-  readonly only?: number;
   readonly filter?: string;
   readonly type?: TestType;
   /**
    * Set when `--sample` narrowed `files`: `kept` is what survived, `total` what discovery found.
-   * `kept` is carried rather than counted from what ran, because `--worker N` runs one shard of the
-   * sample and would otherwise report that shard's size as the corpus.
+   * Carried rather than counted from what ran: a pass runs part of the sample, never the corpus.
    */
   readonly sample?: { readonly kept: number; readonly total: number };
   /** Passed straight to `reproduceFor`: see `ReproduceOptions.affected`. */
@@ -248,7 +218,6 @@ const planOf = (
   ...(pass.type === undefined ? {} : { type: pass.type }),
   ...(options.sample === undefined ? {} : { sample: options.sample.kept }),
   ...(options.affected === undefined ? {} : { affected: options.affected }),
-  ...(options.only === undefined ? {} : { shard: options.only }),
   ...(options.isolate === true ? { isolate: true } : {}),
   ...(options.passthrough === undefined || options.passthrough.length === 0
     ? {}
@@ -256,17 +225,12 @@ const planOf = (
 });
 
 /**
- * `X_TEST_SHARD_FAILED` for a `--worker` run and `X_TEST_FAILED` for a whole one, because the two
- * name different reruns: a shard is reproduced by naming it, and a full run by rerunning it. Both
- * codes already exist and both are already documented — a third would be a new name for a failed
- * `bun test`.
+ * `X_TEST_FAILED`, whose `fix:` reruns exactly what failed. `X_TEST_SHARD_FAILED` was the
+ * `--worker` rerun's and went with it: the code stays registered (codes are forever) and unthrown.
  */
 export const failureOf = (code: number, files: number, plan: ReproduceOptions): Finding => ({
-  code: plan.shard === undefined ? 'X_TEST_FAILED' : 'X_TEST_SHARD_FAILED',
-  cause:
-    plan.shard === undefined
-      ? `${plan.type ?? 'test'} run exited ${code} across ${plan.workers} worker(s) (${files} file(s))`
-      : `shard ${plan.shard} of ${plan.workers} exited ${code} (${files} file(s))`,
+  code: 'X_TEST_FAILED',
+  cause: `${plan.type ?? 'test'} run exited ${code} across ${plan.workers} worker(s) (${files} file(s))`,
   fix: reproduceFor(plan),
   docs: ERROR_DOCS_URL,
 });
@@ -281,19 +245,17 @@ export const failureOf = (code: number, files: number, plan: ReproduceOptions):
  * it. And every pass runs even after one fails — the caller asked for a suite, and a report that
  * stops at the first red step hides the rest of the answer.
  *
- * `ULTIMATE_TEST_WORKER` is still set for a `--worker` rerun and only then: that run is one
- * process, so naming its database is this file's to do. A `--parallel` run has N of them and Bun
- * numbers each with `BUN_TEST_WORKER_ID`, which `@ultimat3/testing`'s `workerId` already reads.
+ * No `ULTIMATE_TEST_WORKER` here: a `--parallel` run has N processes and Bun numbers each with
+ * `BUN_TEST_WORKER_ID`, which `@ultimat3/testing`'s `workerId` already reads.
  */
 export async function runShards(options: RunShardsOptions): Promise<CommandResult> {
-  const only = options.only;
   // Computed ONCE per invocation, never per pass: every pass spawns from the same `root` and the
   // same parent env, so the leaked-key set cannot differ pass to pass.
   const envOverrides: Record<string, string | undefined> = {
     ...testEnvOverrides(options.root, options.env ?? Bun.env),
     // Only an isolated run: the preload clears `Bun.plugin` handlers after each file, which in a
     // shared global would leave the next `.tsx` compiling with Bun's classic factory.
-    ...(isolatedRun(options) ? { [ISOLATED_TEST_ENV]: '1' } : {}),
+    ...(isolatedRun(options) ? { [ISOLATED_ENV]: '1' } : {}),
   };
   const passthrough = options.passthrough ?? [];
   const watching = passthrough.includes('--watch');
@@ -302,7 +264,6 @@ export async function runShards(options: RunShardsOptions): Promise<CommandResul
     files: options.files,
     workers: options.workers,
     ...(options.type === undefined ? {} : { type: options.type }),
-    ...(only === undefined ? {} : { shard: only }),
   });
   const started = performance.now();
   const steps: StepResult[] = [];
@@ -312,53 +273,38 @@ export async function runShards(options: RunShardsOptions): Promise<CommandResul
   let exitCode = 0;
   for (const pass of passes) {
     const files = pass.files.map((file) => file.path);
-    // A `--worker` rerun is one process over one shard and is never split: shard i of the rerun
-    // must be the same files as shard i of the run it reproduces. Nor is `-- --watch`, which never
-    // exits, so a second batch would never start. Every other pass is spent in `test-batches.ts`'
-    // batches, one `bun test` after another.
-    const batches =
-      only === undefined && !watching
-        ? testBatches(
-            files,
-            pass.workers,
-            isolatedRun(options) ? BATCH_FILES_PER_WORKER : SHARED_BATCH_FILES_PER_WORKER,
-          )
-        : [files];
+    // `-- --watch` is never split: it never exits, so a second batch would never start. Every
+    // other pass is spent in `test-batches.ts`' batches, one `bun test` after another.
+    const batches = !watching
+      ? testBatches(
+          files,
+          pass.workers,
+          isolatedRun(options) ? BATCH_FILES_PER_WORKER : SHARED_BATCH_FILES_PER_WORKER,
+        )
+      : [files];
     const result = await runBatches({
       runner: options.runner,
       batches,
       stopOnFailure: bailing,
       workers: pass.workers,
-      // A `--worker` rerun is one process whatever its N says, and a serial pass is one worker:
-      // only a default-width parallel pass leases from the machine pool.
-      ...(only === undefined && pass.workers > 1 && options.lease !== undefined
-        ? { lease: options.lease }
-        : {}),
+      // A serial pass is one worker: only a default-width parallel pass leases from the pool.
+      ...(pass.workers > 1 && options.lease !== undefined ? { lease: options.lease } : {}),
       argsFor: (batch, width) =>
         testArgs({
           files: batch,
-          workers: only === undefined ? width : pass.workers,
-          ...(only === undefined ? {} : { shard: only }),
+          workers: width,
           ...(options.passthrough === undefined ? {} : { passthrough: options.passthrough }),
           ...(options.isolate === undefined ? {} : { isolate: options.isolate }),
           timings: join(options.root, TEST_TIMINGS_FILE),
         }),
       options: {
         cwd: options.root,
-        ...(Object.keys(envOverrides).length === 0 && only === undefined
-          ? {}
-          : {
-              env: {
-                ...envOverrides,
-                ...(only === undefined ? {} : { ULTIMATE_TEST_WORKER: String(only) }),
-              },
-            }),
+        ...(Object.keys(envOverrides).length === 0 ? {} : { env: envOverrides }),
       },
     });
     batchCount += batches.length;
     const plan = planOf(options, pass);
-    const label =
-      only === undefined ? `${pass.workers} worker(s)` : `shard ${only} of ${pass.workers}`;
+    const label = `${pass.workers} worker(s)`;
     steps.push({
       name: `${pass.type === undefined ? label : `${pass.type} · ${label}`} · ${files.length} files${
         batches.length > 1 ? msg('cli.test.batches', { batches: batches.length }) : ''
@@ -403,7 +349,6 @@ export async function runShards(options: RunShardsOptions): Promise<CommandResul
     durationMs,
     ...(options.filter === undefined ? {} : { filter: options.filter }),
     ...(sample === undefined ? {} : { sample: { kept: sample.kept, total: sample.total } }),
-    ...(only === undefined ? {} : { shard: only }),
     // Only when the split made more than one, so a single-pass run's JSON is byte-identical to
     // what it has always been — and a mixed one can never be read as if it were a single run.
     ...(spent.length > 1 ? { passes: spent } : {}),

package/src/test-workers.ts

@@ -1,14 +1,36 @@
 // How wide a parallel test run goes, decided in one place. `x test --workers`, `x verify
 // --workers` and every parallel step of the gate read this — a second default would split the same
-// suite two different ways, and the `--worker N` reproduction a shard failure prints would then
-// name a shard the gate never ran.
+// suite two different ways, and the `--workers N` a failure's reproduction prints would then name
+// a width the gate never ran.
 
 // Bun ships no CPU-count or memory primitive: `cpus()` is the fallback when navigator cannot
 // answer, and `totalmem()` is the only reader of the machine's RAM.
 // why: Bun ships no CPU-count or total-memory primitive.
 import { cpus, totalmem } from 'node:os';
+import { UltimateError } from '@ultimat3/core';
 import type { TestType } from '@ultimat3/testing';
-import { TestBudgetInvalidError } from './verify-errors';
+
+/**
+ * `ULTIMATE_TEST_MEMORY_BUDGET` or `ULTIMATE_TEST_MAX_WORKERS` set to something that does not
+ * parse. Refused rather than ignored: a typo read as "the default" is a run sized for a machine
+ * the caller said this is not.
+ */
+export class TestBudgetInvalidError extends UltimateError {
+  constructor(name: string, value: string) {
+    super({
+      code: 'X_TEST_BUDGET_INVALID',
+      cause: `${name}=${JSON.stringify(value)} does not parse — ${
+        name === 'ULTIMATE_TEST_MAX_WORKERS'
+          ? 'expected a positive integer'
+          : 'expected a size such as 3g, 512m or 4GiB'
+      }`,
+      fix:
+        name === 'ULTIMATE_TEST_MAX_WORKERS'
+          ? 'ULTIMATE_TEST_MAX_WORKERS=4 x verify'
+          : 'ULTIMATE_TEST_MEMORY_BUDGET=3g x verify',
+    });
+  }
+}
 
 /** navigator first: it is the runtime's own answer, and it respects a container's CPU limit. */
 export function availableCpus(): number {
@@ -219,7 +241,7 @@ export const sharedWorkers = (
  * Which types run across worker processes, and why the other two cannot.
  *
  * Parallel is safe when the only thing a test file shares with another file is the database, and
- * the database is per worker by construction (`ULTIMATE_TEST_WORKER` → one clone of the migrated
+ * the database is per worker by construction (`BUN_TEST_WORKER_ID` → one clone of the migrated
  * template, `@ultimat3/testing`'s `acquireWorkerDatabase`). Every other process-global in this
  * framework — the permission set, the roles, the entity/action/query registries, the error-code
  * titles, the fixture bag — is handled by `--isolate` giving each FILE its own module registry.