@ultimat3/cli 20.2.1 → 22.0.0

package/src/verify-run.ts

@@ -14,7 +14,7 @@ import {
 import type { StepOutcome, VerifyContext, VerifyStep } from './verify-step';
 
 /**
- * Run every step in order, never bailing early: an agent fixing three things at once needs all
+ * Run every step, never bailing early: an agent fixing three things at once needs all
  * three findings from one run, not one per round-trip.
  *
  * `ctx.only` narrows the list to one step. The narrowing lives HERE rather than in `cmd-verify.ts`
@@ -26,61 +26,43 @@ export async function runVerify(
   ctx: VerifyContext,
 ): Promise<CommandResult> {
   const floor = await readVerifyFloor(ctx.root);
-  const results: StepResult[] = [];
   const selected = ctx.only === undefined ? steps : steps.filter((step) => step.name === ctx.only);
+  const byName = new Map<string, StepResult>();
+  const began = performance.now();
+  // The static steps wait for the serial suites and then run BESIDE them — only when `live` is in
+  // the list, so a one-step run (`--only`) and a list with no serial suite keep today's order.
+  const overlapping = selected.some((step) => step.name === SERIAL_SUITES[0]);
+  const beside = overlapping ? selected.filter((step) => BESIDE_SERIAL_SUITES.has(step.name)) : [];
+  let pending: Promise<void> | undefined;
+  const join = async (): Promise<void> => {
+    await pending;
+    pending = undefined;
+  };
   for (const step of selected) {
-    const applies = step.applies === undefined ? true : await step.applies(ctx);
-    if (!applies) {
-      // A skip this repo already ruled out is not a skip. The step ran here before — the floor is
-      // that claim, committed — so "nothing to check" now means the suite was deleted, and the
-      // gate says so on the step's own line rather than counting one more thing not to worry
-      // about. Recorded as failed and NOT as skipped, so every reader of a step table sees it:
-      // the summary, `data.failed`, and the reference-app gate's own red list.
-      const required = floorRequires(floor, step.name);
-      results.push({
-        name: step.name,
-        ok: !required,
-        durationMs: 0,
-        skipped: !required,
-        findings: required ? [vanishedSuiteFinding(step.name)] : [],
-      });
-      continue;
+    if (beside.includes(step)) continue;
+    if (step.name === SERIAL_SUITES[0]) {
+      pending = Promise.all(
+        beside.map(async (other) => {
+          byName.set(other.name, await runStep(other, ctx, floor));
+        }),
+      ).then(() => undefined);
+    } else if (!SERIAL_SUITES.includes(step.name)) {
+      await join();
     }
-    const started = performance.now();
-    const outcome = await step.run(ctx).catch(
-      (error: unknown): StepOutcome => ({
-        ok: false,
-        findings: [findingOf(error, step.name)],
-      }),
-    );
-    // A suite that executed nothing did not run, whatever its exit code says: `bun test` exits 0
-    // over an all-skipped file, so the counts are the only channel that can tell the two apart.
-    // ONE definition of "nothing ran", read twice, because the floor decides which of the two
-    // things it means — exactly as it already does for a step whose `applies` said no.
-    const tests = outcome.tests;
-    const nothingRan = tests !== undefined && tests.ran === 0;
-    const required = floorRequires(floor, step.name);
-    // A step the floor requires whose suite executed nothing is the same vanished suite as a step
-    // with no files at all — the run just had to finish before it could be seen. Appended to the
-    // step's own findings so `data.failed`, the counts and every gate reading this table carry it.
-    const vanished = nothingRan && required ? [skippedSuiteFinding(step.name, tests.skipped)] : [];
-    results.push({
-      name: step.name,
-      ok: outcome.ok && vanished.length === 0,
-      durationMs: Math.round(performance.now() - started),
-      // Without a floor to require it, a suite that ran nothing is a SKIP and not a pass (#434):
-      // the `e2e` step printed `✓ e2e 46ms` over its one skipped test, which is the one thing a
-      // step table may never do — a reader cannot tell a lane that ran from a lane that did not.
-      skipped: nothingRan && !required,
-      findings: [...outcome.findings, ...vanished],
-      ...(outcome.output === undefined ? {} : { output: outcome.output }),
-      ...(outcome.workers === undefined ? {} : { workers: outcome.workers }),
-      ...(tests === undefined ? {} : { tests }),
-    });
+    byName.set(step.name, await runStep(step, ctx, floor));
   }
+  await join();
+  // Reported in the declared order, whatever order the steps finished in: the table, `--json` and
+  // every gate parsing either read the same sequence they always did.
+  const results = selected.flatMap((step) => {
+    const result = byName.get(step.name);
+    return result === undefined ? [] : [result];
+  });
   const failedSteps = results.filter((step) => !step.ok).map((step) => step.name);
   const skippedSteps = results.filter((step) => step.skipped === true).map((step) => step.name);
-  const totalMs = results.reduce((sum, step) => sum + step.durationMs, 0);
+  // WALL time, not the sum of step times: with steps overlapping, the sum overstates what a run
+  // costs, and the wall clock is the number a CI job waits on.
+  const totalMs = Math.round(performance.now() - began);
   const summary = verifySummary({
     results,
     failed: failedSteps,
@@ -139,6 +121,89 @@ function verifySummary(input: {
   return msg(clean ? 'cli.verify.fail' : 'cli.verify.failSkipped', params);
 }
 
+/**
+ * `x verify`'s wall time was the SUM of 20 serial steps (#14, the DX ledger): measured locally, 395s,
+ * of which `lint`, `boundaries`, `filesize`, `package-shape` and `errors` were 127s spent while
+ * nothing else ran. They read the tree and write nothing a later step reads (`lint` is biome over
+ * files; the rest are in-process scans), so they run BESIDE the serial suites — `live` and `e2e`
+ * are one worker each, Postgres- and browser-bound, and mostly waiting. `typecheck` stays first
+ * and alone: `tsc -b` writes `.tsbuildinfo` and `dist/`, and `unit` saturates every core.
+ * `manifest` joined them 2026-09-23: it compares committed files against the code and writes
+ * nothing, and at the repo root its host checks are ~20 whole-tree reads that sat alone at the end.
+ */
+export const BESIDE_SERIAL_SUITES: ReadonlySet<string> = new Set([
+  'lint',
+  'boundaries',
+  'filesize',
+  'package-shape',
+  'errors',
+  'manifest',
+]);
+
+/** The consecutive run of steps the static group overlaps, in the order `VERIFY_STEP_NAMES` holds. */
+export const SERIAL_SUITES: readonly string[] = ['live', 'job', 'e2e', 'eval'];
+
+async function runStep(
+  step: VerifyStep,
+  ctx: VerifyContext,
+  floor: Awaited<ReturnType<typeof readVerifyFloor>>,
+): Promise<StepResult> {
+  // Inside the step's own failure, like a throwing `run`: an `applies` that threw escaped every
+  // catch and aborted the whole gate, which is the one outcome `runVerify` exists to prevent.
+  let applies: boolean;
+  try {
+    applies = step.applies === undefined ? true : await step.applies(ctx);
+  } catch (error) {
+    return { name: step.name, ok: false, durationMs: 0, findings: [findingOf(error, step.name)] };
+  }
+  if (!applies) {
+    // A skip this repo already ruled out is not a skip. The step ran here before — the floor is
+    // that claim, committed — so "nothing to check" now means the suite was deleted, and the
+    // gate says so on the step's own line rather than counting one more thing not to worry
+    // about. Recorded as failed and NOT as skipped, so every reader of a step table sees it:
+    // the summary, `data.failed`, and the reference-app gate's own red list.
+    const required = floorRequires(floor, step.name);
+    return {
+      name: step.name,
+      ok: !required,
+      durationMs: 0,
+      skipped: !required,
+      findings: required ? [vanishedSuiteFinding(step.name)] : [],
+    };
+  }
+  const started = performance.now();
+  const outcome = await step.run(ctx).catch(
+    (error: unknown): StepOutcome => ({
+      ok: false,
+      findings: [findingOf(error, step.name)],
+    }),
+  );
+  // A suite that executed nothing did not run, whatever its exit code says: `bun test` exits 0
+  // over an all-skipped file, so the counts are the only channel that can tell the two apart.
+  // ONE definition of "nothing ran", read twice, because the floor decides which of the two
+  // things it means — exactly as it already does for a step whose `applies` said no.
+  const tests = outcome.tests;
+  const nothingRan = tests !== undefined && tests.ran === 0;
+  const required = floorRequires(floor, step.name);
+  // A step the floor requires whose suite executed nothing is the same vanished suite as a step
+  // with no files at all — the run just had to finish before it could be seen. Appended to the
+  // step's own findings so `data.failed`, the counts and every gate reading this table carry it.
+  const vanished = nothingRan && required ? [skippedSuiteFinding(step.name, tests.skipped)] : [];
+  return {
+    name: step.name,
+    ok: outcome.ok && vanished.length === 0,
+    durationMs: Math.round(performance.now() - started),
+    // Without a floor to require it, a suite that ran nothing is a SKIP and not a pass (#434):
+    // the `e2e` step printed `✓ e2e 46ms` over its one skipped test, which is the one thing a
+    // step table may never do — a reader cannot tell a lane that ran from a lane that did not.
+    skipped: nothingRan && !required,
+    findings: [...outcome.findings, ...vanished],
+    ...(outcome.output === undefined ? {} : { output: outcome.output }),
+    ...(outcome.workers === undefined ? {} : { workers: outcome.workers }),
+    ...(tests === undefined ? {} : { tests }),
+  };
+}
+
 function findingOf(error: unknown, step: string): Finding {
   // A step may throw anything, including an Error that fights being read: `instanceof` runs a
   // Proxy's `getPrototypeOf` trap and `.message` runs a getter, so a hostile throw would take the

package/src/verify-step.ts

@@ -79,9 +79,9 @@ export interface VerifyContext {
    */
   readonly workers?: number;
   /**
-   * ONE step, by name — an iteration loop, and the one thing here that IS a narrowing. Every
-   * iteration of the whole gate costs ~18s (14s of it `tsc -b`), which is the cost of asking a
-   * question about one step. It does not weaken axiom 5, and the two rules that keep it honest are
+   * ONE step, by name — an iteration loop, and the one thing here that IS a narrowing. The
+   * whole gate costs minutes (3m19s at the framework root on 12 cores, `As of 2026-09-23`), which
+   * is the cost of asking a question about one step. It does not weaken axiom 5, and the two rules that keep it honest are
    * mechanical rather than remembered: a run with this set prints `NOT A GATE RUN` in the summary
    * AND carries `notAGateRun` in `--json` (`verify-run.ts`), so no reader of either can mistake it
    * for the gate; and nothing writes `x.verify.json`, so the suite floor cannot be lowered by a

package/src/verify-tests.ts

@@ -18,7 +18,8 @@ import { countsOf } from './test-counts';
 import { testEnvOverrides } from './test-dotenv';
 import type { TestFile } from './test-select';
 import { discoverTests } from './test-select';
-import { defaultWorkers } from './test-workers';
+import { defaultWorkers, SERIAL_TYPES } from './test-workers';
+import { withE2eApp } from './verify-e2e';
 import type { StepOutcome, VerifyContext, VerifyStep } from './verify-step';
 import { fromExec, fromFindings } from './verify-step';
 import { runParallel } from './verify-test-run';
@@ -110,31 +111,6 @@ export const ownerOf = (path: string): TestType =>
 const disownedBy = (type: TypedTest): readonly string[] =>
   type === 'e2e' ? [`**/e2e/**/*.{${OUTRANKING_E2E.join(',')}}.test.*`] : [];
 
-/**
- * Which types run across worker processes, and why the other two cannot.
- *
- * Parallel is safe when the only thing a test file shares with another file is the database, and
- * the database is per worker by construction (`ULTIMATE_TEST_WORKER` → one clone of the migrated
- * template, `@ultimat3/testing`'s `acquireWorkerDatabase`). Every other process-global in this
- * framework — the permission set, the roles, the entity/action/query registries, the error-code
- * titles, the fixture bag — is handled by `--isolate` giving each FILE its own module registry.
- *
- * | Type | Why |
- * |---|---|
- * | `live` | **serial.** A logical replication slot and a publication are named at the Postgres
- * CLUSTER level, not inside a database, and this repo's own feed tests hard-code
- * `x_live_slot` / `x_live_pub` against `TEST_REPLICATION_URL` — the one server, never a per-worker
- * clone. Two workers would race `pg_create_logical_replication_slot` and the loser's failure would
- * read as a flake. A per-worker database does not isolate a cluster-wide object |
- * | `e2e` | **serial.** It runs against the *built output*: one `dist/`, one service-worker
- * registration, one browser profile. There is nothing per-worker to hand it, and the type is
- * seconds at most, so a split would buy a race and no time |
- *
- * The two are named here rather than tested for, because "can this type be sharded?" is a design
- * fact about the type, not something a run can discover about itself.
- */
-export const SERIAL_TYPES: readonly TestType[] = ['live', 'e2e'];
-
 const isSerial = (type: TestType): boolean => SERIAL_TYPES.includes(type);
 
 /**
@@ -162,6 +138,12 @@ const ignoreFlags = (patterns: readonly string[]): readonly string[] =>
 export const typeFiltersOf = (type: Exclude<TestType, 'unit'>): readonly string[] =>
   OWNERSHIP.filter(([owner]) => owner === type).map(([, filter]) => filter);
 
+/**
+ * An e2e test's own budget: a first navigation waits on `x dev` compiling the route and its island,
+ * which bun's default 5 s does not cover — a timeout there reads as an app bug that is not one.
+ */
+export const E2E_TEST_TIMEOUT_MS = 60_000;
+
 /** Unit is everything the typed suites do not claim, so no test can fall between two steps. */
 export const testStepCommand = (type: TestType): readonly string[] =>
   type === 'unit'
@@ -173,6 +155,7 @@ export const testStepCommand = (type: TestType): readonly string[] =>
     : [
         'bun',
         'test',
+        ...(type === 'e2e' ? [`--timeout=${String(E2E_TEST_TIMEOUT_MS)}`] : []),
         ...ignoreFlags([...NEVER_A_TEST, ...disownedBy(type)]),
         ...typeFiltersOf(type),
       ];
@@ -203,10 +186,19 @@ export const resetTestDiscovery = (): void => discovered.clear();
 const runSerial = async (ctx: VerifyContext, type: TestType): Promise<StepOutcome> => {
   const command = testStepCommand(type);
   const envOverrides = testEnvOverrides(ctx.root, ctx.env ?? Bun.env);
-  const result = await ctx.runner(command, {
-    cwd: ctx.root,
-    ...(Object.keys(envOverrides).length === 0 ? {} : { env: envOverrides }),
-  });
+  const exec = (e2e: { command: readonly string[]; env: typeof envOverrides }) =>
+    ctx.runner(e2e.command, {
+      cwd: ctx.root,
+      ...(Object.keys(e2e.env).length === 0 ? {} : { env: e2e.env }),
+    });
+  // The e2e step drives a real browser against the app it spawns, when this machine has one.
+  const result =
+    type === 'e2e'
+      ? await withE2eApp(
+          { root: ctx.root, isApp: isApp(ctx.root), command, env: envOverrides },
+          exec,
+        )
+      : await exec({ command, env: envOverrides });
   return {
     ...fromExec(result, {
       code: 'X_TEST_FAILED',

package/src/verify-typecheck.ts

@@ -0,0 +1,28 @@
+// Which `tsc` invocation the `typecheck` step runs. `tsc -b` decides "up to date" by mtime, and Bun
+// installs a package as HARDLINKS out of its cache, carrying the cache's old mtimes — so upgrading
+// a dependency to a version already in the cache left every input older than the buildinfo, `-b`
+// skipped the program and reported green while a cold CI went red (#450). `-p` with `incremental`
+// re-reads every input and compares content hashes, so it cannot be fooled by a date.
+
+import { checkRootReferences } from './tsconfig-references';
+
+/**
+ * A package dir no reference can name. `checkRootReferences` answers `[]` when the root has no
+ * `references` array at all and one finding for this probe when it has one, which is the one
+ * question asked here — without a second JSONC parser beside the one that file owns.
+ */
+const PROBE = '\u0000x-verify-typecheck-probe';
+
+/** True when the root tsconfig declares `references`: a build graph that only `-b` can walk. */
+export const usesProjectReferences = async (root: string): Promise<boolean> =>
+  (await checkRootReferences(root, [PROBE])).length > 0;
+
+/**
+ * The argv after `bunx`. A root with references keeps `-b` — the framework's 32 projects are only
+ * reachable that way, and `tsc -b` rebuilds a project whose own sources moved. A root without them
+ * (every scaffolded app) is ONE program, and `-p .` is the content-hashed check of it.
+ */
+export async function typecheckArgs(root: string, bin: string): Promise<readonly string[]> {
+  const mode = (await usesProjectReferences(root)) ? ['-b'] : ['-p', '.'];
+  return [bin, ...mode, '--pretty', 'false'];
+}

package/src/web-binding.ts

@@ -1,6 +1,6 @@
 // How a process binds its sockets, and what it admits about itself. A LEAF: it imports nothing,
-// so every role can read it without pulling `dev-roles` — which is what made this its own file.
-// `dev-sync` needs the default and `dev-roles` already imports `dev-sync`, so reading it from
+// so every role can read it without pulling `role-start` — which is what made this its own file.
+// `role-sync` needs the default and `role-start` already imports `role-sync`, so reading it from
 // there would be a runtime import cycle in the framework's own boot path.
 
 export interface WebBinding {

package/src/worker-bundle.ts

@@ -0,0 +1,192 @@
+// The page's framework scripts (plan 101), each built as its own classic-script browser bundle,
+// addressed by a hash of its source graph, served `immutable` by the same route in `x dev` and the
+// container: the ONE sync worker (`@ultimat3/realtime/sync-worker`, slice 11) and the ONE page boot
+// (`@ultimat3/realtime/boot` — the disk restore and the outbox, once per page instead of once per
+// island). A new deploy is a new URL, so an old tab keeps what it started with.
+
+// why: Bun ships no path API; the entry is resolved to a file and named in the cause.
+import { dirname, join, relative } from 'node:path';
+import type { Route, UltimateRequest } from '@ultimat3/http';
+import { applyCacheHeaders, json } from '@ultimat3/http';
+import { FrameworkScriptBuildFailedError, type FrameworkScriptKind } from './errors';
+import { describeBuildError, graphHash, stripDebugId } from './island-bundle';
+
+/** Under the dev namespace `/_x` — where the socket it opens (`/_x/sync`) already lives. */
+export const SYNC_WORKER_BASE_PATH = '/_x/sync-worker';
+
+/** What an app resolves: realtime's worker entry, from the APP's install, never the CLI's own. */
+export const SYNC_WORKER_SPECIFIER = '@ultimat3/realtime/sync-worker';
+
+/** Under the dev namespace too; one per document that carries a principal scope. */
+export const PAGE_BOOT_BASE_PATH = '/_x/page-boot';
+
+/** Realtime's page boot, from the APP's install. */
+export const PAGE_BOOT_SPECIFIER = '@ultimat3/realtime/boot';
+
+/** One framework script: the sync worker or the page boot. */
+export interface FrameworkScript {
+  /** `<base>/<hash>.js` — what the document names. */
+  readonly url: string;
+  readonly code: string;
+  readonly bytes: number;
+}
+
+/** The worker, by the name every caller already uses. */
+export type SyncWorkerChunk = FrameworkScript;
+
+export interface BuildSyncWorkerOptions {
+  /** An absolute entry path. Absent resolves `SYNC_WORKER_SPECIFIER` from `root`. */
+  readonly entry?: string;
+}
+
+/**
+ * `undefined` when the app cannot resolve realtime's worker: an app with no realtime has no
+ * socket to share, and the tab-side host falls back to an in-page engine by design (slice 11's
+ * transparent fallback) — absence is an answer, not a failure.
+ */
+export function buildSyncWorker(
+  root: string,
+  options: BuildSyncWorkerOptions = {},
+): Promise<FrameworkScript | undefined> {
+  return buildFrameworkScript(
+    root,
+    'sync worker',
+    SYNC_WORKER_SPECIFIER,
+    SYNC_WORKER_BASE_PATH,
+    options.entry,
+  );
+}
+
+/**
+ * The page boot, or `undefined` for an app with no realtime (nothing to restore, no outbox). A
+ * document then carries no boot script, and `pageRealtime().booted` answers at once.
+ */
+export function buildPageBoot(
+  root: string,
+  options: BuildSyncWorkerOptions = {},
+): Promise<FrameworkScript | undefined> {
+  return buildFrameworkScript(
+    root,
+    'page boot',
+    PAGE_BOOT_SPECIFIER,
+    PAGE_BOOT_BASE_PATH,
+    options.entry,
+  );
+}
+
+async function buildFrameworkScript(
+  root: string,
+  what: FrameworkScriptKind,
+  specifier: string,
+  basePath: string,
+  explicit: string | undefined,
+): Promise<FrameworkScript | undefined> {
+  const entry = explicit ?? resolveEntry(root, specifier);
+  if (entry === undefined) return undefined;
+  const label = relative(root, entry);
+  let built: Awaited<ReturnType<typeof Bun.build>>;
+  try {
+    built = await Bun.build({
+      entrypoints: [entry],
+      target: 'browser',
+      // A CLASSIC script: `new SharedWorker(url, { name })` with no `type: 'module'` runs it, and a
+      // `<script defer>` runs it before any island module that follows it in the document.
+      format: 'iife',
+      splitting: false,
+      minify: true,
+      // `island-bundle.ts`'s reasons, verbatim: a chunk is only ever built to be shipped, and the
+      // map's `sourcesContent` is the one stable identity a minified bundle has.
+      define: { 'process.env.NODE_ENV': '"production"' },
+      sourcemap: 'external',
+    });
+  } catch (error) {
+    throw new FrameworkScriptBuildFailedError({
+      what,
+      entry: label,
+      logs: describeBuildError(error),
+    });
+  }
+  const output = built.outputs.find((artifact) => artifact.kind === 'entry-point');
+  const map = built.outputs.find((artifact) => artifact.kind === 'sourcemap');
+  if (!built.success || output === undefined || map === undefined) {
+    throw new FrameworkScriptBuildFailedError({
+      what,
+      entry: label,
+      logs: built.logs.map((log) => String(log)).join('; '),
+    });
+  }
+  const code = stripDebugId(await output.text());
+  return {
+    url: `${basePath}/${graphHash(specifier, await map.text())}.js`,
+    code,
+    bytes: new TextEncoder().encode(code).byteLength,
+  };
+}
+
+/**
+ * The app's realtime, from the root or — in a workspace app, where `@ultimat3/realtime` is a
+ * dependency of `apps/<app>` and not of the root (`examples/dummy`) — from the first app that has
+ * it: where its islands resolve it, which is the copy the scripts must match. Resolving from the
+ * root alone built no worker and no boot for such an app, silently.
+ */
+function resolveEntry(root: string, specifier: string): string | undefined {
+  for (const dir of [root, ...appDirs(root)]) {
+    try {
+      return Bun.resolveSync(specifier, dir);
+    } catch {
+      // Not installed here, or a realtime that predates the export: try the next app.
+    }
+  }
+  return undefined;
+}
+
+function appDirs(root: string): readonly string[] {
+  const glob = new Bun.Glob('apps/*/package.json');
+  return [...glob.scanSync({ cwd: root, onlyFiles: true })]
+    .sort()
+    .map((file) => join(root, dirname(file)));
+}
+
+/** The script a build produced, read per request so `x dev` and the container share one route. */
+export type SyncWorkerSource = () => FrameworkScript | undefined;
+
+export function syncWorkerRoutes(source: SyncWorkerSource): readonly Route[] {
+  return [scriptRoute(SYNC_WORKER_BASE_PATH, 'assets.sync-worker', 'sync worker', source)];
+}
+
+export function pageBootRoutes(source: SyncWorkerSource): readonly Route[] {
+  return [scriptRoute(PAGE_BOOT_BASE_PATH, 'assets.page-boot', 'page boot', source)];
+}
+
+function scriptRoute(
+  basePath: string,
+  name: string,
+  what: string,
+  source: SyncWorkerSource,
+): Route {
+  return {
+    method: 'GET',
+    path: `${basePath}/:file`,
+    meta: { name, auth: 'public', tags: ['assets'] },
+    handler: (request: UltimateRequest): Response => {
+      const script = source();
+      if (script === undefined || script.url !== request.pathname) {
+        return json(
+          {
+            ok: false,
+            error: {
+              code: 'X_ROUTE_NOT_FOUND',
+              cause: `no ${what} is built at ${request.pathname} — the document that named it was rendered against another build`,
+              fix: `reload the page — this process serves only the ${what} it built`,
+            },
+          },
+          { status: 404 },
+        );
+      }
+      return applyCacheHeaders(
+        new Response(script.code, { headers: { 'content-type': 'text/javascript' } }),
+        { mode: 'immutable' },
+      );
+    },
+  };
+}

package/src/workspace-graph.ts

@@ -5,9 +5,9 @@
 
 import { join } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
+import { scanAllImports } from './import-scan';
 import type { Finding } from './output';
 import { eachSourceFile, isGenerated, isTest, isVendored } from './source-files';
-import { maskLiterals } from './ts-scan';
 
 export interface WorkspaceNode {
   /** package.json "name". */
@@ -144,43 +144,20 @@ export function packageOfSpecifier(specifier: string): string | undefined {
 }
 
 /**
- * Every form that names a module: `… from '…'`, a bare `import '…'`, `import('…')`, `require('…')`.
- * `from` is matched only where a quote follows it directly, so `from<Row>('posts', …)` — the query
- * builder, which reads exactly like an import — cannot be one.
+ * Every package a source file imports, deduplicated, in first-appearance order — type-only imports
+ * 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.
  */
-const IMPORT_FORM =
-  /(?:\bfrom\s*|\bimport\s*\(\s*|\brequire\s*\(\s*|(?:^|[;{])\s*import\s+)['"]([^'"]*)['"]/g;
-
-/**
- * Every package a source file imports, deduplicated, in first-appearance order.
- *
- * Read from the MASKED text, because a generator's template literal holds whole programs: every
- * `templates/*.ts` here emits `import … from '@ultimat3/ui'` as a string, and a scan that read
- * those would bill the CLI for the imports of the app it writes. The line a masked hit falls on is
- * then re-read from the real source — the specifier itself is what masking blanks.
- */
-export function importedPackages(source: string): readonly string[] {
-  const masked = maskLiterals(source).split('\n');
-  const lines = source.split('\n');
+export function importedPackages(source: string, path = 'source.ts'): readonly string[] {
   const packages = new Set<string>();
-  for (const [index, maskedLine] of masked.entries()) {
-    const line = lines[index];
-    // `matchAll` clones the regex, so the shared `lastIndex` is never carried between lines.
-    if (line === undefined || [...maskedLine.matchAll(IMPORT_FORM)].length === 0) continue;
-    for (const match of line.matchAll(IMPORT_FORM)) {
-      const name = packageOfSpecifier(match[1] ?? '');
-      if (name !== undefined) packages.add(name);
-    }
+  for (const specifier of scanAllImports({ path, source })) {
+    const name = packageOfSpecifier(specifier);
+    if (name !== undefined) packages.add(name);
   }
   return [...packages];
 }
 
-/**
- * Borrowed, not twinned: `X_APP_PACKAGE_INVALID` already means "this package.json supplies no
- * usable name", and a workspace manifest is that same file one directory down. `bun pm pkg set`
- * is not the fix here — it parses the file it edits, so it fails on exactly the input this
- * reports.
- */
 export const unreadableWorkspaceFinding = (path: string): Finding => ({
   code: 'X_APP_PACKAGE_INVALID',
   cause: `${path} is claimed by the root "workspaces" globs and supplies no readable "name"`,
@@ -228,7 +205,7 @@ export async function checkWorkspaceDependencies(root: string): Promise<readonly
     if (isTest(path) || isGenerated(path)) continue;
     const owner = owners.find((node) => path.startsWith(`${node.dir}/`));
     if (owner === undefined) continue;
-    for (const name of importedPackages(await Bun.file(join(root, path)).text())) {
+    for (const name of importedPackages(await Bun.file(join(root, path)).text(), path)) {
       const target = byName.get(name);
       if (target === undefined || target.name === owner.name) continue;
       if (owner.dependencies.includes(target.name)) continue;