@ultimat3/cli 24.0.0 → 25.0.0

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

package/src/workspace-graph.ts

@@ -4,7 +4,7 @@
 // for `tsc` and is invisible to bun, to `--filter` ordering and to any change-detection tool.
 
 import { join } from 'node:path';
-import { ERROR_DOCS_URL } from '@ultimat3/core';
+import { ERROR_DOCS_URL, maskLiterals } from '@ultimat3/core';
 import { scanAllImports } from './import-scan';
 import type { Finding } from './output';
 import { eachSourceFile, isGenerated, isTest, isVendored } from './source-files';
@@ -148,10 +148,11 @@ export function packageOfSpecifier(specifier: string): string | undefined {
  * included, because a type edge still needs its manifest line. The transpiler is the parser, so a
  * generator's template literal (even one nested in a `${…}`, #493) is a string and never an import,
  * and `from<Row>('posts')` is a call. A file it cannot parse throws rather than reading as empty.
+ * The mask is what reads a type-position `typeof import('x')`, which the transpiler erases whole.
  */
 export function importedPackages(source: string, path = 'source.ts'): readonly string[] {
   const packages = new Set<string>();
-  for (const specifier of scanAllImports({ path, source })) {
+  for (const specifier of scanAllImports({ path, source }, maskLiterals(source))) {
     const name = packageOfSpecifier(specifier);
     if (name !== undefined) packages.add(name);
   }

package/src/write-line.ts

@@ -7,7 +7,7 @@
 import { writeSync } from 'node:fs';
 // The one import beyond `node:fs`, and it costs nothing here: `create-ultimate` reaches this
 // module through `@ultimat3/cli`'s barrel, which has already evaluated core.
-import { stringField } from '@ultimat3/core';
+import { backoffDelay, stringField } from '@ultimat3/core';
 
 /**
  * Write to stdout and be certain it arrived, even if the next statement exits the process.
@@ -22,22 +22,97 @@ import { stringField } from '@ultimat3/core';
  *
  * `EAGAIN` is "the pipe is full right now", not a failure. CI hands the process a NON-BLOCKING
  * stdout, where `writeSync` throws rather than blocking — so the loop that fixed the truncation
- * took the whole command down on a runner, emitting nothing at all. The reader drains in
- * microseconds; the retry is the correct response to "would block".
+ * took the whole command down on a runner, emitting nothing at all. A draining reader clears it in
+ * microseconds, so it is retried — but BOUNDED: a reader that never drains (a stopped `| less`, a
+ * wedged parent) turned the unbounded retry into a command that never exits, spinning a core.
+ * `EAGAIN_ATTEMPTS` consecutive stalls, each waiting longer (capped), then the line is dropped and
+ * counted (`droppedLineCount()`): one lost line beats a process that cannot finish. After a drop
+ * the fd is DEGRADED: each later line gets one attempt and no sleep, or a never-draining reader
+ * would cost ~1.5 s per line forever. Any byte arriving clears it.
  */
 function writeTo(fd: 1 | 2, line: string): void {
-  const buffer = Buffer.from(`${line}\n`);
+  writeAll(fd, Buffer.from(`${line}\n`));
+}
+
+/** Consecutive stalls one write may absorb before its line is dropped. Progress resets it. */
+export const EAGAIN_ATTEMPTS = 50;
+
+/**
+ * Core's one curve, exponential and capped: 1, 2, 4 … 32 ms — under 1.5 s for a reader that never
+ * drains at all. No jitter: one process waiting on its own pipe has no herd to decorrelate.
+ */
+const backoffMs = (stall: number): number => backoffDelay({ attempt: stall, base: 1, max: 32 });
+
+/** `writeSync`'s shape, so a test can hand in a pipe that is full forever. */
+export type WriteSync = (fd: number, buffer: Uint8Array, offset: number, length: number) => number;
+
+let dropped = 0;
+
+/**
+ * Per fd, because fd 1 and fd 2 are two readers. `degraded`: the last line was dropped, so the next
+ * gets one attempt. `torn`: it was dropped HALF-written, so the next line that arrives opens with
+ * the newline the torn one never got — otherwise the two glue into one unparseable line.
+ */
+const pipes = new Map<number, { degraded: boolean; torn: boolean }>();
+
+const pipeOf = (fd: number): { degraded: boolean; torn: boolean } => {
+  let pipe = pipes.get(fd);
+  if (pipe === undefined) {
+    pipe = { degraded: false, torn: false };
+    pipes.set(fd, pipe);
+  }
+  return pipe;
+};
+
+const NEWLINE = 0x0a;
+
+/** Lines this process dropped to a reader that never drained. */
+export const droppedLineCount = (): number => dropped;
+
+/**
+ * Write every byte of `buffer` to `fd`, or drop it after `EAGAIN_ATTEMPTS` stalls in a row — one
+ * stall while the fd is degraded. Returns whether it all arrived. A write of zero bytes is a stall
+ * too, so no path spins.
+ */
+export function writeAll(
+  fd: number,
+  buffer: Uint8Array,
+  write: WriteSync = writeSync,
+  sleep: (ms: number) => void = Bun.sleepSync,
+): boolean {
+  const pipe = pipeOf(fd);
+  const prefix = pipe.torn ? 1 : 0;
+  const bytes = prefix === 0 ? buffer : Buffer.concat([Uint8Array.of(NEWLINE), buffer]);
   let written = 0;
-  while (written < buffer.length) {
+  let stalls = 0;
+  while (written < bytes.length) {
+    let progress = 0;
     try {
-      written += writeSync(fd, buffer, written, buffer.length - written);
+      progress = write(fd, bytes, written, bytes.length - written);
     } catch (cause) {
       // `stringField`, never a cast plus a property read — the rule `metrics-endpoint.ts` states
       // and `caught-value-reads.test.ts` enforces. Here it is also the difference between
-      // rethrowing and an infinite loop: a `code` that cannot be read must not read as `EAGAIN`.
+      // rethrowing and retrying: a `code` that cannot be read must not read as `EAGAIN`.
       if (stringField(cause, 'code') !== 'EAGAIN') throw cause;
     }
+    if (progress > 0) {
+      written += progress;
+      stalls = 0;
+      pipe.degraded = false; // The reader drained: it gets the full budget again.
+      continue;
+    }
+    stalls += 1;
+    if (stalls >= (pipe.degraded ? 1 : EAGAIN_ATTEMPTS)) {
+      dropped += 1;
+      pipe.degraded = true;
+      // Nothing written leaves a torn line torn; only the prefix written closes it cleanly.
+      if (written > 0) pipe.torn = written > prefix;
+      return false;
+    }
+    sleep(backoffMs(stalls));
   }
+  pipe.torn = false;
+  return true;
 }
 
 export function writeLine(line: string): void {

package/src/browser-launcher-fake-html.ts

@@ -1,80 +0,0 @@
-// CSS selectors over an HTML string, on Bun's own `HTMLRewriter`: the `query()` the offline
-// `fakeShotDriver` answers from markup. The selector subset is lol-html's — type, `#id`, `.class`,
-// `[attr]`, `[attr=value]`, descendant and child combinators. No box and no hit-target on any
-// answer: this has no layout engine, and a fabricated box would make a covered button clickable.
-import type { ElementSnapshot } from './browser-launcher-port';
-
-/** Elements with no end tag: `onEndTag` never fires for them, so they close on open. */
-const VOID_TAGS = new Set([
-  'area',
-  'base',
-  'br',
-  'col',
-  'embed',
-  'hr',
-  'img',
-  'input',
-  'link',
-  'meta',
-  'source',
-  'track',
-  'wbr',
-]);
-
-const HIDDEN_STYLE = /(?:^|;)\s*(?:display\s*:\s*none|visibility\s*:\s*hidden)\s*(?:;|$)/i;
-
-const visible = (tag: string, attrs: ReadonlyMap<string, string>): boolean =>
-  !attrs.has('hidden') &&
-  !(tag === 'input' && attrs.get('type')?.toLowerCase() === 'hidden') &&
-  !HIDDEN_STYLE.test(attrs.get('style') ?? '') &&
-  attrs.get('aria-hidden') !== 'true';
-
-interface Open {
-  readonly tag: string;
-  readonly attrs: Map<string, string>;
-  readonly parts: string[];
-}
-
-const finish = (open: Open): ElementSnapshot => ({
-  tag: open.tag,
-  attrs: Object.fromEntries(open.attrs),
-  text: open.parts.join('').replaceAll(/\s+/g, ' ').trim(),
-  value: open.attrs.get('value') ?? '',
-  visible: visible(open.tag, open.attrs),
-  enabled: !open.attrs.has('disabled') && open.attrs.get('aria-disabled') !== 'true',
-});
-
-/** Every element matching `selector`, as the markup states it. A selector lol-html refuses throws. */
-export async function queryHtml(
-  html: string,
-  selector: string,
-): Promise<readonly ElementSnapshot[]> {
-  const done: ElementSnapshot[] = [];
-  const open: Open[] = [];
-  const rewriter = new HTMLRewriter().on(selector, {
-    element(element): void {
-      const tag = element.tagName.toLowerCase();
-      const attrs = new Map<string, string>();
-      for (const [name, value] of element.attributes) attrs.set(name.toLowerCase(), value);
-      const record: Open = { tag, attrs, parts: [] };
-      if (VOID_TAGS.has(tag)) {
-        done.push(finish(record));
-        return;
-      }
-      open.push(record);
-      element.onEndTag(() => {
-        const index = open.lastIndexOf(record);
-        if (index !== -1) open.splice(index, 1);
-        done.push(finish(record));
-      });
-    },
-    text(chunk): void {
-      // Every OPEN match: `div, span` matches both, and both contain the text.
-      for (const record of open) record.parts.push(chunk.text);
-    },
-  });
-  await rewriter.transform(new Response(html)).text();
-  // Never closed is malformed markup; the element still matched, so it is still reported.
-  for (const record of open) done.push(finish(record));
-  return done;
-}

package/src/browser-launcher-fake.ts

@@ -1,168 +0,0 @@
-// `fakeShotDriver`: a `ShotDriver` over recorded pages, so every `x shot` and `ui.*` test runs with
-// no Chrome. It parses markup and runs none of it — `query()` is answered from the HTML,
-// `evaluate()` from a recorded table, and a click follows `data-goto` or an `<a href>`. What it
-// cannot know it refuses by name rather than inventing: no layout box, and no accessibility tree.
-import { hostDecision, notImplemented } from '@ultimat3/core';
-import { CdpCallFailedError } from '@ultimat3/testing';
-import { queryHtml } from './browser-launcher-fake-html';
-import type {
-  CaptureClip,
-  ElementSnapshot,
-  NetworkEntry,
-  ShotColorScheme,
-  ShotDriver,
-  ShotPage,
-  ShotSession,
-  ShotSessionInit,
-} from './browser-launcher-port';
-import { awaitReady } from './cdp-shot-element';
-import { ShotHostRefusedError } from './cdp-shot-errors';
-import { parseKeyChord } from './cdp-shot-keys';
-
-export const FAKE_SHOT_DRIVER = 'fake';
-
-/** One recorded page: its url, its markup, and `expression -> JSON text` for `evaluate()`. */
-export interface FakeShotPage {
-  readonly url: string;
-  readonly html: string;
-  readonly evaluate?: Readonly<Record<string, string>> | undefined;
-  /** The document's HTTP status. Absent is 200 — the page was recorded because it exists. */
-  readonly status?: number | undefined;
-}
-
-/** A PNG signature, and nothing behind it: deterministic bytes, never a render. */
-export const FAKE_PNG = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
-
-/**
- * Different deterministic bytes for every framing fact that was set — one per rectangle, one per
- * colour preference — so a caller that dropped the clip or the scheme fails a test here, which is
- * the only place a framing knob can be proved without a browser (issue #338).
- */
-export const framedPng = (clip: CaptureClip | undefined, scheme: ShotColorScheme): Uint8Array => {
-  const notes =
-    (clip === undefined
-      ? ''
-      : ` clip ${String(clip.x)},${String(clip.y)},${String(clip.width)},${String(clip.height)}`) +
-    (scheme === 'no-preference' ? '' : ` scheme ${scheme}`);
-  if (notes === '') return FAKE_PNG;
-  const suffix = new TextEncoder().encode(notes);
-  const out = new Uint8Array(FAKE_PNG.length + suffix.length);
-  out.set(FAKE_PNG);
-  out.set(suffix, FAKE_PNG.length);
-  return out;
-};
-
-const normalise = (url: string): string => {
-  try {
-    return new URL(url).toString();
-  } catch {
-    return url;
-  }
-};
-
-function fakePage(byUrl: ReadonlyMap<string, FakeShotPage>, init: ShotSessionInit): ShotPage {
-  let current: FakeShotPage | undefined;
-  let scheme: ShotColorScheme = 'no-preference';
-  const network: NetworkEntry[] = [];
-  const url = (): string => current?.url ?? 'about:blank';
-
-  const navigate = (to: string): void => {
-    const page = byUrl.get(normalise(to));
-    if (page === undefined) {
-      throw new CdpCallFailedError({
-        method: `Page.navigate to ${to}`,
-        detail: 'fakeShotDriver() has no page recorded at that url',
-      });
-    }
-    current = page;
-    network.push({
-      method: 'GET',
-      url: page.url,
-      // Data the page answers with, never a bound — a recorded page exists, so absent is a 200.
-      status: page.status === undefined ? 200 : page.status,
-      resourceType: 'document',
-      at: init.clock.now().getTime(),
-    });
-  };
-
-  const query = (selector: string): Promise<readonly ElementSnapshot[]> =>
-    queryHtml(current?.html ?? '', selector);
-
-  const ready = (selector: string, options?: Parameters<ShotPage['waitFor']>[1]) =>
-    awaitReady({
-      selector,
-      state: options?.state ?? 'actionable',
-      timeoutMs: options?.timeout ?? init.timeoutMs,
-      clock: init.clock,
-      url,
-      snapshot: async () => (await query(selector))[0],
-    });
-
-  return {
-    url,
-    async goto(to) {
-      if (!hostDecision(to, init.rules.allowHosts).allowed) {
-        throw new ShotHostRefusedError({ url: to, allowHosts: init.rules.allowHosts });
-      }
-      navigate(to);
-    },
-    waitFor: (selector, options) => ready(selector, options),
-    async click(selector, options) {
-      const target = await ready(selector, options);
-      // What the browser would do with the click, as far as markup can say: follow the link.
-      const next =
-        target.attrs['data-goto'] ?? (target.tag === 'a' ? target.attrs['href'] : undefined);
-      if (next !== undefined) navigate(new URL(next, url()).toString());
-    },
-    async type(selector, _text, options) {
-      await ready(selector, options);
-    },
-    async focus(selector, options) {
-      await ready(selector, options);
-    },
-    async press(chord) {
-      parseKeyChord(chord);
-    },
-    async accessibility() {
-      return notImplemented(
-        'accessibility() on fakeShotDriver()',
-        'assert on the markup with page.query(selector) — a role read off the HTML would hide the element a screen reader cannot name, which is the finding this read exists for',
-      );
-    },
-    query,
-    async evaluate(expression) {
-      const table = current?.evaluate ?? {};
-      const recorded = Object.hasOwn(table, expression) ? table[expression] : undefined;
-      if (recorded === undefined) {
-        throw new CdpCallFailedError({
-          method: 'Runtime.evaluate',
-          detail: 'fakeShotDriver() has no answer recorded for that expression on this page',
-        });
-      }
-      return JSON.parse(recorded) as unknown;
-    },
-    async screenshot(options) {
-      return framedPng(options?.clip, scheme);
-    },
-    async colorScheme(next) {
-      scheme = next;
-    },
-    async prepare() {},
-    console: () => [],
-    pageErrors: () => [],
-    pageErrorsDropped: () => 0,
-    network: () => [...network],
-    networkDropped: () => 0,
-  };
-}
-
-/** A driver whose every session reads from `pages`. An unrecorded url is refused, never fetched. */
-export function fakeShotDriver(pages: readonly FakeShotPage[]): ShotDriver {
-  const byUrl = new Map(pages.map((page) => [normalise(page.url), page]));
-  return {
-    name: FAKE_SHOT_DRIVER,
-    async open(init): Promise<ShotSession> {
-      return { page: fakePage(byUrl, init), close: async () => undefined };
-    },
-  };
-}