@ultimat3/cli 1.2.0 → 3.0.0

package/src/templates/slice-foundation.ts

@@ -0,0 +1,88 @@
+// The modules a feature slice owns — `entity.ts`, `repo.ts`, `policy.ts`, `errors.ts` — composed by
+// every generator that imports one. `x g resource` already wrote them by composing `entityFiles` +
+// `policyFiles`; the five generators that write *into* a slice imported the same files and wrote
+// none of them, so each emitted TS2307 in any slice a resource had not been run in first.
+
+import type { FeatureTarget } from './entity';
+import { entityFiles } from './entity';
+import type { GeneratedFile, NameSet } from './naming';
+import { names } from './naming';
+import { policyFiles } from './policy';
+
+/**
+ * Which slice modules a generator's own source imports. Named per generator rather than emitted as
+ * one fixed set: a job imports `../repo` and evaluates no policy, and a generated `policy.ts` it
+ * never reads is a file an author has to read before deleting.
+ *
+ * `'entity'` is the pair, not the file: `repo.ts` imports `./entity` for its row type, so emitting
+ * one without the other moves the unresolved import rather than closing it.
+ */
+export type SliceModule = 'entity' | 'policy' | 'errors';
+
+/** The feature's own code, derived once. The `docs:` URL used to be the literal
+ * `.../X_NOT_FOUND` beside a `code:` of `X_INVOICE_NOT_FOUND`, so following the link from a real
+ * failure landed on a different code's page — the same interpolation `error-codes.ts`'s `docsFor`
+ * already does for every framework code. */
+const notFoundCode = (feature: NameSet): string =>
+  `X_${feature.kebab.toUpperCase().split('-').join('_')}_NOT_FOUND`;
+
+/**
+ * The emitted `fix:` cites `x queries list`, and which command it cites is the whole point: a
+ * scaffolded app runs the same `errors` step this repo does, so a fix naming a command the build
+ * does not ship writes a fresh X_ERROR_FIX_INVALID into the app on every `x g action`. It cited
+ * `x db studio`, which is in `PLANNED_SUBCOMMANDS` and exits X_NOT_IMPLEMENTED — the generator was
+ * breaking the one rule it exists to demonstrate. `x queries list` ships, and a read is where a
+ * caller gets an id that exists.
+ */
+const errorsSource = (feature: NameSet): string => {
+  const errorCode = notFoundCode(feature);
+  return `// The ${feature.kebab} feature's X_* codes. Never throw a bare Error: an agent reading the failure
+// needs the code, the cause and the exact command that fixes it.
+
+import { UltimateError } from '@ultimat3/core';
+
+export class ${feature.pascal}NotFoundError extends UltimateError {
+  constructor(input: { id: string }) {
+    super({
+      code: '${errorCode}',
+      cause: \`no ${feature.kebab} with id \${input.id}\`,
+      fix: 'x queries list --json, then pass an id the ${feature.kebab} read returns',
+      docs: 'https://ultimate.dev/errors/${errorCode}',
+    });
+  }
+}
+`;
+};
+
+/**
+ * Re-tags a slice module as one the writer may skip. The byte-carrying variant is passed through
+ * untouched rather than cast: only the scaffolded app icon carries bytes and no slice module is a
+ * PNG, so a future one would be a visible hard write instead of a silent claim it was checked.
+ */
+const ifAbsent = (files: readonly GeneratedFile[]): readonly GeneratedFile[] =>
+  files.map((file) =>
+    typeof file.contents === 'string'
+      ? { path: file.path, contents: file.contents, merge: 'if-absent' as const }
+      : file,
+  );
+
+/**
+ * The slice modules `needs` names, in the order a reader meets them: the table, then the authz,
+ * then the failures. Named from `target.feature` and never from the primitive's own name — the
+ * generated `import { InvoiceNotFoundError } from '../errors'` is the feature's type, not
+ * `send-invoice`'s.
+ */
+export function sliceFoundation(
+  target: FeatureTarget,
+  needs: readonly SliceModule[],
+): readonly GeneratedFile[] {
+  const feature = names(target.feature);
+  const dir = `${target.surfaceDir}/${target.feature}`;
+  return ifAbsent([
+    ...(needs.includes('entity') ? entityFiles(target.feature, target) : []),
+    ...(needs.includes('policy') ? policyFiles(target.feature, target) : []),
+    ...(needs.includes('errors')
+      ? [{ path: `${dir}/errors.ts`, contents: errorsSource(feature) }]
+      : []),
+  ]);
+}

package/src/templates/wrap.ts

@@ -0,0 +1,95 @@
+// Emitting a line the way Biome would print it. A template cannot run a formatter, so generated
+// source is written pre-formatted — and a FIXED shape is wrong for one name length or the other:
+// Biome joins a short wrapped call back onto one line and breaks a long joined one, and the app's
+// own `lint` step fails on whichever half the template guessed wrong.
+
+/** The scaffold's own `biome.json` says `lineWidth: 100`, and this is the same number. */
+export const LINE_WIDTH = 100;
+
+/**
+ * `<open><a>, <b><close>` when it fits, one entry per line with a trailing comma when it does not.
+ * The one shape behind every generated argument list, array literal and parameter list — a second
+ * copy of this rule is how `x g entity credit-note-attachment` shipped a `$view([…])` line that the
+ * app's formatter rewrote on sight.
+ */
+export function wrapList(
+  indent: string,
+  open: string,
+  entries: readonly string[],
+  close: string,
+): string {
+  const joined = `${indent}${open}${entries.join(', ')}${close}`;
+  if (joined.length <= LINE_WIDTH) return joined;
+  const body = entries.map((entry) => `${indent}  ${entry},`).join('\n');
+  return `${indent}${open}\n${body}\n${indent}${close}`;
+}
+
+const isDigit = (char: string): boolean => char >= '0' && char <= '9';
+
+/** How many digits run from `at`. A run is compared as a number, so `b2` precedes `b10`. */
+const digitRun = (text: string, at: number): number => {
+  let end = at;
+  while (end < text.length && isDigit(text[end] ?? '')) end += 1;
+  return end - at;
+};
+
+/**
+ * Biome's own order for the names inside `{ … }`, measured against 2.5.8 rather than assumed —
+ * three behaviours, and no single-pass compare gives all three:
+ *
+ *   `{ post, PostView }`  → `{ PostView, post }`   upper first on a pure case tie
+ *   `{ Zeta, alpha }`     → `{ alpha, Zeta }`      but case is only ever the TIEBREAK
+ *   `{ b10, b2 }`         → `{ b2, b10 }`          a digit run compares as a number
+ *
+ * The first two together are why folding to lower case and comparing is wrong: `post` is a prefix
+ * of `postview`, so a folded compare puts `post` first and Biome does not.
+ */
+const compareSpecifiers = (left: string, right: string): number => {
+  let a = 0;
+  let b = 0;
+  while (a < left.length && b < right.length) {
+    const runA = digitRun(left, a);
+    const runB = digitRun(right, b);
+    if (runA > 0 && runB > 0) {
+      const valueA = Number(left.slice(a, a + runA));
+      const valueB = Number(right.slice(b, b + runB));
+      if (valueA !== valueB) return valueA - valueB;
+      a += runA;
+      b += runB;
+      continue;
+    }
+    const charA = left[a] ?? '';
+    const charB = right[b] ?? '';
+    const foldedA = charA.toLowerCase();
+    const foldedB = charB.toLowerCase();
+    if (foldedA !== foldedB) return foldedA < foldedB ? -1 : 1;
+    // Same letter, different case: uppercase wins HERE rather than after the whole string, which
+    // is what makes `PostView` precede `post` instead of following it.
+    if (charA !== charB) return charA < charB ? -1 : 1;
+    a += 1;
+    b += 1;
+  }
+  return left.length - right.length;
+};
+
+/**
+ * The names of an import, in the order Biome would leave them. `assist/source/organizeImports` is
+ * an ERROR under the scaffold's config, and the order is decided by the FEATURE NAME, not by the
+ * template: `x g action audit-log --feature billing` emitted `{ canBillingWrite, billingTag }`, so
+ * every feature starting `a` or `b` wrote a failing `lint` step into the app. Sorted here rather
+ * than spelled in each template, because the correct spelling is not knowable at authoring time.
+ */
+export const sortSpecifiers = (names: readonly string[]): readonly string[] =>
+  [...names].sort(compareSpecifiers);
+
+/**
+ * A named import, sorted and wrapped. Its own function because the braces are spaced on one line
+ * (`import { a, b } from …`) and not spaced when broken — `wrapList` would emit `import {a, b}`
+ * joined, or a stray space before the closing brace when broken.
+ */
+export function wrapImport(names: readonly string[], from: string): string {
+  const sorted = sortSpecifiers(names);
+  const joined = `import { ${sorted.join(', ')} } from '${from}';`;
+  if (joined.length <= LINE_WIDTH) return joined;
+  return `import {\n${sorted.map((name) => `  ${name},`).join('\n')}\n} from '${from}';`;
+}

package/src/test-counts.ts

@@ -0,0 +1,35 @@
+// What a test step actually executed, read back out of `bun test`'s own summary. Separate from
+// the two runners because both of them need it and neither owns it: a step's exit code answers
+// "did anything fail", and only the counts answer "did anything run".
+
+import type { ExecResult } from './exec';
+import { execOutput } from './exec';
+import { parseBunTest } from './mcp-test-output';
+
+export interface TestCounts {
+  /** Tests that executed — passed plus failed. A failed test is a test that ran. */
+  readonly ran: number;
+  /** Tests bun reported as skipped or todo, which is the same thing here: they did not run. */
+  readonly skipped: number;
+}
+
+/**
+ * Summed across every process the step spawned, because a step is one line in the gate whether it
+ * ran on one worker or eight.
+ *
+ * `parseBunTest` is the reader, not a second regex: it is already the one place this repo turns
+ * bun's summary into numbers (`x mcp`'s `test.run`), and two readers of one format is exactly the
+ * drift the CLI's own boundary rule forbids. It reports output it cannot recognise as one FAILED
+ * test rather than as zeros — which is what keeps a runner that died before printing a summary
+ * from reading as a suite that ran nothing.
+ */
+export const countsOf = (results: readonly ExecResult[]): TestCounts => {
+  let ran = 0;
+  let skipped = 0;
+  for (const result of results) {
+    const run = parseBunTest(execOutput(result), result.durationMs);
+    ran += run.passed + run.failed;
+    skipped += run.skipped;
+  }
+  return { ran, skipped };
+};

package/src/test-select.ts

@@ -9,27 +9,41 @@ import { BadFlagError } from './errors';
 import type { ParsedArgs } from './parse';
 import { flagString, nearest } from './parse';
 import type { TestType } from './verify-tests';
-import { TEST_TYPES, typeFilterOf } from './verify-tests';
+import { ownerOf, TEST_TYPES } from './verify-tests';
 
 export interface TestFile {
   readonly path: string;
   readonly bytes: number;
 }
 
-const TEST_GLOB = '**/*.test.ts';
+/**
+ * `.tsx` too. A JSX test was silently outside the gate's parallel steps — `discoverTests` never
+ * yielded it, so `runParallel` spawned `bun test` over an explicit file list that did not include
+ * it and the step reported green over a file that never executed, while `bun run test` at the root
+ * ran it and failed. `testStepCommand`'s own ignore patterns already say `.test.*`.
+ */
+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.
  */
-const IGNORED = ['/dist/', '/node_modules/', '/examples/'];
+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 — see
- * `belongsToType` below, the one place that rule is decided.
+ * `type`, when given, narrows to exactly the files verify-tests.ts would run for that suite — one
+ * owner per path, decided by `ownerOf` there and never a second time here.
  */
 export async function discoverTests(
   root: string,
@@ -65,18 +79,19 @@ export function sampleFiles(files: readonly TestFile[], sample: number): readonl
 }
 
 /**
- * verify-tests.ts owns the one definition of what a file's test type is; `typeFilterOf` is that
- * table's own accessor. Re-declaring the suffixes here would be a second definition, and the two
- * would drift the first time a suite's naming rule changed.
+ * verify-tests.ts owns the one definition of what a file's test type is, and `ownerOf` IS that
+ * definition — one owner per path, `unit` for anything no typed rule claims. Re-deciding it here
+ * would be a second answer, and the two would disagree the first time a suite's naming rule
+ * changed: a file both of them claimed would run in two steps of one gate.
+ *
+ * Asked lazily, and that is load-bearing: verify-tests.ts imports this module (the gate's test
+ * steps select their files through `discoverTests`), so the two form a cycle. Anything here that
+ * READ that module at import time would evaluate inside its temporal dead zone, and whichever side
+ * is imported first dies with "Cannot access 'TEST_TYPES' before initialization" — measured by
+ * `bun run manifest`, which imports the CLI and took the crash.
  */
-const TYPE_FILTERS: readonly (readonly [Exclude<TestType, 'unit'>, string])[] = TEST_TYPES.filter(
-  (type): type is Exclude<TestType, 'unit'> => type !== 'unit',
-).map((type) => [type, typeFilterOf(type)] as const);
-
-/** unit is everything the five typed suites do not claim, so no file falls between two types. */
 export function belongsToType(path: string, type: TestType): boolean {
-  if (type === 'unit') return TYPE_FILTERS.every(([, filter]) => !path.includes(filter));
-  return TYPE_FILTERS.some(([typed, filter]) => typed === type && path.includes(filter));
+  return ownerOf(path) === type;
 }
 
 /**

package/src/test-shards.ts

@@ -3,11 +3,12 @@
 // cmd-test.ts because a printed reproduction is only true if it carries every input to the split —
 // that rule is this file's, and argv parsing is that one's.
 
-import { docsFor } from './errors';
+import { docsFor } from './error-codes';
 import type { Runner } from './exec';
 import { execOutput } from './exec';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue, StepResult } from './output';
+import { quoteArg } from './shell-quote';
 import type { TestFile } from './test-select';
 import { bySizeThenPath } from './test-select';
 import type { TestType } from './verify-tests';
@@ -43,18 +44,26 @@ export function planShards(files: readonly TestFile[], workers: number): readonl
   }));
 }
 
-/** Explicit file list, so the child never re-globs and can never pick up another shard's files. */
-export const shardArgs = (shard: Shard): readonly string[] => ['bun', 'test', ...shard.files];
-
-const SHELL_SAFE = /^[\w@%+=:,./-]+$/;
-
 /**
- * POSIX single-quoting for the values a caller supplies. A `--filter` holding a space, a `$` or a
- * `;` pastes back as two arguments or as a second command, so an unquoted line would run something
- * other than the run it claims to reproduce. `'\''` is the only escape a single-quoted string has.
+ * Explicit file list, so the child never re-globs and can never pick up another shard's files.
+ *
+ * `--isolate` is what makes an arbitrary partition safe, and it is not optional. Half a dozen
+ * registries in this framework 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. Re-partition the same files and that accident is gone: measured on this
+ * repo, an 8-way split turned 0 failures into 36, all of them `X_PERMISSION_UNKNOWN` in
+ * `@ultimat3/query` because the `packages/cli` file that had been declaring `feed:read` for it
+ * landed in another shard. A fresh module registry per FILE removes the channel entirely, so the
+ * split can be any split. The database is isolated per WORKER, not per file — one cloned template
+ * per process, which is `ULTIMATE_TEST_WORKER` below.
  */
-export const quoteArg = (value: string): string =>
-  SHELL_SAFE.test(value) ? value : `'${value.split("'").join("'\\''")}'`;
+export const SHARD_COMMAND_PREFIX = ['bun', 'test', '--isolate'] as const;
+
+export const shardArgs = (shard: Shard): readonly string[] => [
+  ...SHARD_COMMAND_PREFIX,
+  ...shard.files,
+];
 
 export interface ReproduceOptions {
   /** The *effective* worker count: `planShards` clamps to the file count, and the split follows. */

package/src/test-workers.ts

@@ -0,0 +1,50 @@
+// 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.
+
+// Bun ships no CPU-count primitive; `cpus()` is the fallback when navigator cannot answer.
+import { cpus } from 'node:os';
+
+/** navigator first: it is the runtime's own answer, and it respects a container's CPU limit. */
+export function availableCpus(): number {
+  const hinted = typeof navigator === 'undefined' ? Number.NaN : navigator.hardwareConcurrency;
+  return Math.max(1, Number.isFinite(hinted) && hinted > 0 ? Math.trunc(hinted) : cpus().length);
+}
+
+/**
+ * Deliberately MORE workers than cores, with a ceiling.
+ *
+ * `cpus - 1` is the intuitive default and it was measured to be worthless exactly where it has to
+ * pay off. On a 4-core `ubuntu-latest` — the runner this repo commits to — the `unit` step:
+ *
+ *   | workers | wall  |
+ *   |---------|-------|
+ *   | serial  | 43.2s |
+ *   | 3 (cpus - 1) | 44.8s |   <- the old default: slower than not sharding at all
+ *   | 4       | 41.6s |
+ *   | 6       | 34.8s |
+ *
+ * Three workers on four cores loses to serial because sharding is not free — each worker reloads
+ * the framework's module graph — and three of them cannot cover that cost. The reason more-than-
+ * cores wins is that a test worker is not CPU-bound end to end: it spends real time on module
+ * resolution, on `--isolate` rebuilding a registry per file, and on waiting for its database.
+ * Oversubscribing fills those stalls.
+ *
+ * The ceiling is memory, not cores. A worker is a whole Bun process with the framework's module
+ * graph loaded and — in the typed suites — its own cloned Postgres or an in-process PGlite, so
+ * width costs hundreds of MB per step. It binds on a developer's 12- or 32-core machine, which is
+ * exactly where an unbounded count would swap.
+ *
+ * The floor of 2 keeps a 1-core box sharding rather than silently reverting to serial.
+ */
+export const WORKER_CEILING = 8;
+
+/** Oversubscription factor. See the table above — it is measured, not chosen for roundness. */
+export const WORKER_OVERSUBSCRIBE = 1.5;
+
+/** The floor the paragraph above names: a 1-core box shards rather than reverting to serial. */
+export const WORKER_FLOOR = 2;
+
+export const defaultWorkers = (available: number = availableCpus()): number =>
+  Math.max(WORKER_FLOOR, Math.min(WORKER_CEILING, Math.round(available * WORKER_OVERSUBSCRIBE)));