@ultimat3/cli 23.0.0 → 24.0.0

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-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';
@@ -124,7 +125,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 +136,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/build-errors.ts

@@ -1,54 +0,0 @@
-// The CLI's build and bundle refusals: an entry an app does not have, an island that will not
-// compile, a framework browser script that will not bundle. Split from `errors.ts` at its 500-line
-// ceiling; `errors.ts` re-exports every name, so no import site moves.
-
-import { UltimateError } from '@ultimat3/core';
-import { quoteArg } from './shell-quote';
-
-/**
- * A build target names an entry file the app does not have. `x build` refuses before it spawns the
- * builder: `bun build`'s own "module not found" says nothing about which file an Ultimate app is
- * supposed to own, and `docker build`'s says nothing about which target wanted it.
- */
-export class BuildEntryMissingError extends UltimateError {
-  constructor(input: { target: string; entry: string }) {
-    super({
-      code: 'X_BUILD_ENTRY_MISSING',
-      cause: `x build --target ${input.target} builds from ${input.entry}, and the app does not have it`,
-      fix: `x new scratch-app --dry-run --json   # its file list carries ${input.entry}; copy that file into this app`,
-    });
-  }
-}
-
-/**
- * A client entry would not compile. `X_BUILD_FAILED`, not a code of its own: an island is a bundle
- * entry point like any other, and the target's own logs are what says which line. The fix builds
- * exactly that one file, so the next message an author reads is the compiler's and not the CLI's.
- */
-export class IslandBuildFailedError extends UltimateError {
-  constructor(input: { file: string; logs: string }) {
-    super({
-      code: 'X_BUILD_FAILED',
-      cause: `${input.file} is an island entry point and would not bundle: ${input.logs}`,
-      fix: `bun build --target browser ${input.file}`,
-    });
-  }
-}
-
-/** Which framework script a page ships: the sync worker, the page boot, or the client router. */
-export type FrameworkScriptKind = 'sync worker' | 'page boot' | 'client router';
-
-/**
- * One of the page's framework scripts would not bundle. Same code as an island: "a browser entry
- * the framework builds did not build" is one condition, and the entry here is framework code, not
- * the app's — the cause names WHICH script, so the reader knows what the page is now missing.
- */
-export class FrameworkScriptBuildFailedError extends UltimateError {
-  constructor(input: { what: FrameworkScriptKind; entry: string; logs: string }) {
-    super({
-      code: 'X_BUILD_FAILED',
-      cause: `the ${input.what} (${input.entry}) would not bundle for the browser: ${input.logs}`,
-      fix: `bun build --target browser --format iife ${quoteArg(input.entry)}`,
-    });
-  }
-}

package/src/verify-errors.ts

@@ -1,58 +0,0 @@
-// The gate's sizing and CI-split refusals: a bad budget env var, an unsplittable `--shard`, and a
-// `x verify merge` part that is not a verify document. Split from errors.ts at its size ceiling.
-
-import { UltimateError } from '@ultimat3/core';
-
-/**
- * `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',
-    });
-  }
-}
-
-/**
- * The gate as an app types it. A refusal raised from another entry — `bun run verify` at the
- * framework root, where `x verify` answers `X_NOT_IN_APP` — passes its own spelling, so the
- * `fix:` runs where it was raised.
- */
-const GATE = 'x verify';
-
-/** `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;
-    super({
-      code: 'X_VERIFY_SHARD_INVALID',
-      cause: `${command} --shard: ${input.reason}`,
-      fix: input.fix ?? `${command} --only unit --shard 1/4 --json`,
-    });
-  }
-}
-
-/** A part handed to `x verify merge` that is not an `x verify --json` document. */
-export class VerifyMergeInputError extends UltimateError {
-  constructor(input: { file: string; reason: string; sourceError?: unknown; command?: string }) {
-    const command = input.command ?? GATE;
-    super({
-      code: 'X_VERIFY_MERGE_INPUT',
-      cause: `${command} merge: ${input.file} ${input.reason}`,
-      fix: `${command} --only unit --json > part.json   # one document per part, the last line of stdout`,
-      ...(input.sourceError === undefined ? {} : { sourceError: input.sourceError }),
-    });
-  }
-}