@ultimat3/cli 23.0.0 → 25.0.0

package/src/verify-part-step.ts

@@ -0,0 +1,98 @@
+// One step of an `x verify --json` part, read against the shape `mergeStep` relies on. It was a
+// cast past `name` and `ok`: `findings: [null]` merged green, and a step with no `durationMs`
+// reached `Math.max` as `undefined` — a part a CI job hand-edited, or truncated, was believed.
+
+import type { Finding } from './output';
+import type { TestCounts } from './test-counts';
+
+export interface PartStep {
+  readonly name: string;
+  readonly ok: boolean;
+  readonly durationMs: number;
+  readonly skipped: boolean;
+  readonly findings: readonly Finding[];
+  readonly workers?: number;
+  readonly tests?: TestCounts;
+  readonly output?: string;
+  readonly warnings?: readonly string[];
+  readonly shard?: {
+    readonly index: number;
+    readonly total: number;
+    readonly corpusHash: string;
+    readonly files: readonly string[];
+  };
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const isCount = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isInteger(value) && value >= 0;
+
+/** What every finding is: code, cause and fix as strings. Optional fields ride along as written. */
+export const isFinding = (value: unknown): value is Finding =>
+  isRecord(value) &&
+  typeof value['code'] === 'string' &&
+  typeof value['cause'] === 'string' &&
+  typeof value['fix'] === 'string';
+
+const isTests = (value: unknown): value is TestCounts =>
+  isRecord(value) &&
+  isCount(value['ran']) &&
+  isCount(value['skipped']) &&
+  (value['errors'] === undefined || isCount(value['errors']));
+
+const isTextList = (value: unknown): value is readonly string[] =>
+  Array.isArray(value) && value.every((line) => typeof line === 'string');
+
+const isShard = (value: unknown): value is NonNullable<PartStep['shard']> =>
+  isRecord(value) &&
+  isCount(value['index']) &&
+  isCount(value['total']) &&
+  typeof value['corpusHash'] === 'string' &&
+  Array.isArray(value['files']) &&
+  value['files'].every((file) => typeof file === 'string');
+
+/** The step, or the reason it is not one — phrased to follow "holds a step …". */
+export function readPartStep(raw: unknown): PartStep | string {
+  if (!isRecord(raw) || typeof raw['name'] !== 'string' || typeof raw['ok'] !== 'boolean') {
+    return 'holds a step without a name and ok';
+  }
+  const name = raw['name'];
+  const durationMs = raw['durationMs'];
+  if (typeof durationMs !== 'number' || !Number.isFinite(durationMs) || durationMs < 0) {
+    return `holds step "${name}" without a durationMs in milliseconds`;
+  }
+  const findings = raw['findings'];
+  if (!Array.isArray(findings) || !findings.every(isFinding)) {
+    return `holds step "${name}" whose findings are not each a code, a cause and a fix`;
+  }
+  const { tests, shard, output, workers, skipped, warnings } = raw;
+  if (tests !== undefined && !isTests(tests)) {
+    return `holds step "${name}" whose tests are not counts`;
+  }
+  if (shard !== undefined && !isShard(shard)) {
+    return `holds step "${name}" whose shard is not an index, a total, a corpusHash and its files`;
+  }
+  if (output !== undefined && typeof output !== 'string') {
+    return `holds step "${name}" whose output is not text`;
+  }
+  if (warnings !== undefined && !isTextList(warnings)) {
+    return `holds step "${name}" whose warnings are not a list of text`;
+  }
+  if (workers !== undefined && !isCount(workers)) {
+    return `holds step "${name}" whose workers is not a count`;
+  }
+  return {
+    name,
+    ok: raw['ok'],
+    durationMs,
+    skipped: skipped === true,
+    findings,
+    ...(workers === undefined ? {} : { workers }),
+    ...(tests === undefined ? {} : { tests }),
+    ...(output === undefined ? {} : { output }),
+    ...(warnings === undefined ? {} : { warnings }),
+    ...(shard === undefined ? {} : { shard }),
+  };
+}

package/src/verify-role-load-probe.ts

@@ -3,11 +3,22 @@
 // those registered that the worker's process did not hold. Run by hand, it is the same answer.
 
 import { scanAppModules } from './app-load';
+import type { RelativeHost } from './posix-path';
+import { posixRelative } from './posix-path';
 import { scanBackground } from './role-load';
 import type { MissingRegistration } from './verify-role-load';
 import { PROBE_MARKER, registeredSince, registrations } from './verify-role-load';
 import { writeLine } from './write-line';
 
+/**
+ * The app-root-relative POSIX key a scanned module is held under — the form `scanBackground`'s
+ * `files` already are. A `${root}/` prefix strip matched nothing on Windows (`D:\…\app\apps\…`),
+ * so every module the worker DID import was blamed as missing. `host` is for a test only.
+ */
+export function moduleKey(root: string, absolute: string, host?: RelativeHost): string {
+  return posixRelative(root, absolute, host);
+}
+
 /**
  * What importing each module the worker load left out registered, by module — `[]` when the whole
  * scan reported a module that would not import. Exported so a test calls it in its own process;
@@ -31,12 +42,11 @@ export async function probeRoleLoad(root: string): Promise<readonly MissingRegis
 
   // The whole app, in the scan's own order. `include` is asked before each import, so the look it
   // takes is at what the PREVIOUS module added; a module the worker already imported adds nothing.
-  const prefix = root.endsWith('/') ? root : `${root}/`;
   const whole = await scanAppModules(root, {
     track: false,
     include: (absolute) => {
       attribute();
-      const file = absolute.startsWith(prefix) ? absolute.slice(prefix.length) : absolute;
+      const file = moduleKey(root, absolute);
       current = imported.has(file) ? undefined : file;
       return true;
     },

package/src/verify-role-load.ts

@@ -5,7 +5,7 @@
 // manifest; this is the build error for everything else a job reads by name.
 
 // why: Bun ships no path API; the fix names the import relative to the API index.
-import { dirname, join, relative } from 'node:path';
+import { dirname, join } from 'node:path';
 import { ERROR_DOCS_URL, registeredServiceNames, singleLine } from '@ultimat3/core';
 import { entityNames } from '@ultimat3/entity';
 import { catalogDeclarationCount } from '@ultimat3/i18n';
@@ -16,6 +16,8 @@ import { definedStorage } from '@ultimat3/storage';
 import { API_INDEX } from './app-root';
 import type { Runner } from './exec';
 import type { Finding } from './output';
+import type { RelativeHost } from './posix-path';
+import { posixRelative } from './posix-path';
 import { quoteArg } from './shell-quote';
 
 /** One thing a process registered, as a job would ask for it: by kind and by name. */
@@ -79,9 +81,12 @@ export function registeredSince(
   return after.filter((one) => !had.has(keyOf(one)));
 }
 
-/** The import the API index is missing, as it would be written there. */
-function specifierFor(module: string): string {
-  const from = relative(dirname(API_INDEX), module).replace(/\.[jt]sx?$/, '');
+/**
+ * The import the API index is missing, as it would be written there — POSIX on every host: a `\`
+ * pasted from a Windows run is an import no Linux teammate resolves. `host` is for a test only.
+ */
+export function specifierFor(module: string, host?: RelativeHost): string {
+  const from = posixRelative(dirname(API_INDEX), module, host).replace(/\.[jt]sx?$/, '');
   return from.startsWith('.') ? from : `./${from}`;
 }
 

package/src/verify-run.ts

@@ -7,14 +7,22 @@ import type { CoverageMap } from './coverage-lcov';
 import { encodeCoverage } from './coverage-lcov';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue, StepResult } from './output';
-import { guardStep, raceDeadline, stepTimeoutFinding, stepTimeoutMs } from './verify-deadline';
+import type { StepGuard } from './verify-deadline';
+import { guardStep, raceDeadline, stepTimeoutMs } from './verify-deadline';
 import {
   floorRequires,
   readVerifyFloor,
   skippedSuiteFinding,
   vanishedSuiteFinding,
 } from './verify-floor';
-import type { CoverageNumbers, StepOutcome, VerifyContext, VerifyStep } from './verify-step';
+import { stalledOutput, stepTimeoutFinding } from './verify-stalled';
+import type {
+  CoverageNumbers,
+  StepOutcome,
+  VerifyContext,
+  VerifyStep,
+  VerifyStepName,
+} from './verify-step';
 import { GATE_COMMAND } from './verify-step';
 
 /**
@@ -172,7 +180,7 @@ export function verifySummary(input: {
  * `manifest` joined them 2026-09-23: it compares committed files against the code and writes
  * nothing, and at the repo root its host checks are ~20 whole-tree reads that sat alone at the end.
  */
-export const BESIDE_SERIAL_SUITES: ReadonlySet<string> = new Set([
+export const BESIDE_SERIAL_SUITES: ReadonlySet<VerifyStepName> = new Set<VerifyStepName>([
   'lint',
   'boundaries',
   'filesize',
@@ -182,7 +190,7 @@ export const BESIDE_SERIAL_SUITES: ReadonlySet<string> = new Set([
 ]);
 
 /** The consecutive run of steps the static group overlaps, in the order `VERIFY_STEP_NAMES` holds. */
-export const SERIAL_SUITES: readonly string[] = ['live', 'job', 'e2e', 'eval'];
+export const SERIAL_SUITES: readonly VerifyStepName[] = ['live', 'job', 'e2e', 'eval'];
 
 async function runStep(
   step: VerifyStep,
@@ -243,10 +251,7 @@ async function runStep(
     limit,
   );
   const outcome: StepOutcome = raced.timedOut
-    ? {
-        ok: false,
-        findings: [stepTimeoutFinding(step.name, limit, await guard.expire(), command)],
-      }
+    ? await expired(step.name, limit, guard, 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.
@@ -272,6 +277,9 @@ async function runStep(
       skipped: nothingRan && !required,
       findings: [...outcome.findings, ...vanished],
       ...(outcome.output === undefined ? {} : { output: outcome.output }),
+      ...(outcome.warnings === undefined || outcome.warnings.length === 0
+        ? {}
+        : { warnings: outcome.warnings }),
       ...(outcome.workers === undefined ? {} : { workers: outcome.workers }),
       ...(outcome.widthReason === undefined ? {} : { widthReason: outcome.widthReason }),
       ...(outcome.shard === undefined ? {} : { shard: outcome.shard }),
@@ -282,6 +290,22 @@ async function runStep(
   };
 }
 
+/** The timed-out step's outcome: the finding naming what was in flight, over what it last printed. */
+async function expired(
+  step: VerifyStepName,
+  limit: number,
+  guard: StepGuard,
+  command: string,
+): Promise<StepOutcome> {
+  const expiry = await guard.expire();
+  const output = stalledOutput(expiry);
+  return {
+    ok: false,
+    findings: [stepTimeoutFinding(step, limit, expiry, command)],
+    ...(output === undefined ? {} : { output }),
+  };
+}
+
 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

package/src/verify-shard.ts

@@ -5,13 +5,24 @@
 // of the machine, the clock or the order a glob yielded — so job 3 of 8 is the same files on every
 // runner, and a failing shard reproduces locally with the same flags.
 
-import { renderFixShellArg } from '@ultimat3/core';
+import { renderFixShellArg, UltimateError } from '@ultimat3/core';
 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';
 
+/** `x verify --shard` asked for a split the gate cannot make. */
+export class VerifyShardInvalidError extends UltimateError {
+  constructor(input: { reason: string; fix?: string; command?: string }) {
+    const command = input.command ?? GATE_COMMAND;
+    super({
+      code: 'X_VERIFY_SHARD_INVALID',
+      cause: `${command} --shard: ${input.reason}`,
+      fix: input.fix ?? `${command} --only unit --shard 1/4 --json`,
+    });
+  }
+}
+
 /** 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'];
 

package/src/verify-stalled.ts

@@ -0,0 +1,152 @@
+// What a step was doing when its deadline passed, as the `X_VERIFY_STEP_TIMEOUT` finding. A hung
+// test file used to cost eight minutes and report "2 process(es) were killed" — nothing a reader
+// could run. The finding now names the file bun says a killed worker held, and its `fix:` runs it.
+
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import type { Finding } from './output';
+import { quoteArg } from './shell-quote';
+import type { InFlightRun, StepExpiry } from './verify-deadline';
+import { STEP_TIMEOUT_FIELD } from './verify-deadline';
+import type { VerifyStepName } from './verify-step';
+
+/**
+ * One `bun test` the step was waiting on, read against what it printed as it was stopped. A `type`,
+ * like the meta that carries it: an interface is not assignable to `Finding.meta`'s JSON record.
+ */
+export type StalledRun = {
+  /** The argv without its file list: `bun test --parallel=3`. */
+  readonly command: string;
+  /** Files the run was handed; 0 for a serial run, which selects by filter. */
+  readonly files: number;
+  /** `--parallel`'s width, and 1 for a serial run. */
+  readonly workers: number;
+  /** The files that were still running, as bun named them. Empty when it named none. */
+  readonly stuck: readonly string[];
+};
+
+/** `X_VERIFY_STEP_TIMEOUT`'s `meta`. A `type`: an interface is not assignable to `Finding.meta`. */
+export type StepTimeoutMeta = {
+  readonly step: string;
+  readonly deadlineMs: number;
+  readonly killed: readonly { readonly pid: number; readonly command: string }[];
+  readonly inFlight: readonly StalledRun[];
+};
+
+/**
+ * What a `--parallel` coordinator prints for the file a killed worker was holding. The guard kills
+ * the workers first for exactly this line (`verify-deadline.ts`); it is bun's own statement of
+ * what was in flight, and it is printed in every reporter mode.
+ */
+const CRASHED = /^\s*✗ (.+) \(worker crashed: SIG[A-Z0-9]+\)$/;
+
+/** Bun's per-file header — `::group::`-prefixed on GitHub Actions. A serial run prints it at START. */
+const FILE_LINE = /^(?:::group::)?(\S.*\.test\.[cm]?[jt]sx?):$/;
+
+const PARALLEL = '--parallel=';
+
+const bare = (path: string): string => (path.startsWith('./') ? path.slice(2) : path);
+
+/**
+ * A parallel run names its stuck files itself, one crash line per killed worker. A serial run has
+ * no worker to kill: it prints a file's header when the file STARTS, so the stuck file is the last
+ * one printed — unless a `(fail)` follows it, which is also all a failures-only reporter ever
+ * prints, and then nothing is claimed.
+ */
+export function stalledRun(run: InFlightRun): StalledRun | undefined {
+  const [program, verb, ...rest] = run.command;
+  if (program !== 'bun' || verb !== 'test' || run.output === undefined) return undefined;
+  const lines = run.output.split('\n').map((line) => line.trimEnd());
+  const width = rest.find((arg) => arg.startsWith(PARALLEL));
+  const flags = rest.filter((arg) => arg.startsWith('--') && !arg.startsWith('--timings'));
+  const command = ['bun', 'test', ...flags].join(' ');
+  if (width === undefined) {
+    const last = lines.findLastIndex((line) => FILE_LINE.test(line));
+    const started = last < 0 ? undefined : FILE_LINE.exec(lines[last] ?? '')?.[1];
+    const failed = lines.slice(last + 1).some((line) => line.startsWith('(fail)'));
+    return {
+      command,
+      files: 0,
+      workers: 1,
+      stuck: started === undefined || failed ? [] : [started],
+    };
+  }
+  const files = rest.filter((arg) => !arg.startsWith('--'));
+  const crashed = lines.flatMap((line) => {
+    const path = CRASHED.exec(line)?.[1];
+    // As the caller handed it in, so the `fix:` reruns the very argument the run was given.
+    return path === undefined ? [] : [files.find((file) => bare(file) === bare(path)) ?? path];
+  });
+  return {
+    command,
+    files: files.length,
+    workers: Math.max(1, Number(width.slice(PARALLEL.length)) || 1),
+    stuck: [...new Set(crashed)],
+  };
+}
+
+/** How many paths a `cause:` spells out — the rest are in `meta`. */
+const NAMED_IN_CAUSE = 5;
+
+const OUTPUT_TAIL_CHARS = 4_000;
+
+/** The last thing each killed run printed: what a reader of a red step looks at first. */
+export function stalledOutput(expiry: StepExpiry): string | undefined {
+  const text = expiry.inFlight
+    .flatMap((run) => (run.output === undefined || run.output === '' ? [] : [run.output]))
+    .join('\n');
+  if (text === '') return undefined;
+  return text.length > OUTPUT_TAIL_CHARS ? `…${text.slice(-OUTPUT_TAIL_CHARS)}` : text;
+}
+
+const inFlightClause = (runs: readonly StalledRun[], expiry: StepExpiry): string => {
+  const files = runs.flatMap((run) => run.stuck);
+  const named = runs.find((run) => run.stuck.length > 0);
+  if (named !== undefined) {
+    const shown = files.slice(0, NAMED_IN_CAUSE).join(', ');
+    const more = files.length > NAMED_IN_CAUSE ? `, +${String(files.length - NAMED_IN_CAUSE)}` : '';
+    return `; still running when it was stopped: ${shown}${more} (${named.command})`;
+  }
+  const waiting = expiry.inFlight[0];
+  if (waiting === undefined) return '';
+  return runs[0] === undefined
+    ? `; it was waiting on: ${waiting.command.slice(0, 4).join(' ')}`
+    : `; its running "${runs[0].command}" named no file still in flight, so the run itself did not exit`;
+};
+
+/**
+ * A step that ran past its deadline, on that step's own line. `command` is the gate as it was
+ * invoked here (`x verify`, or `bun run verify` at the framework root), so the fix runs where the
+ * finding was raised. With a stuck file named, the fix runs THAT file; the step's own rerun and
+ * the `stepTimeoutMs` edit ride behind it.
+ */
+export const stepTimeoutFinding = (
+  step: VerifyStepName,
+  ms: number,
+  expiry: StepExpiry,
+  command: string,
+): Finding => {
+  const runs = expiry.inFlight.flatMap((run) => stalledRun(run) ?? []);
+  const stuck = runs.flatMap((run) => run.stuck);
+  const rerun = `${command} --only ${step} --json`;
+  const longer = `if it legitimately needs longer, edit x.verify.json — add "${STEP_TIMEOUT_FIELD}": { "${step}": <milliseconds> }`;
+  // Each path through `quoteArg`, one argv word apiece: a test file's name is data from the disk,
+  // and this line is pasted into a shell.
+  const alone = ['bun', 'test', ...stuck.map(quoteArg)].join(' ');
+  const meta: StepTimeoutMeta = {
+    step,
+    deadlineMs: ms,
+    killed: expiry.killed.map((one) => ({ pid: one.pid, command: one.command })),
+    inFlight: runs,
+  };
+  return {
+    code: 'X_VERIFY_STEP_TIMEOUT',
+    cause: `step "${step}" did not finish within its ${String(ms)} ms deadline, so it was stopped and ${String(expiry.killed.length)} process(es) it had started were killed${inFlightClause(runs, expiry)}`,
+    fix:
+      stuck.length > 0
+        ? `${alone}   # what had not finished, alone; the whole step: ${rerun}; ${longer}`
+        : `${rerun}   # reproduce it alone; ${longer}`,
+    docs: ERROR_DOCS_URL,
+    ...(stuck[0] === undefined ? {} : { at: stuck[0] }),
+    meta,
+  };
+};

package/src/verify-step.ts

@@ -135,6 +135,8 @@ export interface StepOutcome {
   readonly ok: boolean;
   readonly findings: readonly Finding[];
   readonly output?: string;
+  /** Advice that does not fail the step; carried on a pass too (`StepResult.warnings`). */
+  readonly warnings?: readonly string[];
   /**
    * Processes this step actually used. `1` is a step that ran serially, and a reader has to be
    * able to tell "serial because nothing could isolate it" from "parallel and fast" without

package/src/verify-test-run.ts

@@ -4,13 +4,14 @@
 
 // why: Bun ships no path-join primitive; the timings cache lives under the run's root.
 import { join } from 'node:path';
+import { ISOLATED_ENV } from '@ultimat3/testing';
 import type { Runner } from './exec';
 import type { Finding } from './output';
 import { runBatches, testBatches } from './test-batches';
 import { countsOf } from './test-counts';
 import { testEnvOverrides } from './test-dotenv';
 import type { TestFile } from './test-select';
-import { failureOf, ISOLATED_TEST_ENV, TEST_TIMINGS_FILE, testArgs } from './test-shards';
+import { failureOf, TEST_TIMINGS_FILE, testArgs } from './test-shards';
 import { BATCH_FILES_PER_WORKER, SHARED_BATCH_FILES_PER_WORKER } from './test-workers';
 import type { StepOutcome } from './verify-step';
 // Type-only, so nothing here evaluates verify-tests.ts and the two files cannot form a cycle.
@@ -53,7 +54,7 @@ export async function runParallel(options: ParallelRunOptions): Promise<StepOutc
   const workers = Math.max(1, Math.min(Math.trunc(options.workers), files.length || 1));
   const envOverrides = {
     ...testEnvOverrides(options.root, options.env ?? Bun.env),
-    ...(options.isolate === true ? { [ISOLATED_TEST_ENV]: '1' } : {}),
+    ...(options.isolate === true ? { [ISOLATED_ENV]: '1' } : {}),
   };
   // Batched exactly as `x test` batches the same selection at the same width, so the gate's
   // `fix:` line — `x test <type> --workers N` — reruns the very processes that failed.

package/src/verify-tests.ts

@@ -18,6 +18,7 @@ import { judgeCoverage } from './coverage-floor';
 import { msg } from './messages';
 import { countsOf } from './test-counts';
 import { testEnvOverrides } from './test-dotenv';
+import { IGNORED_TEST_PATTERNS } from './test-ignores';
 import type { TestFile } from './test-select';
 import { discoverTests } from './test-select';
 import { machineLease } from './test-slots';
@@ -39,7 +40,6 @@ import { runParallel } from './verify-test-run';
  * and `@ultimat3/testing` is already a runtime dependency of this package.
  */
 export type { TestType } from '@ultimat3/testing';
-export { TEST_TYPES } from '@ultimat3/testing';
 
 type TypedTest = Exclude<TestType, 'unit'>;
 
@@ -124,7 +124,9 @@ const isSerial = (type: TestType): boolean => SERIAL_TYPES.includes(type);
  * Build output, and nested projects that carry their own `x verify`. `examples/**` and
  * `dummy/**` are the second kind: each holds a whole app gated by its own run of this same step
  * list, so collecting them here would report one app failure on two different gates. The patterns
- * are relative to the run's root, so this excludes nothing when the app itself is the root.
+ * are relative to the run's root, so this excludes nothing when the app itself is the root. The
+ * policy — which directories, and which are anchored at the root — is `test-ignores.ts`'s, the same
+ * one `discoverTests` filters the parallel steps by; this is its glob projection.
  *
  * `dummy/**` was added after the framework gate started running a demo app's tests and disagreeing
  * with `bun run test` — which already excluded it — for no reason a reader could see.
@@ -133,7 +135,7 @@ const isSerial = (type: TestType): boolean => SERIAL_TYPES.includes(type);
  * those apps and blocks on a per-app ratchet. Until 2026-08 that was only true of `examples/**`,
  * and `dummy/social-media-clone` was excluded by this list and gated by nothing.
  */
-const NEVER_A_TEST = ['**/dist/**', '**/build/**', '**/examples/**', '**/dummy/**'];
+const NEVER_A_TEST = IGNORED_TEST_PATTERNS;
 
 const ignoreFlags = (patterns: readonly string[]): readonly string[] =>
   patterns.map((pattern) => `--path-ignore-patterns=${pattern}`);

package/src/worker-bundle.ts

@@ -7,7 +7,7 @@
 // why: Bun ships no path API; the entry is resolved to a file and named in the cause.
 import { dirname, join, relative } from 'node:path';
 import type { Route, UltimateRequest } from '@ultimat3/http';
-import { applyCacheHeaders, json } from '@ultimat3/http';
+import { applyCacheHeaders, jsonResponse } from '@ultimat3/http';
 import { FrameworkScriptBuildFailedError, type FrameworkScriptKind } from './errors';
 import { describeBuildError, graphHash, stripDebugId } from './island-identity';
 
@@ -198,7 +198,7 @@ function scriptRoute(
     handler: (request: UltimateRequest): Response => {
       const script = source();
       if (script === undefined || script.url !== request.pathname) {
-        return json(
+        return jsonResponse(
           {
             ok: false,
             error: {

package/src/workspace-checks.ts

@@ -14,6 +14,8 @@ 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 { pathSegments } from './path-segments';
+import { toPosix } from './posix-path';
 import {
   entryFilesOf,
   FIXTURE_SUFFIX,
@@ -23,6 +25,8 @@ import {
 } from './publish-closure';
 import { isReExportManifest } from './reexport-manifest';
 import { eachSourceFile, isGenerated } from './source-files';
+import type { ShippedPackage } from './test-only-shipped';
+import { checkTestOnlyShipped, entryPatternsOf } from './test-only-shipped';
 import { checkRootReferences } from './tsconfig-references';
 
 export const LINE_CEILING = 500;
@@ -53,15 +57,41 @@ export const countLines = (text: string): number =>
  * statement of logic in it is not, and only reading tells them apart.
  */
 export async function checkFileSizes(root: string): Promise<readonly Finding[]> {
+  return (await fileSizeReport(root)).findings;
+}
+
+/**
+ * Where a split gets planned rather than forced. Seven files once sat at exactly 500 lines,
+ * trimmed to the ceiling instead of split: a band that lists a file at 450 makes the split a
+ * decision taken with room to spare. Never a finding — a warning that fails the step is a ceiling.
+ */
+export const WARN_BAND = 450;
+
+/** A file in the band: at or over `WARN_BAND`, at or under the ceiling. */
+export interface FileSizeWarning {
+  readonly path: string;
+  readonly lines: number;
+  readonly ceiling: number;
+}
+
+export interface FileSizeReport {
+  readonly findings: readonly Finding[];
+  readonly warnings: readonly FileSizeWarning[];
+}
+
+/** The ceiling's findings and the band's warnings, from one read of every file. */
+export async function fileSizeReport(root: string): Promise<FileSizeReport> {
   const findings: Finding[] = [];
+  const warnings: FileSizeWarning[] = [];
   for await (const path of eachSourceFile(root)) {
     if (isGenerated(path)) continue;
     const source = await Bun.file(join(root, path)).text();
     const lines = countLines(source);
-    if (lines <= LINE_CEILING || isReExportManifest(source)) continue;
-    findings.push(tooLongFinding(path, lines));
+    if (lines < WARN_BAND || isReExportManifest(source)) continue;
+    if (lines > LINE_CEILING) findings.push(tooLongFinding(path, lines));
+    else warnings.push({ path, lines, ceiling: LINE_CEILING });
   }
-  return findings;
+  return { findings, warnings };
 }
 
 export const missingFileFinding = (dir: string, file: string, scaffolder: boolean): Finding => ({
@@ -307,13 +337,20 @@ export function frameworkDepsOf(manifest: unknown): ManifestFacts['frameworkDeps
   });
 }
 
+/**
+ * `packages/<dir>/package.json` → `<dir>`, from a glob answer in the host's separator. Split on `/`
+ * alone, Windows' `packages\db\package.json` named no directory, so an app's `package-shape` found
+ * no workspace and its floor reported `X_VERIFY_SUITE_VANISHED` on a scaffold fresh from `x new`.
+ */
+export const workspaceDirOf = (globbed: string): string | undefined => pathSegments(globbed)[1];
+
 export async function workspacePackages(root: string): Promise<readonly string[]> {
   const dirs: string[] = [];
   for await (const path of new Bun.Glob('packages/*/package.json').scan({
     cwd: root,
     absolute: false,
   })) {
-    const dir = path.split('/')[1];
+    const dir = workspaceDirOf(path);
     if (dir !== undefined) dirs.push(dir);
   }
   return dirs.sort();
@@ -345,7 +382,10 @@ async function fixtureReach(root: string, dir: string, manifest: unknown): Promi
   // 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'));
+    // Keyed POSIX: `entryFilesOf` and every import the walk resolves are, on every host.
+    if (!/\.test\.tsx?$/.test(path)) {
+      sources.set(toPosix(path), readFileSync(join(base, path), 'utf8'));
+    }
   }
   if (!mayReachFixture(sources, entries)) return [];
   return fixturesReachedFrom({ read: (path) => sources.get(path) }, entries).map((fixture) =>
@@ -361,6 +401,7 @@ export async function checkPackageShape(
   const scaffolder = existsSync(join(root, 'scripts', 'new-package.ts'));
   const findings: Finding[] = [];
   const facts: ManifestFacts[] = [];
+  const shipped: ShippedPackage[] = [];
   const allowlisted = new Set(ARTIFACT_ALLOWLIST);
   for (const dir of await workspacePackages(root)) {
     for (const file of PACKAGE_FILES) {
@@ -373,7 +414,7 @@ export async function checkPackageShape(
       cwd: join(root, 'packages', dir),
       absolute: false,
     })) {
-      if (!allowlisted.has(join('packages', dir, path))) artifacts.push(path);
+      if (!allowlisted.has(toPosix(join('packages', dir, path)))) artifacts.push(path);
     }
     if (artifacts.length > 0) {
       findings.push(buildArtifactsFinding(dir, artifacts.length));
@@ -389,7 +430,10 @@ export async function checkPackageShape(
       findings.push(badVersionFinding(dir, version));
       continue;
     }
-    if (record.private !== true) findings.push(...(await fixtureReach(root, dir, manifest)));
+    if (record.private !== true) {
+      findings.push(...(await fixtureReach(root, dir, manifest)));
+      shipped.push({ dir, entries: entryPatternsOf(manifest) });
+    }
     facts.push({
       dir,
       name: typeof record.name === 'string' ? record.name : `@ultimat3/${dir}`,
@@ -403,6 +447,8 @@ export async function checkPackageShape(
     ...findings,
     ...checkLockstep(facts, options.release),
     ...checkPublishShape(root, facts),
+    // The other way test code ships: a module only tests import, under a name `files` keeps.
+    ...(await checkTestOnlyShipped(root, shipped)),
     // Nothing enforced that a workspace joins the root build graph, and `scripts/new-package.ts`
     // never added one — so a package could ship, be imported, and be typechecked by nothing. It
     // rides on this step because it is this step's own question: what does a workspace owe the