@ultimat3/cli 29.4.0 → 30.1.0

package/src/app-module-graph.ts

@@ -0,0 +1,232 @@
+// The app's module graph as `@ultimat3/manifest`'s `ModuleFacts`: every source and test file, the
+// app files each one imports — type-only imports included, since a type change breaks a test —
+// a computed `import()` marking its file opaque, and which file declares which primitive.
+
+// why: Bun ships no path API; a specifier resolves against its importing file's directory.
+import { dirname, join, relative, resolve } from 'node:path';
+import { describeActions, getAction } from '@ultimat3/action';
+import { maskLiterals } from '@ultimat3/core';
+import { registeredEntities } from '@ultimat3/entity';
+import { registeredJobs, registeredTasks } from '@ultimat3/jobs';
+import type { ModuleFacts } from '@ultimat3/manifest';
+import { describeQueries, getQuery } from '@ultimat3/query';
+import { routeEntries } from '@ultimat3/render';
+import { scanAllImports } from './import-scan';
+import { hasPathSegment } from './path-segments';
+import { isTest } from './source-files';
+
+/** Every authored TypeScript file an app holds: its apps, packages, guards, scripts and root. */
+const FILE_GLOBS = [
+  'apps/**/*.{ts,tsx}',
+  'packages/**/*.{ts,tsx}',
+  'guards/**/*.{ts,tsx}',
+  'scripts/**/*.{ts,tsx}',
+  '*.{ts,tsx}',
+] as const;
+
+/** A computed `import()` — any argument that does not open with a quote — read off masked code. */
+const COMPUTED_IMPORT = /(?<![\w$.])import\s*\(\s*(?!['"])/;
+
+const toPosix = (path: string): string => path.replace(/\\/g, '/');
+
+const skipped = (path: string): boolean =>
+  hasPathSegment(path, 'node_modules') ||
+  hasPathSegment(path, 'dist') ||
+  hasPathSegment(path, '.x') ||
+  path.endsWith('.d.ts');
+
+/** The app's files, root-relative POSIX, sorted. */
+export async function appSourceFiles(root: string): Promise<readonly string[]> {
+  const found = new Set<string>();
+  for (const pattern of FILE_GLOBS) {
+    for await (const path of new Bun.Glob(pattern).scan({ cwd: root, absolute: false })) {
+      const posix = toPosix(path);
+      if (!skipped(posix)) found.add(posix);
+    }
+  }
+  return [...found].sort();
+}
+
+/** One file's app-internal imports (root-relative) and whether it computes one. */
+export function fileImports(
+  root: string,
+  path: string,
+  source: string,
+): { readonly imports: readonly string[]; readonly opaque: boolean } {
+  // Absolute: `Bun.resolveSync` reads a relative directory against nothing useful.
+  const base = resolve(root);
+  const masked = maskLiterals(source);
+  let specifiers: readonly string[];
+  try {
+    specifiers = scanAllImports({ path, source }, masked);
+  } catch {
+    // A file that does not parse imports nothing we can read: it may import anything.
+    return { imports: [], opaque: true };
+  }
+  const imports = new Set<string>();
+  for (const specifier of specifiers) {
+    let resolved: string;
+    try {
+      resolved = Bun.resolveSync(specifier, dirname(join(base, path)));
+    } catch {
+      // Unresolvable: the module's own import fails first, and loudly.
+      continue;
+    }
+    const inside = toPosix(relative(base, resolved));
+    if (!inside.startsWith('../') && !skipped(inside)) imports.add(inside);
+  }
+  return { imports: [...imports].sort(), opaque: COMPUTED_IMPORT.test(masked) };
+}
+
+/**
+ * The app's own test preloads (`bunfig.toml`'s `[test] preload`): Bun imports each before EVERY
+ * test file, so each is an import of every test — the edge no source spells.
+ */
+async function testPreloads(root: string): Promise<readonly string[]> {
+  const bunfig = Bun.file(join(root, 'bunfig.toml'));
+  if (!(await bunfig.exists())) return [];
+  let parsed: unknown;
+  try {
+    parsed = Bun.TOML.parse(await bunfig.text());
+  } catch {
+    // An unparseable bunfig fails every `bun test` first; no edge is better than a guessed one.
+    return [];
+  }
+  const preload = (parsed as { readonly test?: { readonly preload?: unknown } }).test?.preload;
+  const listed = Array.isArray(preload) ? preload : typeof preload === 'string' ? [preload] : [];
+  return fileImports(
+    root,
+    'bunfig.ts',
+    listed.map((entry) => `import ${JSON.stringify(String(entry))};`).join('\n'),
+  ).imports;
+}
+
+/** Every file's facts. `primitives` is filled by `primitiveFiles` once the app has loaded. */
+export async function moduleFiles(root: string): Promise<ModuleFacts['files']> {
+  const preloads = await testPreloads(root);
+  const files: ModuleFacts['files'][number][] = [];
+  for (const path of await appSourceFiles(root)) {
+    const source = await Bun.file(join(root, path)).text();
+    const found = fileImports(root, path, source);
+    const test = isTest(path);
+    const imports = test ? [...new Set([...found.imports, ...preloads])].sort() : found.imports;
+    files.push({ path, imports, opaque: found.opaque, test });
+  }
+  return files;
+}
+
+type Primitive = ModuleFacts['primitives'][number];
+
+const BARREL = /(?:^|\/)index\.tsx?$/;
+
+/**
+ * The modules asked for their exports: the ones `loadApp` imported, and the app's own workspace
+ * libraries (`packages/<name>/src/`, where an entity is declared). Never a script or a guard —
+ * importing one RUNS it.
+ */
+const IMPORTABLE = /^(?:apps\/[^/]+\/(?:app|site|api|shared)\/|packages\/[^/]+\/src\/).*\.tsx?$/;
+
+/**
+ * Which file declares which primitive, by IDENTITY: each loaded module's exports compared with the
+ * handles the registries hold — never a parse of the source for a call. Routes carry their file.
+ * Call after `loadApp`: Bun's module cache answers each import without evaluating it again.
+ */
+export async function primitiveFiles(
+  root: string,
+  files: readonly string[],
+): Promise<readonly Primitive[]> {
+  const handles = new Map<unknown, Omit<Primitive, 'file'>>();
+  for (const { name } of describeActions()) handles.set(getAction(name), { kind: 'action', name });
+  for (const { name } of describeQueries()) handles.set(getQuery(name), { kind: 'query', name });
+  for (const job of registeredJobs()) handles.set(job, { kind: 'job', name: job.name });
+  for (const task of registeredTasks()) handles.set(task, { kind: 'task', name: task.name });
+  for (const entity of registeredEntities()) {
+    if (entity.core !== undefined) handles.set(entity.core, { kind: 'entity', name: entity.name });
+  }
+  const found = new Map<string, Primitive>();
+  for (const route of routeEntries()) {
+    const file = toPosix(route.file);
+    found.set(`route:${route.path}`, { kind: 'route', name: route.path, file });
+  }
+  for (const file of files) {
+    if (isTest(file) || !IMPORTABLE.test(file)) continue;
+    let module: Readonly<Record<string, unknown>>;
+    try {
+      module = (await import(join(root, file))) as Readonly<Record<string, unknown>>;
+    } catch {
+      // A module that will not load declares nothing here; `x verify`'s manifest step names it.
+      continue;
+    }
+    for (const value of Object.values(module)) {
+      const handle = handles.get(value);
+      const key = handle === undefined ? undefined : `${handle.kind}:${handle.name}`;
+      if (handle === undefined || key === undefined) continue;
+      // A barrel re-exports the handle its declaring module exports: the declaring file wins.
+      const held = found.get(key);
+      if (held === undefined || (BARREL.test(held.file) && !BARREL.test(file))) {
+        found.set(key, { ...handle, file });
+      }
+    }
+  }
+  return [...found.values()].sort((a, b) =>
+    `${a.kind}:${a.name}` < `${b.kind}:${b.name}` ? -1 : 1,
+  );
+}
+
+/** Root-level files the framework READS rather than imports: a change re-checks everything. */
+const READ_NOT_IMPORTED = new Set([
+  'app.config.ts',
+  'bunfig.toml',
+  'package.json',
+  'tsconfig.json',
+]);
+
+export interface TestSelection {
+  /** Root-relative test files, sorted. Every test when `all`. */
+  readonly tests: readonly string[];
+  /** `true` when a changed file decides nothing by import alone, so every test runs. */
+  readonly all: boolean;
+  /** The changed files that forced `all`. */
+  readonly forcing: readonly string[];
+}
+
+/**
+ * The tests a change can break: a test runs unless its import closure misses every changed file.
+ * A superset by construction — a test importing an opaque file always runs, and a changed file
+ * the import graph cannot speak for (config read at boot, a catalog, a lockfile, anything outside
+ * the app) runs everything. A `.md` reaches nothing.
+ */
+export function selectTests(
+  files: ModuleFacts['files'],
+  changed: readonly string[],
+): TestSelection {
+  const known = new Set(files.map((file) => file.path));
+  // Outside the app, read at boot, deleted, or no source at all: the import graph cannot speak for
+  // it. A deleted module's importers are no longer on record either, so it forces too.
+  const forcing = changed.filter(
+    (path) =>
+      !path.endsWith('.md') &&
+      (path.startsWith('../') || READ_NOT_IMPORTED.has(path) || !known.has(path)),
+  );
+  const allTests = files.filter((file) => file.test).map((file) => file.path);
+  if (forcing.length > 0) return { tests: allTests, all: true, forcing };
+  const importers = new Map<string, string[]>();
+  for (const file of files) {
+    for (const target of file.imports) {
+      const list = importers.get(target);
+      if (list === undefined) importers.set(target, [file.path]);
+      else list.push(file.path);
+    }
+  }
+  const reached = new Set(changed.filter((path) => known.has(path)));
+  for (const file of files) if (file.opaque) reached.add(file.path);
+  const queue = [...reached];
+  for (let at = queue.shift(); at !== undefined; at = queue.shift()) {
+    for (const importer of importers.get(at) ?? []) {
+      if (reached.has(importer)) continue;
+      reached.add(importer);
+      queue.push(importer);
+    }
+  }
+  return { tests: allTests.filter((test) => reached.has(test)), all: false, forcing: [] };
+}

package/src/app-reload-graph.ts

@@ -4,7 +4,7 @@
 // 2026-09-27 `x dev` re-imported only the edited ROUTE module, under `?x-reload=<hash>`, and every
 // module that route imports resolved to the instance already cached: a save to a component, its
 // `.module.scss` or a helper logged "reloaded" and rendered the old code until a restart
-// (notificado.co: the panel's balance card and the home page, observed twice on one day).
+// (one adopter: the panel's balance card and the home page, observed twice on one day).
 //
 // The rule is a reverse-dependency closure. A rescan hashes every file this graph knows; each
 // changed file, and every module that imports it transitively, leaves the registry, and the scan's
@@ -62,7 +62,7 @@ export function takeStalePins(): readonly StalePin[] {
   return taken;
 }
 /**
- * Edges cost a transpile scan and a resolve per import (~300 ms over notificado.co's 1200 modules),
+ * Edges cost a transpile scan and a resolve per import (~300 ms over one adopter's 1200 modules),
  * so only the one process that rescans pays it: `x dev` turns this on before its first scan. Off,
  * a rescan still re-evaluates each changed module itself — a route saved in place reloads — but
  * nothing it is imported by.

package/src/app-root.ts

@@ -1,6 +1,8 @@
 // Locating the app. `app.config.ts` is the one config file, so it is also the one root marker —
 // commands that need an app resolve it here and nowhere else, and the failure names the fix.
 
+// why: a refusal is synchronous and Bun.file reads are not; this is the one read on that path.
+import { readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { APP_CONFIG_FILE, appDirOf } from '@ultimat3/core';
 import { BunVersionError, NotInAppError } from './errors';
@@ -54,10 +56,44 @@ export function findAppRoot(from: string): AppRoot | undefined {
 
 export function requireAppRoot(command: string, from: string): AppRoot {
   const root = findAppRoot(from);
-  if (root === undefined) throw new NotInAppError({ command, from: resolve(from) });
+  if (root === undefined) {
+    const dir = resolve(from);
+    throw new NotInAppError({
+      command,
+      from: dir,
+      below: appDirsBelow(dir),
+      adopter: dependsOnFramework(dir),
+    });
+  }
   return root;
 }
 
+/** Bounded: this runs on a refusal, and `from` may be a home directory. */
+const APP_CONFIG_BELOW = ['*', '*/*', '*/*/*'].map(
+  (depth) => new Bun.Glob(`${depth}/${APP_CONFIG_FILE}`),
+);
+
+/** The app directories up to three levels under `from`, for a refusal to name. Never vendored. */
+export function appDirsBelow(from: string): readonly string[] {
+  try {
+    return APP_CONFIG_BELOW.flatMap((glob) => [...glob.scanSync({ cwd: from })])
+      .map((path) => path.replaceAll('\\', '/').slice(0, -`/${APP_CONFIG_FILE}`.length))
+      .filter((dir) => !dir.split('/').includes('node_modules'))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+/** Whether `from`'s own manifest names a framework package, read as text: a refusal must not throw. */
+function dependsOnFramework(from: string): boolean {
+  try {
+    return readFileSync(join(from, 'package.json'), 'utf8').includes('"@ultimat3/');
+  } catch {
+    return false;
+  }
+}
+
 /** Semver-lite compare, sufficient because both sides are plain `major.minor.patch`. */
 export function versionAtLeast(found: string, required: string): boolean {
   const parse = (input: string): readonly number[] =>

package/src/bin.ts

@@ -22,6 +22,7 @@ const local = resolveLocalCli({
   cwd: cwdFromArgv(Bun.argv.slice(2), process.cwd()),
   selfPath: import.meta.path,
   env: Bun.env,
+  command: Bun.argv[2],
 });
 if (local !== undefined) {
   writeErrorLine(`x: using the app's own @ultimat3/cli at ${local}`);

package/src/boundary-findings.ts

@@ -8,7 +8,10 @@ import { appImportGraph, checkImportRules, readAppSources } from './app-boundari
 import { siblingModuleFindings } from './app-layout';
 import { appTransportFindings } from './app-transport';
 import { planBoundaryCuts } from './boundary-cuts';
+import { handRolledSocketFindings } from './hand-rolled-socket';
+import { islandDisposerFindings } from './island-disposer';
 import type { Finding } from './output';
+import { packageBoundaryFindings } from './package-boundaries';
 
 /** A cut and a finding name one violation when they share its code, its importer and its chain. */
 const keyOf = (code: string, at: string | undefined, cause: string): string =>
@@ -46,5 +49,8 @@ export async function appBoundaryFindings(
     ...withCutEdits(checkImportRules(files), appImportGraph(files)),
     ...(await appTransportFindings(root, files)),
     ...siblingModuleFindings(files),
+    ...islandDisposerFindings(files),
+    ...handRolledSocketFindings(files),
+    ...(await packageBoundaryFindings(root)),
   ];
 }

package/src/budgets-freshness.ts

@@ -0,0 +1,32 @@
+// Whether `x verify`'s budgets step may read the stats on disk, or has to build first. Pure: the
+// stats as `readBuildStats` returned them and two mtimes in, one state out. The reads that gather
+// the mtimes are `verify-budgets-build.ts`'s.
+
+import type { BuildStats } from './budgets';
+
+/** `fresh` is the only state the step reads without building first. */
+export type BudgetsFreshness = 'fresh' | 'missing' | 'old-rule' | 'older-than-source';
+
+export interface FreshnessInput {
+  /** `readBuildStats`' answer: `undefined` is no file, `stale: true` a file of an earlier rule. */
+  readonly stats: BuildStats | undefined;
+  /** The stats file's mtime; `undefined` when it could not be read. */
+  readonly statsMtimeMs: number | undefined;
+  /** The newest mtime over the app's source set; `undefined` when the set is empty. */
+  readonly newestSourceMtimeMs?: number | undefined;
+}
+
+/**
+ * Mtimes, never a content hash: a wrong answer here costs one rebuild, never a wrong verdict, and
+ * the rebuild writes the stats again. Equal mtimes are fresh, because a build finishing in the same
+ * clock tick as the last save read that save. A stats file with no readable mtime is not trusted.
+ */
+export function budgetsFreshness(input: FreshnessInput): BudgetsFreshness {
+  if (input.stats === undefined || input.statsMtimeMs === undefined) return 'missing';
+  if (input.stats.stale === true) return 'old-rule';
+  const newest = input.newestSourceMtimeMs;
+  // What the build READ, when it said (`sourcesAt`): a save landing during the build is older than
+  // the stats file and newer than that. A file an older build wrote has only its own mtime.
+  const read = input.stats.sourcesAt ?? input.statsMtimeMs;
+  return newest !== undefined && newest > read ? 'older-than-source' : 'fresh';
+}

package/src/budgets.ts

@@ -61,6 +61,11 @@ export interface BuildStats {
   readonly measuredBy?: number;
   /** Set by `readBuildStats` on a file an earlier rule wrote: there are no numbers to read. */
   readonly stale?: true;
+  /**
+   * The newest source mtime (ms) the build read before it rendered (`source-mtime.ts`): `budgets`
+   * calls the stats fresh only if no source is newer, so a save during the build is not missed.
+   */
+  readonly sourcesAt?: number;
 }
 
 /**
@@ -148,7 +153,10 @@ function unmeasuredFinding(
   }
   return {
     code: 'X_BUDGET_UNMEASURED',
-    cause: `${url} declares a ${declared} budget and no build has written ${BUILD_STATS_FILE} in this repo`,
+    // Inside the gate this is a build that ran and still wrote nothing: `x verify`'s budgets step
+    // builds whenever the file is missing (`verify-budgets-build.ts`), so the cause names the one
+    // writer that did not run. The fix is the build alone, which prints why.
+    cause: `${url} declares a ${declared} budget and no build has written ${BUILD_STATS_FILE} in this repo — x verify builds when it is missing, so a static build that ran wrote none: apps/web/prerender.ts must call prerenderSite()`,
     // `--target static` is load-bearing and `x build` alone was a fix that changes nothing: the
     // flag defaults to `docker`, and only the static target runs `apps/web/prerender.ts`, which is
     // the one caller of `writeBuildStats`.
@@ -292,6 +300,17 @@ export interface MeasuredJs {
  * excluded as data, by `carriesJson`, not by this set. A further entry joins this set by a
  * decision, here, with the register's argument: every document carries it and no author can
  * remove it.
+ *
+ * `/x-client-errors.js` (`clientErrors.enabled`, plan 101, 24) is NOT here, and needs no entry: it
+ * rides `app/` documents a served process renders, and the static export this measures never names
+ * it (no route there receives a report). Measured 2026-11-03: 1,961 B (962 B gzip) per served
+ * `app/` document of an app that turned it on, and 0 B for every other document.
+ *
+ * `/x-client-vitals.js` (`clientErrors.vitals`, plan 101, 41) is NOT here either, and is CHARGED:
+ * the app opted in per surface and can opt out, the page boot's argument. A weighed `app/` page
+ * is measured as served (`prerender-served.ts` hands its bytes in `served`), and a `site/` page
+ * that lists it is exported carrying it, so it is weighed off disk. Measured 2026-11-06: 1,202 B
+ * (633 B gzip) per document on a listed surface, 0 B everywhere else.
  */
 export const FRAMEWORK_SCRIPTS: ReadonlySet<string> = new Set([SW_REGISTER_PATH]);
 

package/src/build-capture-env.ts

@@ -0,0 +1,9 @@
+// The one name `x build --no-capture` and the static export agree on. Its own module so `x build`
+// reads it without loading the export's image and card writers.
+
+/**
+ * How `x build --no-capture` reaches the app's own `prerender.ts`, which `x build` spawns and which
+ * calls `prerenderSite` with no flag of its own: `off` stamps the card tags and takes no picture.
+ * An env var, not an argv flag, so every app's existing `prerender.ts` honours it unedited.
+ */
+export const BUILD_CAPTURE_ENV = 'ULTIMATE_BUILD_CAPTURE';

package/src/cdp-shot-a11y.ts

@@ -1,6 +1,8 @@
 // The accessibility tree, read over the page's own CDP session: what the BROWSER computed for a
 // screen reader, after ARIA, label association and `aria-hidden` pruning. A `<div onclick>`
 // answers no role and no name, which is the finding — no read of the markup can reproduce it.
+// The node READER is `@ultimat3/testing`'s, the one the e2e audit reads a whole tree with.
+import { toAxNode } from '@ultimat3/testing';
 import type { AxNode } from './browser-launcher-port';
 
 /** One session-scoped CDP call. Every answer is somebody else's JSON, read and never cast. */
@@ -12,45 +14,6 @@ export type SessionSend = (
 const record = (value: unknown): Readonly<Record<string, unknown>> | undefined =>
   typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : undefined;
 
-/** CDP's `AXValue.value` is any scalar; a reader is told text. */
-const textOf = (wrapped: unknown): string | undefined => {
-  const value = record(wrapped)?.['value'];
-  return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
-    ? String(value)
-    : undefined;
-};
-
-const flagOf = (node: Readonly<Record<string, unknown>>, name: string): boolean | undefined => {
-  const properties = node['properties'];
-  if (!Array.isArray(properties)) return undefined;
-  const found = properties.map(record).find((property) => property?.['name'] === name);
-  return found === undefined ? undefined : record(found['value'])?.['value'] === true;
-};
-
-/**
- * `nodes[0]` is the element's own node when `fetchRelatives` is false. An EMPTY list is a real
- * answer — an element that never entered the tree — and is kept as ignored, so the count the
- * caller gets is the count of matches.
- */
-export const toAxNode = (answer: Readonly<Record<string, unknown>> | undefined): AxNode => {
-  const nodes = answer?.['nodes'];
-  const node = Array.isArray(nodes) ? record(nodes[0]) : undefined;
-  if (node === undefined) return { role: '', name: '', ignored: true };
-  const description = textOf(node['description']);
-  const value = textOf(node['value']);
-  const focused = flagOf(node, 'focused');
-  const disabled = flagOf(node, 'disabled');
-  return {
-    role: textOf(node['role']) ?? '',
-    name: textOf(node['name']) ?? '',
-    ...(description === undefined ? {} : { description }),
-    ...(value === undefined ? {} : { value }),
-    ...(focused === undefined ? {} : { focused }),
-    ...(disabled === undefined ? {} : { disabled }),
-    ignored: node['ignored'] === true,
-  };
-};
-
 /** Every match of `selector`, in document order, at most `max` — one round trip per match. */
 export async function axNodesFor(
   send: SessionSend,