@ultimat3/cli 22.15.0 → 24.0.0

package/src/app-permissions-borrowed.ts

@@ -0,0 +1,129 @@
+// The `policy` step's provenance question: every permission the app's OWN actions, queries and
+// routes require is one the app ITSELF declares. `defineAdmin()` declares `<entity>:read|write|
+// delete` for every mounted entity, so an app rule naming one passed in the web process and threw
+// X_PERMISSION_UNKNOWN in any process that never mounted the admin — with nothing saying so.
+
+// why: Bun ships no path API, and `relative` renders a frame's absolute path against the app root.
+import { relative } from 'node:path';
+import { listActions } from '@ultimat3/action';
+import { type Policy, permissionDeclarationSites, policyPermissions } from '@ultimat3/policy';
+import { listQueries } from '@ultimat3/query';
+import { routeEntries } from '@ultimat3/render';
+import { frameFile, siteFile } from './app-permissions-site';
+import type { Finding } from './output';
+
+/** One permission one app declaration requires. */
+export interface AppRule {
+  readonly permission: string;
+  /** `action createPost`, `query postList`, or the route file. */
+  readonly by: string;
+}
+
+/** An app rule whose permission no app module declares, and the file that did declare it. */
+export interface BorrowedPermission extends AppRule {
+  /**
+   * Root-relative paths of EVERY declaring module (`node_modules/…` or `../…`), distinct and
+   * sorted: naming only the first told the reader one package declared it when two did.
+   */
+  readonly from: readonly string[];
+}
+
+/**
+ * EVERY permission in each tree, composites included — unlike the grant question, which judges
+ * only a bare `can()`: an `or()` branch is still a `can()` that asserted its name, so it needs the
+ * app's own declaration as much as a bare one does. A screen the admin MOUNTS is not here: those
+ * are the package's rules, and declaring their names is the package's job.
+ */
+export function appRules(): readonly AppRule[] {
+  const named = (by: string, policy: Policy<unknown, unknown>): readonly AppRule[] =>
+    policyPermissions(policy).map((permission) => ({ permission, by }));
+  return [
+    ...listActions().flatMap((target) => named(`action ${target.name}`, target.policy)),
+    ...listQueries().flatMap((target) => named(`query ${target.name}`, target.policy)),
+    ...routeEntries().flatMap((entry) => {
+      const permission = entry.config.policy?.permission;
+      return permission === undefined ? [] : [{ permission, by: entry.file }];
+    }),
+  ];
+}
+
+/** An app module's root-relative path, or `undefined` for a dependency's or an unreadable frame. */
+const appFile = (root: string, site: string): string | undefined => {
+  const file = siteFile(root, site);
+  return file === undefined || file.split('/').includes('node_modules') ? undefined : file;
+};
+
+/**
+ * Provenance by the declaring module's PATH, which is where the call ran — never by the name's
+ * shape: `posts:read` is the same string whether `defineAdmin()` or the app declared it. A name
+ * with any unreadable site is one whose origin nobody can state, so it is not judged — and that
+ * covers an UNKNOWN name too, which has no site at all: it is X_PERMISSION_UNKNOWN's, asked first,
+ * and a second finding would be a second instruction for one fault.
+ */
+export function borrowedPermissions(
+  root: string,
+  rules: readonly AppRule[] = appRules(),
+  declaredAt: Readonly<Record<string, readonly string[]>> = permissionDeclarationSites(),
+): readonly BorrowedPermission[] {
+  const found = new Map<string, BorrowedPermission>();
+  for (const rule of rules) {
+    const sites = Object.hasOwn(declaredAt, rule.permission) ? declaredAt[rule.permission] : [];
+    const files = (sites ?? []).map(frameFile);
+    if (files.length === 0 || files.some((file) => file === undefined)) continue;
+    if ((sites ?? []).some((site) => appFile(root, site) !== undefined)) continue;
+    const from = [
+      ...new Set(
+        files.flatMap((file) =>
+          file === undefined ? [] : [relative(root, file).replaceAll('\\', '/')],
+        ),
+      ),
+    ].sort();
+    found.set(`${rule.permission}\u0000${rule.by}`, { ...rule, from });
+  }
+  return [...found.values()].sort((a, b) =>
+    a.permission === b.permission
+      ? a.by.localeCompare(b.by)
+      : a.permission.localeCompare(b.permission),
+  );
+}
+
+/**
+ * The app file its permissions are declared in — where the missing name is added. Read off the
+ * recorded sites, never a scaffold path; none under the root is `undefined`, never a guess.
+ */
+export function permissionsFile(root: string): string | undefined {
+  for (const sites of Object.values(permissionDeclarationSites())) {
+    for (const site of sites) {
+      const file = appFile(root, site);
+      if (file !== undefined) return file;
+    }
+  }
+  return undefined;
+}
+
+/** A TS string literal for the name — quoted the house way unless the name itself needs escaping. */
+const literal = (name: string): string =>
+  /^[\w:.*-]+$/.test(name) ? `'${name}'` : JSON.stringify(name);
+
+export function borrowedFinding(
+  entry: BorrowedPermission,
+  declaredIn: string | undefined,
+): Finding {
+  const [only, ...more] = entry.from;
+  const declarers =
+    more.length === 0 ? `only ${only} declares it` : `only ${entry.from.join(', ')} declare it`;
+  const where =
+    declaredIn === undefined
+      ? 'paste this call into an app module'
+      : `paste this call into ${declaredIn} (definePermissions() merges, so a second call is fine)`;
+  const finding: Finding = {
+    code: 'X_PERMISSION_BORROWED',
+    cause:
+      `${entry.by} requires ${literal(entry.permission)}, and ${declarers} — no app module does, ` +
+      "so the rule holds only in a process that ran that package's declaration (defineAdmin()) " +
+      `first; ${where}, then x verify --only policy`,
+    // A call to paste, never prose: `add …` read as a command answered `add: command not found`.
+    fix: `definePermissions([${literal(entry.permission)}])`,
+  };
+  return declaredIn === undefined ? finding : { ...finding, at: declaredIn };
+}

package/src/app-permissions-site.ts

@@ -0,0 +1,24 @@
+// Single responsibility: a declaration site — a stack FRAME `@ultimat3/policy` recorded for a
+// `defineRoles()` or `definePermissions()` call — reduced to the file it names, absolute or
+// app-root-relative. Both `policy` step questions key their findings by it.
+
+// why: Bun ships no path API, and `relative` is what turns a stack frame's absolute path into
+// the app-root-relative one every finding is keyed by.
+import { relative } from 'node:path';
+
+/** The absolute source path a frame (`at foo (/abs/path.ts:3:1)`) names, or `undefined`. */
+export function frameFile(site: string): string | undefined {
+  return /\(?(\/[^():]+\.[cm]?tsx?)(?::\d+)?(?::\d+)?\)?/.exec(site)?.[1];
+}
+
+/**
+ * The frame's file relative to the app root, or `undefined` outside it: a locator nobody can act on
+ * is worse than none. The frame is the only place the declaring module's name exists by the time
+ * the declaration runs.
+ */
+export function siteFile(root: string, site: string): string | undefined {
+  const absolute = frameFile(site);
+  if (absolute === undefined) return undefined;
+  const rel = relative(root, absolute).replaceAll('\\', '/');
+  return rel.startsWith('..') || rel.length === 0 ? undefined : rel;
+}

package/src/app-reload-graph.ts

@@ -20,9 +20,10 @@
 // the old instance of what changed (a slice's service under its query, an admin page's view under
 // `defineAdmin`), so only a new process serves the save. `x dev` restarts on it (`dev-supervisor.ts`).
 
-// why: Bun ships no path API; import specifiers resolve against the importing file's directory.
-import { dirname, resolve } from 'node:path';
+// why: Bun ships no path API; the app root is compared as an absolute path.
+import { resolve } from 'node:path';
 import { registeredStylesheets } from '@ultimat3/render/server';
+import { resolvedImports } from './module-imports';
 import { hasPathSegment } from './path-segments';
 
 type Kind = 'script' | 'style' | 'data';
@@ -91,11 +92,6 @@ const STYLE = /\.(?:s[ac]ss|css)$/;
 const kindOf = (path: string): Kind =>
   SCRIPT.test(path) ? 'script' : STYLE.test(path) ? 'style' : 'data';
 
-const transpilers = {
-  ts: new Bun.Transpiler({ loader: 'ts' }),
-  tsx: new Bun.Transpiler({ loader: 'tsx' }),
-};
-
 const readText = async (path: string): Promise<string | null> => {
   try {
     return await Bun.file(path).text();
@@ -108,29 +104,10 @@ const hashOf = (text: string | null): bigint | null =>
   text === null ? null : BigInt(Bun.hash.wyhash(text));
 
 /** The in-app files `source` imports — a package under `node_modules` is not the app's to reload. */
-function importsOf(path: string, source: string, root: string): string[] {
-  let specifiers: readonly { readonly path: string }[];
-  try {
-    const transpiler = path.endsWith('x') ? transpilers.tsx : transpilers.ts;
-    specifiers = transpiler.scanImports(source);
-  } catch {
-    // A file that will not parse imports nothing yet; its own hash still changes on the fix.
-    return [];
-  }
-  const found: string[] = [];
-  for (const { path: specifier } of specifiers) {
-    let target: string;
-    try {
-      target = Bun.resolveSync(specifier, dirname(path));
-    } catch {
-      continue;
-    }
-    if (target.startsWith(`${root}/`) && !hasPathSegment(target, 'node_modules')) {
-      found.push(target);
-    }
-  }
-  return found;
-}
+const importsOf = (path: string, source: string, root: string): string[] =>
+  resolvedImports(path, source, 'referenced').filter(
+    (target) => target.startsWith(`${root}/`) && !hasPathSegment(target, 'node_modules'),
+  );
 
 function link(from: string, to: string): void {
   let set = importers.get(to);

package/src/app-transport.ts

@@ -0,0 +1,219 @@
+// The browser-transport rule (`browser-transport.ts`) over ONE APP: what `x verify`'s `boundaries`
+// step reports for a raw `fetch(` in an island. Built in rather than a file in `guards/` — a rule
+// an app can delete is a rule the next agent deletes.
+//
+// It reads nothing `readAppSources` already read. The islands and the surface files arrive in
+// memory; the only new I/O is the app's `tsconfig.json`, its workspace manifests, the installed
+// `@ultimat3/*` manifests (which name the browser entries), and — lazily — the files of the app's
+// own `packages/*` an island actually imports. An app with no island pays for none of it.
+//
+// The walk STOPS at an installed package: `@ultimat3/core`'s `clientTransport`, realtime's socket
+// and storage's upload client are the three seams, they live in `node_modules`, and they are
+// trusted rather than re-read — in an app, no file may open its own connection.
+
+// why: `ClosureHost.read` is synchronous (the walk is a plain loop) and `Bun.file().text()` is not.
+import { readFileSync } from 'node:fs';
+// why: Bun ships no path API; this reaches a file on disk with the host's separator.
+import { join } from 'node:path';
+import { isJsonObject } from '@ultimat3/core';
+import type { SourceFile } from './app-boundaries';
+import type { FindingContext } from './browser-transport';
+import {
+  barrelFinding,
+  browserEntries,
+  bypassFinding,
+  checkBrowserTransport,
+} from './browser-transport';
+import type { ClosureHost } from './import-closure';
+import type { Finding } from './output';
+import { hasPathSegment } from './path-segments';
+import { serverBarrels } from './server-barrels';
+import type { TransportShape } from './transport-calls';
+
+/** What an app is told may hold each shape: the framework's function, never a file of its own. */
+const HOLDER: ReadonlyMap<TransportShape, string> = new Map([
+  ['fetch', "@ultimat3/core's clientTransport"],
+  ['websocket', "@ultimat3/realtime's page socket"],
+  ['xhr', "@ultimat3/storage's uploadFile"],
+]);
+
+const CONTEXT: FindingContext = {
+  holder: (shape) => HOLDER.get(shape),
+  rerun: 'x verify --only boundaries --json',
+};
+
+/** One `paths` row or one `exports` row, as a specifier pattern: at most one `*` on each side. */
+interface Pattern {
+  readonly head: string;
+  readonly tail: string;
+  readonly wild: boolean;
+  /** Root-relative, `*` still in place. */
+  readonly target: string;
+}
+
+const patternOf = (key: string, target: string): Pattern => {
+  const star = key.indexOf('*');
+  return star < 0
+    ? { head: key, tail: '', wild: false, target }
+    : { head: key.slice(0, star), tail: key.slice(star + 1), wild: true, target };
+};
+
+/** The path `spec` names under `pattern`, or `undefined` when the pattern is not about it. */
+function applied(pattern: Pattern, spec: string): string | undefined {
+  if (!pattern.wild) return spec === pattern.head ? pattern.target : undefined;
+  if (!spec.startsWith(pattern.head) || !spec.endsWith(pattern.tail)) return undefined;
+  if (spec.length < pattern.head.length + pattern.tail.length) return undefined;
+  const middle = spec.slice(pattern.head.length, spec.length - pattern.tail.length);
+  return pattern.target.replace('*', middle);
+}
+
+const posix = (path: string): string => path.split('\\').join('/').replace(/^\.\//, '');
+
+/** A manifest or a tsconfig, or `undefined`: absent and unreadable both mean "says nothing". */
+async function readObject(path: string): Promise<Readonly<Record<string, unknown>> | undefined> {
+  const file = Bun.file(path);
+  if (!(await file.exists())) return undefined;
+  try {
+    // JSONC: a tsconfig may carry comments and trailing commas, and a strict parse would turn one
+    // into "this app has no aliases" — every island's imports unresolved, the rule silently blind.
+    const parsed: unknown = Bun.JSONC.parse(await file.text());
+    return isJsonObject(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** `compilerOptions.paths` of the app's root tsconfig — how its own packages are spelled. */
+async function tsconfigPatterns(root: string): Promise<readonly Pattern[]> {
+  const options = (await readObject(join(root, 'tsconfig.json')))?.['compilerOptions'];
+  const paths = isJsonObject(options) ? options['paths'] : undefined;
+  if (!isJsonObject(paths)) return [];
+  return Object.entries(paths).flatMap(([key, targets]) => {
+    const first: unknown = Array.isArray(targets) ? targets[0] : undefined;
+    return typeof first === 'string' ? [patternOf(key, posix(first))] : [];
+  });
+}
+
+interface Workspaces {
+  /** Every specifier a workspace package publishes, as a pattern onto its file. */
+  readonly patterns: readonly Pattern[];
+  /** Package name → its directory, for "is this file inside the package that barrel names". */
+  readonly dirs: ReadonlyMap<string, string>;
+}
+
+/** The app's own `apps/*` and `packages/*`, by the `name` and `exports` each manifest declares. */
+async function workspaces(root: string): Promise<Workspaces> {
+  const patterns: Pattern[] = [];
+  const dirs = new Map<string, string>();
+  for await (const manifest of new Bun.Glob('{apps,packages}/*/package.json').scan({ cwd: root })) {
+    const dir = posix(manifest).split('/').slice(0, 2).join('/');
+    const parsed = await readObject(join(root, manifest));
+    const name = parsed?.['name'];
+    if (typeof name !== 'string') continue;
+    dirs.set(name, dir);
+    const exports = isJsonObject(parsed?.['exports']) ? parsed['exports'] : {};
+    for (const [sub, target] of Object.entries(exports)) {
+      if (typeof target !== 'string') continue;
+      const spec = sub === '.' ? name : `${name}${sub.slice(1)}`;
+      patterns.push(patternOf(spec, `${dir}/${posix(target)}`));
+    }
+  }
+  return { patterns, dirs };
+}
+
+const INSTALLED = [
+  'node_modules/@ultimat3/*/package.json',
+  // A workspace install may leave a package beside the workspace that asked for it.
+  '{apps,packages}/*/node_modules/@ultimat3/*/package.json',
+];
+
+/** Every specifier the installed framework publishes — what `serverBarrels` derives its map from. */
+async function installedSpecifiers(root: string): Promise<ReadonlySet<string>> {
+  const specifiers = new Set<string>();
+  for (const pattern of INSTALLED) {
+    const found = new Bun.Glob(pattern).scan({ cwd: root, followSymlinks: true });
+    for await (const manifest of found) {
+      const parsed = await readObject(join(root, manifest));
+      const name = parsed?.['name'];
+      if (typeof name !== 'string') continue;
+      const exports = isJsonObject(parsed?.['exports']) ? parsed['exports'] : {};
+      for (const sub of Object.keys(exports)) {
+        if (!sub.includes('*')) specifiers.add(sub === '.' ? name : `${name}${sub.slice(1)}`);
+      }
+    }
+  }
+  return specifiers;
+}
+
+const SUFFIXES = ['', '.ts', '.tsx', '/index.ts', '/index.tsx'];
+
+/**
+ * The closure's view of the app: the surface files from memory, a file of the app's own
+ * `packages/*` from disk the first time an island reaches it, and nothing under `node_modules` —
+ * a relative import that climbs into an installed package is still past the boundary.
+ */
+function hostOf(
+  root: string,
+  sources: ReadonlyMap<string, string>,
+  patterns: readonly Pattern[],
+): ClosureHost {
+  const disk = new Map<string, string | undefined>();
+  const read = (path: string): string | undefined => {
+    const held = sources.get(path);
+    if (held !== undefined) return held;
+    if (!/\.tsx?$/.test(path) || hasPathSegment(path, 'node_modules')) return undefined;
+    if (!disk.has(path)) {
+      try {
+        disk.set(path, readFileSync(join(root, path), 'utf8'));
+      } catch {
+        disk.set(path, undefined);
+      }
+    }
+    return disk.get(path);
+  };
+  const alias = (spec: string): string | undefined => {
+    for (const pattern of patterns) {
+      const base = applied(pattern, spec);
+      if (base === undefined) continue;
+      for (const suffix of SUFFIXES) {
+        if (read(`${base}${suffix}`) !== undefined) return `${base}${suffix}`;
+      }
+    }
+    return undefined;
+  };
+  return { read, alias };
+}
+
+/**
+ * `X_BROWSER_TRANSPORT_BYPASS` and `X_BROWSER_SERVER_BARREL` for the app at `root`, over the
+ * sources `readAppSources` already holds.
+ */
+export async function appTransportFindings(
+  root: string,
+  files: readonly SourceFile[],
+): Promise<readonly Finding[]> {
+  const sources = new Map(files.map((file) => [file.path, file.source]));
+  const entries = browserEntries(sources);
+  if (entries.length === 0) return [];
+  const [paths, own, installed] = await Promise.all([
+    tsconfigPatterns(root),
+    workspaces(root),
+    installedSpecifiers(root),
+  ]);
+  const published = [...installed, ...own.patterns.filter((p) => !p.wild).map((p) => p.head)];
+  const { bypasses, barrels } = checkBrowserTransport({
+    entries,
+    // The tsconfig first: it is what the app's own typecheck resolves through.
+    host: hostOf(root, sources, [...paths, ...own.patterns]),
+    seams: new Map(),
+    barrels: serverBarrels(published),
+    ownsBarrel: (file, barrel) => {
+      const dir = own.dirs.get(barrel);
+      return dir !== undefined && file.startsWith(`${dir}/`);
+    },
+  });
+  return [
+    ...bypasses.map((bypass) => bypassFinding(bypass, CONTEXT)),
+    ...barrels.map((barrel) => barrelFinding(barrel, CONTEXT)),
+  ];
+}

package/src/boundary-findings.ts

@@ -3,7 +3,9 @@
 // was another command to run for the real one (plan 101 slice 11 j). The planner is the same one
 // `x fix boundary` prints from, so the gate and the command cannot disagree about the cut.
 
+import type { SourceFile } from './app-boundaries';
 import { appImportGraph, checkImportRules, readAppSources } from './app-boundaries';
+import { appTransportFindings } from './app-transport';
 import { planBoundaryCuts } from './boundary-cuts';
 import type { Finding } from './output';
 
@@ -29,8 +31,18 @@ export function withCutEdits(
   });
 }
 
-/** Read the app's sources once, check them, and hand back findings whose fix is the edit. */
-export async function appBoundaryFindings(root: string): Promise<readonly Finding[]> {
-  const files = await readAppSources(root);
-  return withCutEdits(checkImportRules(files), appImportGraph(files));
+/**
+ * Read the app's sources once, check them, and hand back findings whose fix is the edit. The
+ * browser-transport findings come from the same read and already carry their own edit.
+ */
+export async function appBoundaryFindings(
+  root: string,
+  /** The app's sources when the caller has already read them — the gate step reads them once. */
+  read?: readonly SourceFile[],
+): Promise<readonly Finding[]> {
+  const files = read ?? (await readAppSources(root));
+  return [
+    ...withCutEdits(checkImportRules(files), appImportGraph(files)),
+    ...(await appTransportFindings(root, files)),
+  ];
 }

package/src/browser-transport.ts

@@ -0,0 +1,160 @@
+// The browser has ONE HTTP function and ONE socket, as a rule over a file tree: a raw `fetch(`,
+// `new WebSocket(`, `new XMLHttpRequest(` or `new EventSource(` in browser-reachable code skips
+// `@ultimat3/core`'s `clientTransport` — credentials, the idempotency header, the record envelope,
+// the principal fence — so its rows never reach the page's store and it keeps running for the
+// previous principal after a sign-out. A package's SERVER BARREL in that closure is refused too.
+//
+// BROWSER-REACHABLE is derived, never listed: every `*.island.tsx`, every module that names the
+// client seam itself, and the import closure of each, followed name by name through barrels
+// (`import-closure.ts`). Pure over the tree its caller read — `app-transport.ts` reads an app's,
+// `scripts/browser-transport.ts` this repository's.
+//
+// WHAT IT CANNOT SEE: a browser module that neither is an island, nor names the seam, nor is
+// imported by either; a request made inside an installed package (the walk ends at the package
+// boundary); a fetch reached through a computed member (`globalThis['fetch']`); and a bare
+// `fetch(` in a file that also binds a local `fetch` (`bindsFetch`). A floor, not a proof.
+
+import { ERROR_DOCS_URL, maskLiterals } from '@ultimat3/core';
+import { commentSafe } from './comment-safe';
+import type { ClosureHost } from './import-closure';
+import { importClosure } from './import-closure';
+import type { Finding } from './output';
+import type { BarrelImport } from './server-barrels';
+import { barrelImports } from './server-barrels';
+import { isTest } from './source-files';
+import type { TransportCall, TransportShape } from './transport-calls';
+import { transportCalls } from './transport-calls';
+
+export interface Bypass extends TransportCall {
+  readonly file: string;
+}
+
+export interface ServerBarrel extends BarrelImport {
+  readonly file: string;
+}
+
+export const isIsland = (path: string): boolean => path.endsWith('.island.tsx');
+
+/** A module naming the page's client seam is browser code by its own statement. */
+const NAMES_SEAM = /\b(?:clientTransport|pageClient)\s*[(<]/;
+
+/**
+ * Where the closure starts: every island, plus every module `namesSeam` admits that calls the seam
+ * itself. Masked before the test: a template that EMITS `clientTransport(` is not browser code.
+ */
+export function browserEntries(
+  files: ReadonlyMap<string, string>,
+  namesSeam: (path: string) => boolean = () => true,
+): readonly string[] {
+  return [...files.entries()]
+    .filter(([path, source]) => {
+      if (isTest(path)) return false;
+      if (isIsland(path)) return true;
+      // The raw text first: masking is a pass over every character, and almost no file names it.
+      return namesSeam(path) && NAMES_SEAM.test(source) && NAMES_SEAM.test(maskLiterals(source));
+    })
+    .map(([path]) => path)
+    .sort();
+}
+
+export interface TransportInput {
+  readonly entries: readonly string[];
+  /** Reads a file and resolves a bare specifier; `undefined` from either ends the walk there. */
+  readonly host: ClosureHost;
+  /**
+   * Shape → the ONE file in this tree allowed to hold it. Empty for an app: the seams are the
+   * framework's and live in `node_modules`, past the boundary the walk stops at.
+   */
+  readonly seams: ReadonlyMap<TransportShape, string>;
+  /** Files whose realm is not a page — a service worker has no store and no principal fence. */
+  readonly exempt?: ReadonlySet<string>;
+  /** Server barrel → the browser entry that replaces it (`serverBarrels`). */
+  readonly barrels: ReadonlyMap<string, string>;
+  /** A package's own modules may import its own barrel; only a FOREIGN import pays for it. */
+  readonly ownsBarrel?: (file: string, barrel: string) => boolean;
+}
+
+/** The whole rule over a tree, pure. */
+export function checkBrowserTransport(input: TransportInput): {
+  readonly reachable: readonly string[];
+  readonly bypasses: readonly Bypass[];
+  readonly barrels: readonly ServerBarrel[];
+} {
+  const reachable = importClosure(input.host, input.entries);
+  const bypasses: Bypass[] = [];
+  const barrels: ServerBarrel[] = [];
+  for (const file of reachable) {
+    if (input.exempt?.has(file) === true) continue;
+    const source = input.host.read(file) ?? '';
+    for (const call of transportCalls(source)) {
+      if (input.seams.get(call.shape) === file) continue;
+      bypasses.push({ ...call, file });
+    }
+    for (const found of barrelImports(source, input.barrels)) {
+      if (input.ownsBarrel?.(file, found.barrel) === true) continue;
+      barrels.push({ ...found, file });
+    }
+  }
+  return { reachable, bypasses, barrels };
+}
+
+/**
+ * What to write instead, per shape — each a line that runs once its placeholder is named. A raw
+ * request does not say which of these it is, so `fetch` lists the four it can be.
+ */
+const REPLACEMENT: ReadonlyMap<TransportShape, string> = new Map([
+  [
+    'fetch',
+    "an action: `await browserClient.<action>(input)` (rpc<Api['actions']> in apps/web/shared/browser-client.ts); a read: `useQuery(<QUERY_REF>, input)` from '@ultimat3/realtime'; a file: `await uploadFile({ file, grant })` from '@ultimat3/storage'; anything else: `await clientTransport({ method: 'GET', url })` from '@ultimat3/core/page'",
+  ],
+  [
+    'websocket',
+    "`useQuery(<QUERY_REF>, input)` for rows or `useChannel(<CHANNEL_REF>, params, { onEvent })` for events, both from '@ultimat3/realtime' — the page has one socket and it is the framework's",
+  ],
+  [
+    'xhr',
+    "an upload with progress: `await uploadFile({ file, grant, onProgress })` from '@ultimat3/storage'; anything else: `await clientTransport({ method: 'GET', url })` from '@ultimat3/core/page'",
+  ],
+  [
+    'eventsource',
+    "`useQuery(<QUERY_REF>, input)` or `useChannel(<CHANNEL_REF>, params, { onEvent })` from '@ultimat3/realtime' — pushed frames arrive on the page's one socket",
+  ],
+]);
+
+export interface FindingContext {
+  /** Who may hold `shape` instead — a file in a repo, the framework's function in an app. */
+  readonly holder: (shape: TransportShape) => string | undefined;
+  /** The command that re-reads the tree: the gate's step in an app, the script in this repo. */
+  readonly rerun: string;
+}
+
+/** `file:line` for a message: the path is the scanned tree's, so it is escaped before it is quoted. */
+const siteOf = (site: { readonly file: string; readonly line: number }): string =>
+  `${commentSafe(site.file)}:${site.line}`;
+
+/**
+ * One runnable line, the edit behind a `#` — the shape `app-boundaries.ts` gives every fix. The
+ * command re-reads the tree; the comment is the edit, because only the finding knows the line.
+ */
+export function bypassFinding(bypass: Bypass, context: FindingContext): Finding {
+  const holder = context.holder(bypass.shape);
+  const site = siteOf(bypass);
+  return {
+    code: 'X_BROWSER_TRANSPORT_BYPASS',
+    at: `${bypass.file}:${bypass.line}`,
+    cause: `${site} calls ${bypass.spelled} in browser-reachable code; ${holder === undefined ? 'no module may' : `only ${holder} may`}, so this request skips the page's record store, idempotency header and principal fence`,
+    fix: `${context.rerun}   # after replacing ${bypass.spelled} at ${site} with ${REPLACEMENT.get(bypass.shape) ?? ''}`,
+    docs: ERROR_DOCS_URL,
+  };
+}
+
+export function barrelFinding(site: ServerBarrel, context: FindingContext): Finding {
+  const at = siteOf(site);
+  return {
+    code: 'X_BROWSER_SERVER_BARREL',
+    at: `${site.file}:${site.line}`,
+    cause: `${at} imports ${site.barrel} in browser-reachable code; that barrel is the package's server half, and ${site.entry} is the entry it publishes for a browser`,
+    fix: `${context.rerun}   # after changing the import at ${at} from '${site.barrel}' to '${site.entry}'`,
+    docs: ERROR_DOCS_URL,
+  };
+}