@ultimat3/cli 11.1.0 → 11.2.0

package/src/shot-server.ts

@@ -0,0 +1,90 @@
+// The server a shot is taken against, and the hosts the page may reach while it is: the two
+// facts a ROUTE capture and a COMPONENT capture share, and the only ones. Its own file so
+// `island-shot.ts` can have them without importing the command that photographs a route, which
+// would be a cycle between two files that otherwise have nothing to say to each other.
+
+// why: no Bun native joins a path; `.x/shot` is a path both capture paths write under.
+import { join } from 'node:path';
+import { startDev } from './cmd-dev';
+import { clearLock, isProcessAlive, lockPath, parseLock, preflight, writeLock } from './dev-lock';
+import { DEV_BINDING } from './dev-roles';
+import { resolveServices } from './dev-services';
+
+export const SHOT_DIR = join('.x', 'shot');
+
+/**
+ * How `devServerFor` starts a scratch server. A parameter with a default rather than a direct
+ * call, for the reason every `Runner` in this package is one: the failure path below — a boot that
+ * throws, and the lock it has to hand back — is otherwise only reachable by breaking a real app.
+ */
+export type BootDevServer = (input: {
+  readonly root: string;
+  readonly port: number;
+  readonly env: Readonly<Record<string, string | undefined>>;
+}) => Promise<{ readonly url: string; stop(): Promise<void> }>;
+
+export interface ShotServer {
+  readonly url: string;
+  /** Which server the picture is of. Reported, because the two have different failure modes. */
+  readonly origin: 'booted' | 'reused';
+  stop(): Promise<void>;
+}
+
+/**
+ * One rule, two branches: photograph the `x dev` this checkout already has, or boot a scratch one.
+ * Reusing is not a convenience — embedded Postgres is a single-writer directory, so a second boot
+ * on one checkout is `X_DEV_ALREADY_RUNNING` and the picture would never be taken at all.
+ */
+export async function devServerFor(
+  root: string,
+  env: Readonly<Record<string, string | undefined>>,
+  port: number,
+  boot: BootDevServer = (input) => startDev(input),
+): Promise<ShotServer> {
+  const services = resolveServices(root, env);
+  const file = Bun.file(lockPath(services.stateDir));
+  if (await file.exists()) {
+    const lock = parseLock(await file.text());
+    if (lock !== null && isProcessAlive(lock.pid)) {
+      return { url: lock.url, origin: 'reused', stop: () => Promise.resolve() };
+    }
+  }
+  const { release } = await preflight({
+    stateDir: services.stateDir,
+    port,
+    hostname: DEV_BINDING.hostname,
+    embeddedDb: services.db.mode === 'embedded',
+  });
+  // The directory is CLAIMED from here down — `preflight` returns holding it, never having merely
+  // looked — so a boot that throws has to give it back. `cmd-dev.ts` states the same rule at the
+  // same seam. Without it one failed `x shot` refused every later `x dev` and `x shot` on this
+  // checkout, naming a pid that had already exited. The original error is re-thrown untouched: a
+  // teardown must never replace the failure it is cleaning up after.
+  const dev = await boot({ root, port, env }).catch((error: unknown) => {
+    release();
+    throw error;
+  });
+  await writeLock(services.stateDir, {
+    pid: process.pid,
+    port,
+    url: dev.url,
+    startedAt: new Date().toISOString(),
+  });
+  return {
+    url: dev.url,
+    origin: 'booted',
+    async stop() {
+      clearLock(services.stateDir);
+      await dev.stop();
+    },
+  };
+}
+
+/** `--allow-hosts a.com,b.com` on top of the app's own host. Empty means the app's host alone. */
+export const allowHostsFrom = (url: string, extra: string | undefined): readonly string[] => {
+  const named = (extra ?? '')
+    .split(',')
+    .map((host) => host.trim())
+    .filter((host) => host.length > 0);
+  return [new URL(url).hostname, ...named];
+};

package/src/shot-settle.ts

@@ -1,7 +1,8 @@
-// When a shot may be TAKEN: the two rules that decide whether the page has finished hydrating,
-// separated from both the command that drives a browser and the verdict that judges what came
-// back. Plain values and an injected sleep, so the whole loop is proved with neither.
+// When a shot may be TAKEN: the rules that decide whether the page has finished, separated from
+// both the command that drives a browser and the verdict that judges what came back. Plain values
+// and an injected sleep, so every loop here is proved with neither.
 
+import type { IslandReadiness } from './island-verdict';
 import type { IslandCount } from './shot-verdict';
 
 /**
@@ -55,3 +56,32 @@ export async function settleIslands(
   }
   return answer;
 }
+
+/**
+ * Read the harness's readiness until the page goes QUIET or the window runs out.
+ *
+ * Quiet and not idle, which is the whole rule: the page's own watcher sets `ready` after N
+ * consecutive frames in which no request started and none settled, so a state whose fixture is
+ * deliberately `pending` still reaches it. Waiting for nothing in flight would hang on exactly the
+ * state an author declared on purpose, and a fixed sleep would photograph whatever a slow machine
+ * had painted by then.
+ *
+ * A `null` answer never overwrites a real one, for `settleIslands`' reason: `null` is "the page
+ * answered no probe", and a probe that fails once must not turn a ready page into an unready one.
+ */
+export async function settleReadiness(
+  probe: () => Promise<IslandReadiness | null>,
+  options: SettleOptions,
+): Promise<IslandReadiness | null> {
+  const sleep = options.sleep ?? ((ms: number): Promise<void> => Bun.sleep(ms));
+  let answer = await probe();
+  let waited = 0;
+  while (answer?.ready !== true && waited < options.windowMs) {
+    // At least 1ms, or a `pollMs` of zero is a loop with no exit while the window stands.
+    const step = Math.max(1, Math.min(options.pollMs, options.windowMs - waited));
+    await sleep(step);
+    waited += step;
+    answer = (await probe()) ?? answer;
+  }
+  return answer;
+}

package/src/ts-scan.ts

@@ -161,10 +161,18 @@ export function lineIndex(text: string): (index: number) => number {
 }
 
 /**
- * Every string literal in the value expression starting at `from`, at the expression's own bracket
- * depth. Spanning the expression is what makes `cond ? 'a' : 'b'` and `table[k] ?? 'c'` checkable
- * instead of silently skipped; the depth rule is what keeps `command.join(' ')`'s separator and
- * `table['key']`'s key out — an argument is not a fix.
+ * Every string literal the value expression starting at `from` can EVALUATE TO, at the
+ * expression's own bracket depth. Spanning the expression is what makes `cond ? 'a' : 'b'` and
+ * `table[k] ?? 'c'` checkable instead of silently skipped; the depth rule is what keeps
+ * `command.join(' ')`'s separator and `table['key']`'s key out — an argument is not a fix.
+ *
+ * A ternary's CONDITION is dropped, which is the difference between reading the expression and
+ * reading every literal in it. `fix: input.slug === '' ? 'x g …' : 'x g …'` published the empty
+ * string as a fix line — `X_ERROR_FIX_INVALID`, "the fix line is empty", against source whose two
+ * real fixes are both correct — and `input.key === 'timeZone' ? … : …` published `timeZone`, a
+ * string then judged for banned phrases and cited paths that is not a fix at all. Costly enough
+ * that `@ultimat3/testing`'s island-state errors carry two classes under one code rather than one
+ * class with a ternary in it.
  */
 export function valueLiterals(
   masked: string,
@@ -173,21 +181,42 @@ export function valueLiterals(
   lineAt: (index: number) => number,
 ): readonly FixSite[] {
   const found: { value: string; index: number }[] = [];
+  // The literals of the segment being read. A segment ended by `?` is a condition and is dropped
+  // whole; one ended by `:` or by the end of the expression is a value the fix can evaluate to.
+  let segment: { value: string; index: number }[] = [];
+  const keep = (): void => {
+    found.push(...segment);
+    segment = [];
+  };
   let depth = 0;
+  /** Open `?`s still waiting for their `:`, so a `:` outside a ternary stays an ordinary char. */
+  let conditionals = 0;
   for (let i = from; i < masked.length; i += 1) {
     const ch = masked[i] as string;
     if (QUOTES.has(ch)) {
       const end = endOfLiteral(masked, i);
       // A quote that never closes is one character of code, not an empty literal to report.
       if (end === i + 1) continue;
-      if (depth === 0) found.push({ value: source.slice(i + 1, end - 1), index: i });
+      if (depth === 0) segment.push({ value: source.slice(i + 1, end - 1), index: i });
       i = end - 1;
     } else if (OPENERS.has(ch)) depth += 1;
     else if (CLOSERS.has(ch)) {
       if (depth === 0) break;
       depth -= 1;
+    } else if (depth === 0 && ch === '?') {
+      // `??` and `?.` are operators and end no segment: `input?.fix ?? 'x help'` evaluates to the
+      // literal, and dropping what came before it would drop the only answer the expression has.
+      if (masked[i + 1] === '?') i += 1;
+      else if (masked[i + 1] !== '.') {
+        segment = [];
+        conditionals += 1;
+      }
+    } else if (depth === 0 && ch === ':' && conditionals > 0) {
+      keep();
+      conditionals -= 1;
     } else if (depth === 0 && (ch === ',' || ch === ';')) break;
   }
+  keep();
   return found.map((literal) => ({
     at: '',
     line: lineAt(literal.index),

package/src/workspace-checks.ts

@@ -1,12 +1,20 @@
-// Four shape rules the gate owns: one file, one job (a hard line ceiling), every workspace
-// package shipping the same contract files, every published package's tarball matching what its
-// manifest promises, and every published package being in the root build graph. All report
-// findings — a shape rule that is only written down is not a rule (axiom 3).
+// Four shape rules the gate owns: one file, one job (a hard line ceiling on REVIEWABLE LOGIC),
+// every workspace package shipping the same contract files, every published package's tarball
+// matching what its manifest promises, and every published package being in the root build graph.
+// All report findings — a shape rule that is only written down is not a rule (axiom 3).
+//
+// The ceiling exempts a pure re-export manifest, and only that. Such a file has one job by
+// construction and its length is a function of the package's API size rather than of its
+// complexity: `@ultimat3/core`'s `src/index.ts` reached 514 lines with 513 statements and not one
+// of them logic, so the ceiling had stopped protecting anything and started refusing every new
+// 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 { join } from 'node:path';
 import { ERROR_DOCS_URL, renderCauseValue } from '@ultimat3/core';
 import type { Finding } from './output';
+import { isReExportManifest } from './reexport-manifest';
 import { eachSourceFile, isGenerated } from './source-files';
 import { checkRootReferences } from './tsconfig-references';
 
@@ -30,13 +38,21 @@ export const tooLongFinding = (path: string, lines: number): Finding => ({
 export const countLines = (text: string): number =>
   text === '' ? 0 : text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
 
-/** Files are the unit of review: one file, one job, hard ceiling 500 lines. */
+/**
+ * Files are the unit of review: one file, one job, hard ceiling 500 lines of reviewable logic.
+ *
+ * The source is read before the count is judged rather than after, because the exemption is a
+ * question about CONTENTS: a 3,000-line file of re-exports is one job and a 501-line file with one
+ * statement of logic in it is not, and only reading tells them apart.
+ */
 export async function checkFileSizes(root: string): Promise<readonly Finding[]> {
   const findings: Finding[] = [];
   for await (const path of eachSourceFile(root)) {
     if (isGenerated(path)) continue;
-    const lines = countLines(await Bun.file(join(root, path)).text());
-    if (lines > LINE_CEILING) findings.push(tooLongFinding(path, lines));
+    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));
   }
   return findings;
 }