@ultimat3/cli 22.14.0 → 23.0.0

package/src/verify-run.ts

@@ -3,15 +3,19 @@
 // command: what a run means — never bail early, count what actually ran — belongs to neither.
 
 import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
+import type { CoverageMap } from './coverage-lcov';
+import { encodeCoverage } from './coverage-lcov';
 import { msg } from './messages';
-import type { CommandResult, Finding, StepResult } from './output';
+import type { CommandResult, Finding, JsonValue, StepResult } from './output';
+import { guardStep, raceDeadline, stepTimeoutFinding, stepTimeoutMs } from './verify-deadline';
 import {
   floorRequires,
   readVerifyFloor,
   skippedSuiteFinding,
   vanishedSuiteFinding,
 } from './verify-floor';
-import type { StepOutcome, VerifyContext, VerifyStep } from './verify-step';
+import type { CoverageNumbers, StepOutcome, VerifyContext, VerifyStep } from './verify-step';
+import { GATE_COMMAND } from './verify-step';
 
 /**
  * Run every step, never bailing early: an agent fixing three things at once needs all
@@ -30,6 +34,30 @@ export async function runVerify(
   const only = onlyList(ctx.only);
   const selected = only === undefined ? steps : steps.filter((step) => only.includes(step.name));
   const byName = new Map<string, StepResult>();
+  // Per step: the numbers a judged run measured, or — under `--shard`, which cannot judge — the
+  // `facts` its slice covered, for `x verify merge` to fold.
+  const coverage = new Map<string, JsonValue>();
+  // One per run: a step's tag is `<step>@<run>`, so two gates on one machine never kill each
+  // other's children.
+  const runId = crypto.randomUUID().slice(0, 8);
+  const run = async (step: VerifyStep, stepCtx: VerifyContext): Promise<void> => {
+    const ran = await runStep(step, stepCtx, floor, runId);
+    byName.set(step.name, ran.result);
+    if (ran.coverage !== undefined) {
+      coverage.set(step.name, { facts: encodeCoverage(ran.coverage) });
+    } else if (ran.measured !== undefined) {
+      const { lines, funcs, files } = ran.measured;
+      coverage.set(step.name, { lines, funcs, files });
+    }
+    // Told as it finishes, never at the end: the caller streams it, so a cancelled job's log
+    // ends on the last step that finished (#589). A progress line is not the verdict: a listener
+    // that throws — stderr closed under it — must not take the gate down with it.
+    try {
+      ctx.onStep?.(ran.result);
+    } catch {
+      // Nothing to report it on; the document on stdout still carries the step.
+    }
+  };
   const began = performance.now();
   // The static steps wait for the serial suites and then run BESIDE them — only when `live` is in
   // the list, so a one-step run (`--only`) and a list with no serial suite keep today's order.
@@ -51,16 +79,12 @@ export async function runVerify(
   for (const step of selected) {
     if (beside.includes(step)) continue;
     if (step.name === SERIAL_SUITES[0]) {
-      pending = Promise.all(
-        beside.map(async (other) => {
-          byName.set(other.name, await runStep(other, base, floor));
-        }),
-      ).then(() => undefined);
+      pending = Promise.all(beside.map((other) => run(other, base))).then(() => undefined);
     } else if (!SERIAL_SUITES.includes(step.name)) {
       await join();
     }
     const inWindow = pending !== undefined && SERIAL_SUITES.includes(step.name);
-    byName.set(step.name, await runStep(step, inWindow ? shared : base, floor));
+    await run(step, inWindow ? shared : base);
   }
   await join();
   // Reported in the declared order, whatever order the steps finished in: the table, `--json` and
@@ -98,6 +122,7 @@ export async function runVerify(
       // summary line to learn that this run checked one thing.
       // `only` is always the LIST, in declared order — one name is a list of one.
       ...(only === undefined ? {} : { notAGateRun: true, only: [...only] }),
+      ...(coverage.size === 0 ? {} : { coverage: Object.fromEntries(coverage) }),
     },
     // The step's own status: one step, so `failedSteps` is that step and nothing else.
     exitCode: failedSteps.length === 0 ? 0 : 1,
@@ -163,14 +188,27 @@ async function runStep(
   step: VerifyStep,
   ctx: VerifyContext,
   floor: Awaited<ReturnType<typeof readVerifyFloor>>,
-): Promise<StepResult> {
+  runId: string,
+): Promise<{
+  readonly result: StepResult;
+  readonly coverage?: CoverageMap;
+  readonly measured?: CoverageNumbers;
+}> {
+  const command = ctx.command ?? GATE_COMMAND;
   // Inside the step's own failure, like a throwing `run`: an `applies` that threw escaped every
   // catch and aborted the whole gate, which is the one outcome `runVerify` exists to prevent.
   let applies: boolean;
   try {
     applies = step.applies === undefined ? true : await step.applies(ctx);
   } catch (error) {
-    return { name: step.name, ok: false, durationMs: 0, findings: [findingOf(error, step.name)] };
+    return {
+      result: {
+        name: step.name,
+        ok: false,
+        durationMs: 0,
+        findings: [findingOf(error, step.name, command)],
+      },
+    };
   }
   if (!applies) {
     // A skip this repo already ruled out is not a skip. The step ran here before — the floor is
@@ -180,20 +218,36 @@ async function runStep(
     // the summary, `data.failed`, and the reference-app gate's own red list.
     const required = floorRequires(floor, step.name);
     return {
-      name: step.name,
-      ok: !required,
-      durationMs: 0,
-      skipped: !required,
-      findings: required ? [vanishedSuiteFinding(step.name)] : [],
+      result: {
+        name: step.name,
+        ok: !required,
+        durationMs: 0,
+        skipped: !required,
+        findings: required ? [vanishedSuiteFinding(step.name, command)] : [],
+      },
     };
   }
   const started = performance.now();
-  const outcome = await step.run(ctx).catch(
-    (error: unknown): StepOutcome => ({
-      ok: false,
-      findings: [findingOf(error, step.name)],
-    }),
+  // The deadline: a step that hangs fails BY NAME and its processes are killed, instead of eating
+  // the CI job's whole timeout and leaving a log that says nothing (#589). The step runs on a
+  // guarded runner, so everything it starts carries its tag — that is what the kill finds.
+  const limit = stepTimeoutMs(step.name, ctx.stepTimeoutMs, floor?.stepTimeoutMs);
+  const guard = guardStep(ctx.runner, `${step.name}@${runId}`);
+  const raced = await raceDeadline(
+    step.run({ ...ctx, runner: guard.runner }).catch(
+      (error: unknown): StepOutcome => ({
+        ok: false,
+        findings: [findingOf(error, step.name, command)],
+      }),
+    ),
+    limit,
   );
+  const outcome: StepOutcome = raced.timedOut
+    ? {
+        ok: false,
+        findings: [stepTimeoutFinding(step.name, limit, await guard.expire(), command)],
+      }
+    : raced.value;
   // A suite that executed nothing did not run, whatever its exit code says: `bun test` exits 0
   // over an all-skipped file, so the counts are the only channel that can tell the two apart.
   // ONE definition of "nothing ran", read twice, because the floor decides which of the two
@@ -208,23 +262,27 @@ async function runStep(
   // step's own findings so `data.failed`, the counts and every gate reading this table carry it.
   const vanished = nothingRan && required ? [skippedSuiteFinding(step.name, tests.skipped)] : [];
   return {
-    name: step.name,
-    ok: outcome.ok && vanished.length === 0,
-    durationMs: Math.round(performance.now() - started),
-    // Without a floor to require it, a suite that ran nothing is a SKIP and not a pass (#434):
-    // the `e2e` step printed `✓ e2e 46ms` over its one skipped test, which is the one thing a
-    // step table may never do — a reader cannot tell a lane that ran from a lane that did not.
-    skipped: nothingRan && !required,
-    findings: [...outcome.findings, ...vanished],
-    ...(outcome.output === undefined ? {} : { output: outcome.output }),
-    ...(outcome.workers === undefined ? {} : { workers: outcome.workers }),
-    ...(outcome.widthReason === undefined ? {} : { widthReason: outcome.widthReason }),
-    ...(outcome.shard === undefined ? {} : { shard: outcome.shard }),
-    ...(tests === undefined ? {} : { tests }),
+    result: {
+      name: step.name,
+      ok: outcome.ok && vanished.length === 0,
+      durationMs: Math.round(performance.now() - started),
+      // Without a floor to require it, a suite that ran nothing is a SKIP and not a pass (#434):
+      // the `e2e` step printed `✓ e2e 46ms` over its one skipped test, which is the one thing a
+      // step table may never do — a reader cannot tell a lane that ran from a lane that did not.
+      skipped: nothingRan && !required,
+      findings: [...outcome.findings, ...vanished],
+      ...(outcome.output === undefined ? {} : { output: outcome.output }),
+      ...(outcome.workers === undefined ? {} : { workers: outcome.workers }),
+      ...(outcome.widthReason === undefined ? {} : { widthReason: outcome.widthReason }),
+      ...(outcome.shard === undefined ? {} : { shard: outcome.shard }),
+      ...(tests === undefined ? {} : { tests }),
+    },
+    ...(outcome.coverage === undefined ? {} : { coverage: outcome.coverage }),
+    ...(outcome.measured === undefined ? {} : { measured: outcome.measured }),
   };
 }
 
-function findingOf(error: unknown, step: string): Finding {
+function findingOf(error: unknown, step: string, command: string): Finding {
   // A step may throw anything, including an Error that fights being read: `instanceof` runs a
   // Proxy's `getPrototypeOf` trap and `.message` runs a getter, so a hostile throw would take the
   // gate's own report down with it — the one message that may never be lost.
@@ -232,7 +290,7 @@ function findingOf(error: unknown, step: string): Finding {
   return {
     code: 'X_VERIFY_FAILED',
     cause: `step "${step}" threw: ${cause}`,
-    fix: 'x verify --json',
+    fix: `${command} --json`,
     docs: ERROR_DOCS_URL,
   };
 }

package/src/verify-shard.ts

@@ -10,6 +10,7 @@ import { CryptoHasher } from 'bun';
 import type { ShardFacts } from './output';
 import { VerifyShardInvalidError } from './verify-errors';
 import type { VerifyStepName } from './verify-step';
+import { GATE_COMMAND } from './verify-step';
 
 /** The steps a shard may split: the parallel suites. `live` and `e2e` are serial by design. */
 export const SHARDABLE_STEPS: readonly VerifyStepName[] = ['unit', 'contract', 'job'];
@@ -20,18 +21,22 @@ export interface ShardSpec {
   readonly total: number;
 }
 
-/** `3/8` → `{ index: 3, total: 8 }`, refused unless `1 <= i <= n`. */
-export function parseShard(raw: string): ShardSpec {
+/**
+ * `3/8` → `{ index: 3, total: 8 }`, refused unless `1 <= i <= n`. `command` is the gate as the
+ * caller was invoked, so the refusal's fix runs where it was raised.
+ */
+export function parseShard(raw: string, command: string = GATE_COMMAND): ShardSpec {
   const match = /^\s*(\d+)\s*\/\s*(\d+)\s*$/.exec(raw);
   const index = match === null ? Number.NaN : Number(match[1]);
   const total = match === null ? Number.NaN : Number(match[2]);
   if (!Number.isSafeInteger(index) || !Number.isSafeInteger(total) || total < 1 || index < 1) {
-    throw new VerifyShardInvalidError({ reason: `"${raw}" is not i/n (e.g. 2/4)` });
+    throw new VerifyShardInvalidError({ reason: `"${raw}" is not i/n (e.g. 2/4)`, command });
   }
   if (index > total) {
     throw new VerifyShardInvalidError({
       reason: `shard ${String(index)} does not exist in a ${String(total)}-way split (1..${String(total)})`,
-      fix: `x verify --only unit --shard ${renderFixShellArg(`${String(total)}/${String(total)}`, '<i/n>')} --json`,
+      fix: `${command} --only unit --shard ${renderFixShellArg(`${String(total)}/${String(total)}`, '<i/n>')} --json`,
+      command,
     });
   }
   return { index, total };
@@ -41,11 +46,14 @@ export function parseShard(raw: string): ShardSpec {
  * The steps a shard run may name: every one must be shardable. Refused with the step named, and a
  * fix that keeps the shardable ones — `live`/`e2e` belong in a job of their own.
  */
-export function assertShardable(only: readonly VerifyStepName[] | undefined): void {
+export function assertShardable(
+  only: readonly VerifyStepName[] | undefined,
+  command: string = GATE_COMMAND,
+): void {
   if (only === undefined || only.length === 0) {
     throw new VerifyShardInvalidError({
       reason: 'a shard is one slice of ONE parallel step and needs --only to name it',
-      fix: 'x verify --only unit --shard 1/4 --json',
+      command,
     });
   }
   const refused = only.filter((step) => !SHARDABLE_STEPS.includes(step));
@@ -57,8 +65,9 @@ export function assertShardable(only: readonly VerifyStepName[] | undefined): vo
       } in a job of its own without --shard`,
       fix:
         kept.length === 0
-          ? `x verify --only ${renderFixShellArg(refused.join(','), '<step,step>')} --json`
-          : `x verify --only ${renderFixShellArg(kept.join(','), '<step,step>')} --shard 1/4 --json`,
+          ? `${command} --only ${renderFixShellArg(refused.join(','), '<step,step>')} --json`
+          : `${command} --only ${renderFixShellArg(kept.join(','), '<step,step>')} --shard 1/4 --json`,
+      command,
     });
   }
 }
@@ -116,12 +125,13 @@ export function shardFiles(
 }
 
 /** A timings file, or a refusal naming it — a CI job must not silently fall back to round-robin. */
-export async function readTimings(path: string): Promise<Timings> {
+export async function readTimings(path: string, command: string = GATE_COMMAND): Promise<Timings> {
   const file = Bun.file(path);
   if (!(await file.exists())) {
     throw new VerifyShardInvalidError({
       reason: `--timings ${path} does not exist`,
       fix: 'bun test --timings=timings.json --update-timings   # writes it, then commit or cache it',
+      command,
     });
   }
   let parsed: unknown;
@@ -139,6 +149,7 @@ export async function readTimings(path: string): Promise<Timings> {
     throw new VerifyShardInvalidError({
       reason: `--timings ${path} is not a JSON object of { "path": ms }`,
       fix: 'bun test --timings=timings.json --update-timings',
+      command,
     });
   }
   return parsed as Timings;

package/src/verify-step.ts

@@ -3,10 +3,12 @@
 // implementation can live beside the code it checks without importing the list.
 
 import { ERROR_DOCS_URL } from '@ultimat3/core';
+import type { CoverageMap } from './coverage-lcov';
 import type { ExecResult, Runner } from './exec';
 import { execOutput } from './exec';
-import type { Finding, ShardFacts } from './output';
+import type { Finding, ShardFacts, StepResult } from './output';
 import type { TestCounts } from './test-counts';
+import type { StepTimeouts } from './verify-deadline';
 
 /**
  * Every step of the gate, in cost order — cheapest and most informative first, and never a check
@@ -106,8 +108,29 @@ export interface VerifyContext {
    * name is accepted for the callers that narrow to one (`scripts/verify.ts`).
    */
   readonly only?: VerifyStepName | readonly VerifyStepName[];
+  /**
+   * Per-step deadlines in milliseconds that beat `x.verify.json`'s `stepTimeoutMs`, which beat the
+   * step class's declared number (`verify-deadline.ts`). A step past its deadline fails by name
+   * with `X_VERIFY_STEP_TIMEOUT` and every process it started is killed.
+   */
+  readonly stepTimeoutMs?: StepTimeouts;
+  /**
+   * Called as each step finishes, in the order they finish. `--json` prints nothing until the run
+   * ends, so a job cancelled mid-run left no trace of where it hung (#589): the command streams
+   * one line per step to stderr through this, and stdout stays the single document.
+   */
+  readonly onStep?: (step: StepResult) => void;
+  /**
+   * The gate as it was invoked HERE, for a `fix:` that has to run where it was raised: `x verify`
+   * when absent, `bun run verify` from the framework root's own entry — where `x verify` answers
+   * `X_NOT_IN_APP`.
+   */
+  readonly command?: string;
 }
 
+/** `ctx.command`'s default: the binary and the command, as an app types it. */
+export const GATE_COMMAND = 'x verify';
+
 export interface StepOutcome {
   readonly ok: boolean;
   readonly findings: readonly Finding[];
@@ -128,6 +151,24 @@ export interface StepOutcome {
    * NOT the same as a suite that ran nothing, which is a number the ratchet acts on.
    */
   readonly tests?: TestCounts;
+  /**
+   * What the `unit` suite covered of the app's own tree, when this run did NOT judge it: a
+   * `--shard` slice cannot hold a floor, so it hands its facts to `x verify merge`, which folds
+   * every shard's and judges once.
+   */
+  readonly coverage?: CoverageMap;
+  /**
+   * What the `unit` suite covered of the app's own tree when this run DID judge it. `--json` drops
+   * a green step's `output`, so the numbers ride in `data.coverage` where a reader can find them.
+   */
+  readonly measured?: CoverageNumbers;
+}
+
+/** The two percentages a judged run measured, and the source files they are over. */
+export interface CoverageNumbers {
+  readonly lines: number;
+  readonly funcs: number;
+  readonly files: number;
 }
 
 export interface VerifyStep {

package/src/verify-tests.ts

@@ -14,6 +14,8 @@ import type { TestType } from '@ultimat3/testing';
 import { TEST_TYPES } from '@ultimat3/testing';
 import { checkEvalBaselines, checkEvalCoverage, checkEvalRecording } from './app-evals';
 import { APP_CONFIG_FILE } from './app-root';
+import { judgeCoverage } from './coverage-floor';
+import { msg } from './messages';
 import { countsOf } from './test-counts';
 import { testEnvOverrides } from './test-dotenv';
 import type { TestFile } from './test-select';
@@ -21,7 +23,9 @@ import { discoverTests } from './test-select';
 import { machineLease } from './test-slots';
 import type { WorkerPlan } from './test-workers';
 import { availableCpus, SERIAL_TYPES, totalMemory, workerPlan } from './test-workers';
+import { runCovered } from './verify-coverage-run';
 import { withE2eApp } from './verify-e2e';
+import { readVerifyFloor } from './verify-floor';
 import { shardFiles } from './verify-shard';
 import type { StepOutcome, VerifyContext, VerifyStep } from './verify-step';
 import { fromExec, fromFindings } from './verify-step';
@@ -240,6 +244,21 @@ const runType = async (ctx: VerifyContext, type: TestType): Promise<StepOutcome>
     ctx.workers === undefined ? workerPlan(availableCpus(), totalMemory(), env) : undefined;
   const workers = ctx.workers ?? (plan as WorkerPlan).workers;
   const lease = plan === undefined ? undefined : machineLease(plan.workers, env);
+  const widthReason =
+    plan === undefined
+      ? `${String(Math.min(workers, files.length))} workers (--workers)`
+      : files.length < plan.workers
+        ? `${String(files.length)} of ${plan.reason}`
+        : plan.reason;
+  if (type === 'unit' && isApp(ctx.root)) {
+    return coveredUnit(ctx, {
+      files: files.map((file) => file.path),
+      workers,
+      widthReason,
+      shard,
+      lease,
+    });
+  }
   const outcome = await runParallel({
     root: ctx.root,
     runner: ctx.runner,
@@ -247,18 +266,71 @@ const runType = async (ctx: VerifyContext, type: TestType): Promise<StepOutcome>
     workers,
     type,
     isolate: ctx.isolate === true,
-    widthReason:
-      plan === undefined
-        ? `${String(Math.min(workers, files.length))} workers (--workers)`
-        : files.length < plan.workers
-          ? `${String(files.length)} of ${plan.reason}`
-          : plan.reason,
+    widthReason,
     ...(lease === undefined ? {} : { lease }),
     ...(ctx.env === undefined ? {} : { env: ctx.env }),
   });
   return shard === undefined ? outcome : { ...outcome, shard };
 };
 
+/**
+ * An APP's unit step: the suite, and what it covered of the app's own source held to the floor in
+ * `x.verify.json` (`coverage-floor.ts`). Only the unit suite counts — it is the one every run
+ * executes, and an opt-in suite cannot hold a floor a default run must meet. Only an app: the
+ * framework's packages are held to the same bar one process each, by `scripts/coverage-gate.ts`,
+ * because one run over a monorepo reads every package diluted by the ones it imports.
+ *
+ * A red suite is not judged — a slice that died wrote no lcov, and a coverage finding beside
+ * `X_TEST_FAILED` would send the reader to the wrong fix. A `--shard` slice is not judged either:
+ * it hands its facts to `x verify merge`, which folds every shard and judges once.
+ */
+const coveredUnit = async (
+  ctx: VerifyContext,
+  run: {
+    readonly files: readonly string[];
+    readonly workers: number;
+    readonly widthReason: string;
+    readonly shard: ReturnType<typeof shardFiles> | undefined;
+    readonly lease: ReturnType<typeof machineLease> | undefined;
+  },
+): Promise<StepOutcome> => {
+  const { coverage, ...outcome } = await runCovered({
+    root: ctx.root,
+    runner: ctx.runner,
+    files: run.files,
+    workers: run.workers,
+    isolate: ctx.isolate === true,
+    widthReason: run.widthReason,
+    ...(run.lease === undefined ? {} : { lease: run.lease }),
+    ...(ctx.env === undefined ? {} : { env: ctx.env }),
+  });
+  if (!outcome.ok) return run.shard === undefined ? outcome : { ...outcome, shard: run.shard };
+  if (run.shard !== undefined) {
+    return {
+      ...outcome,
+      shard: run.shard,
+      coverage,
+      output: msg('cli.verify.coverageDeferred'),
+    };
+  }
+  const verdict = await judgeCoverage(
+    ctx.root,
+    coverage,
+    (await readVerifyFloor(ctx.root))?.coverage,
+  );
+  return {
+    ...outcome,
+    ok: verdict.findings.length === 0,
+    findings: verdict.findings,
+    output: verdict.output,
+    measured: {
+      lines: verdict.measure.lines,
+      funcs: verdict.measure.funcs,
+      files: verdict.measure.files,
+    },
+  };
+};
+
 const isApp = (root: string): boolean => existsSync(join(root, APP_CONFIG_FILE));
 
 /**

package/src/workspace-checks.ts

@@ -10,10 +10,17 @@
 // public subject. `isReExportManifest` is the whole carve-out — one statement of logic in such a
 // file re-arms the ceiling on the same save, which is what keeps it from being a hole.
 
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ERROR_DOCS_URL, renderCauseValue } from '@ultimat3/core';
 import type { Finding } from './output';
+import {
+  entryFilesOf,
+  FIXTURE_SUFFIX,
+  fixtureReachFinding,
+  fixturesReachedFrom,
+  mayReachFixture,
+} from './publish-closure';
 import { isReExportManifest } from './reexport-manifest';
 import { eachSourceFile, isGenerated } from './source-files';
 import { checkRootReferences } from './tsconfig-references';
@@ -177,6 +184,16 @@ export function checkLockstep(
  */
 export const TEST_EXCLUSION = '!src/**/*.test.ts';
 
+/**
+ * The same rule for the other suffix test code is written under. A `-fixture.ts` is a harness a
+ * test imports — a fake driver, a recorded page, a scaffolded tree — and `src` sweeps it into the
+ * tarball exactly as it sweeps a `*.test.ts`: six packages shipped 18 of them, 2026-10.
+ */
+export const FIXTURE_EXCLUSION = '!src/**/*-fixture.ts';
+
+/** Every exclusion a published package's `files` carries, in the order it is written. */
+export const TEST_CODE_EXCLUSIONS: readonly string[] = [TEST_EXCLUSION, FIXTURE_EXCLUSION];
+
 export const missingPublishedFileFinding = (dir: string, entry: string): Finding => ({
   code: 'X_PACKAGE_SHAPE',
   cause: `packages/${dir}/package.json ships "${entry}" in "files", but packages/${dir}/${entry} does not exist`,
@@ -185,10 +202,10 @@ export const missingPublishedFileFinding = (dir: string, entry: string): Finding
   at: `packages/${dir}/package.json`,
 });
 
-export const publishesTestsFinding = (dir: string): Finding => ({
+export const publishesTestsFinding = (dir: string, exclusion: string): Finding => ({
   code: 'X_PACKAGE_SHAPE',
-  cause: `packages/${dir}/package.json does not exclude ${TEST_EXCLUSION} from "files"`,
-  fix: `add "${TEST_EXCLUSION}" to "files" in packages/${dir}/package.json, after "src"`,
+  cause: `packages/${dir}/package.json does not exclude ${exclusion} from "files"`,
+  fix: `add "${exclusion}" to "files" in packages/${dir}/package.json, after "src"`,
   docs: ERROR_DOCS_URL,
   at: `packages/${dir}/package.json`,
 });
@@ -222,7 +239,7 @@ export const buildArtifactsFinding = (dir: string, count: number): Finding => ({
 export const noFilesAllowlistFinding = (dir: string): Finding => ({
   code: 'X_PACKAGE_SHAPE',
   cause: `packages/${dir}/package.json publishes with no "files" allowlist, so the tarball carries whatever is in the directory`,
-  fix: `add "files": ["src", "${TEST_EXCLUSION}", "README.md", "LICENSE"] to packages/${dir}/package.json`,
+  fix: `add "files": ["src", ${TEST_CODE_EXCLUSIONS.map((entry) => `"${entry}"`).join(', ')}, "README.md", "LICENSE"] to packages/${dir}/package.json`,
   docs: ERROR_DOCS_URL,
   at: `packages/${dir}/package.json`,
 });
@@ -239,7 +256,7 @@ export const noFilesAllowlistFinding = (dir: string): Finding => ({
  * The second half is `src` sweeping in every `*.test.ts` beside it. Tests are the framework's own,
  * they run against a preloaded frozen clock and a sealed network, and a consumer's test runner
  * collecting them is a failure nobody asked for — 393 files, over half of `@ultimat3/cli`'s
- * tarball.
+ * tarball. A `*-fixture.ts` is the same code under its other suffix (`TEST_CODE_EXCLUSIONS`).
  *
  * Private packages are exempt: a generated app's `packages/*` never reach a registry, carry no
  * `files` and need no license of their own.
@@ -258,8 +275,10 @@ export function checkPublishShape(root: string, manifests: readonly ManifestFact
       if (existsSync(join(root, 'packages', manifest.dir, entry))) continue;
       findings.push(missingPublishedFileFinding(manifest.dir, entry));
     }
-    if (!manifest.files.includes(TEST_EXCLUSION)) {
-      findings.push(publishesTestsFinding(manifest.dir));
+    for (const exclusion of TEST_CODE_EXCLUSIONS) {
+      if (!manifest.files.includes(exclusion)) {
+        findings.push(publishesTestsFinding(manifest.dir, exclusion));
+      }
     }
   }
   return findings;
@@ -312,6 +331,28 @@ export interface PackageShapeOptions {
   readonly release?: string;
 }
 
+/**
+ * The fixtures a published package's entry points reach. A package with no fixture costs one glob
+ * — 19 of 31 — and one with some is read once: `mayReachFixture` answers from the text, and only a
+ * package it cannot clear pays for the import walk.
+ */
+async function fixtureReach(root: string, dir: string, manifest: unknown): Promise<Finding[]> {
+  const base = join(root, 'packages', dir);
+  const fixtures = new Bun.Glob(`src/**/*${FIXTURE_SUFFIX}`).scan({ cwd: base, absolute: false });
+  if ((await fixtures.next()).done === true) return [];
+  const entries = entryFilesOf(manifest);
+  // What the tarball carries of `src`, plus the fixtures themselves: a test's imports are not a
+  // consumer's, so no `*.test.ts` is read.
+  const sources = new Map<string, string>();
+  for await (const path of new Bun.Glob('src/**/*.{ts,tsx}').scan({ cwd: base, absolute: false })) {
+    if (!/\.test\.tsx?$/.test(path)) sources.set(path, readFileSync(join(base, path), 'utf8'));
+  }
+  if (!mayReachFixture(sources, entries)) return [];
+  return fixturesReachedFrom({ read: (path) => sources.get(path) }, entries).map((fixture) =>
+    fixtureReachFinding(dir, fixture, entries),
+  );
+}
+
 /** Every package ships the same contract files; a missing one is a build error, not a chore. */
 export async function checkPackageShape(
   root: string,
@@ -348,6 +389,7 @@ export async function checkPackageShape(
       findings.push(badVersionFinding(dir, version));
       continue;
     }
+    if (record.private !== true) findings.push(...(await fixtureReach(root, dir, manifest)));
     facts.push({
       dir,
       name: typeof record.name === 'string' ? record.name : `@ultimat3/${dir}`,