@ultimat3/cli 22.15.0 → 23.0.0

package/src/templates/scaffold-site.ts

@@ -45,7 +45,7 @@ export const config = defineRoute({
   }),
 });
 
-export function HomePage() {
+export function Page() {
   const t = useT();
 
   return (
@@ -259,23 +259,49 @@ const siteStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
 }
 `;
 
-const sitePageTest =
-  (): string => `// The landing page ships zero JS and declares its metadata. Both are promises the file makes in
-// its config, and both are the kind that rot silently when someone adds one import.
-import { metaContextFor, routeDataFor } from '@ultimat3/render';
-import { expect, unitTest } from '@ultimat3/testing';
-import { config } from './page';
-
-// The same two objects a render builds: \`routeDataFor\` resolves the route's data once, and
-// \`metaContextFor\` wraps it the way every render mode wraps it before calling \`meta\`.
-const ctx = { params: {}, url: 'https://example.test/' };
-
-unitTest('the landing page ships zero JS and declares metadata', async () => {
-  expect(config.render).toBe('static');
-  expect(config.hydrate).toBe('never');
-  expect(config.budget.js).toBe('0kb');
-  const meta = await config.meta(metaContextFor(ctx, await routeDataFor(config, ctx)));
-  expect(meta.title ?? '').not.toBe('');
+const sitePageTest = (
+  app: NameSet,
+): string => `// The landing page, rendered: what a visitor reads, where its two calls to action lead, and that
+// it ships zero JS. Each is a promise the file makes, and each rots silently on one import.
+${sortedImports([
+  `import { useT } from '@${app.kebab}/i18n';`,
+  "import { expect, renderRoute, unitTest } from '@ultimat3/testing';",
+])}
+import * as page from './page';
+
+const url = 'https://example.test/';
+
+unitTest('the landing page says what the catalog says, under one h1', async () => {
+  const t = useT();
+  const view = await renderRoute(page, { url });
+  expect(view.html.match(/<h1\\b/g)).toHaveLength(1);
+  expect(view.text).toContain(t('site.home.headline'));
+  expect(view.text).toContain(t('site.home.lede'));
+  // Three facts, each a heading and a body.
+  expect(view.html.match(/<h2\\b/g)).toHaveLength(3);
+  for (const key of ['site.home.f1Title', 'site.home.f2Body', 'site.home.f3Title'] as const) {
+    expect(view.text).toContain(t(key));
+  }
+  // A key no catalog holds renders as \u27e6key\u27e7 — to a visitor, with every other check green.
+  expect(view.text).not.toContain('\u27e6');
+});
+
+unitTest('its two calls to action lead into the product', async () => {
+  const view = await renderRoute(page, { url });
+  const hrefs = [...view.html.matchAll(/<a\\b[^>]*href="([^"]*)"/g)].map((match) => match[1]);
+  expect(hrefs).toEqual(['/dashboard', '/admin']);
+});
+
+unitTest('it ships zero JS and declares the metadata a search result renders', async () => {
+  const t = useT();
+  const view = await renderRoute(page, { url });
+  expect(page.config.render).toBe('static');
+  expect(page.config.hydrate).toBe('never');
+  expect(page.config.budget.js).toBe('0kb');
+  // What the render DID, beside what the config declares: no island left the page.
+  expect(view.islands).toEqual([]);
+  expect(view.meta.title).toBe(t('site.home.title'));
+  expect(view.meta.description).toBe(t('site.home.description'));
 });
 `;
 
@@ -283,5 +309,5 @@ unitTest('the landing page ships zero JS and declares metadata', async () => {
 export const siteFiles = (app: NameSet): readonly GeneratedFile[] => [
   { path: 'apps/web/site/page.tsx', contents: sitePage(app) },
   { path: 'apps/web/site/page.module.scss', contents: siteStyle() },
-  { path: 'apps/web/site/page.test.ts', contents: sitePageTest() },
+  { path: 'apps/web/site/page.test.ts', contents: sitePageTest(app) },
 ];

package/src/templates/scaffold-ui-package.ts

@@ -31,6 +31,23 @@ export function Card(props: CardProps) {
 }
 `;
 
+const uiCardTest =
+  (): string => `// The card, rendered the way a page renders it. What a typecheck cannot see is where a prop
+// lands: the title is the card's heading, and the children follow it inside the same section.
+import { expect, renderView, unitTest } from '@ultimat3/testing';
+import { Card } from './card';
+
+unitTest('the card puts its title in a heading and its children after it', async () => {
+  const view = await renderView(Card, { title: 'Usage', children: 'body copy' });
+  expect(view.html).toMatch(/^<section[^>]*><h2[^>]*>Usage<\\/h2>body copy<\\/section>$/);
+});
+
+unitTest('a card with no children is its heading and nothing else', async () => {
+  const view = await renderView(Card, { title: 'Empty' });
+  expect(view.text).toBe('Empty');
+});
+`;
+
 const uiCardStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
 
 .card {
@@ -52,5 +69,6 @@ export const uiPackageFiles = (app: NameSet): readonly GeneratedFile[] => [
   ...packageShapeFiles(app, 'ui', DESCRIPTION),
   { path: 'packages/ui/src/index.ts', contents: uiIndex() },
   { path: 'packages/ui/src/card.tsx', contents: uiCard() },
+  { path: 'packages/ui/src/card.test.ts', contents: uiCardTest() },
   { path: 'packages/ui/src/card.module.scss', contents: uiCardStyle() },
 ];

package/src/templates/slice-foundation.ts

@@ -4,6 +4,7 @@
 // none of them, so each emitted TS2307 in any slice a resource had not been run in first.
 
 import { stripComments } from '@ultimat3/core';
+import { adminCatalogFiles } from './admin-catalog';
 import type { FeatureTarget } from './entity';
 import { entityFiles } from './entity';
 import type { GeneratedFile, NameSet } from './naming';
@@ -74,16 +75,24 @@ const ifAbsent = (files: readonly GeneratedFile[]): readonly GeneratedFile[] =>
 export function sliceFoundation(
   target: FeatureTarget,
   needs: readonly SliceModule[],
+  /** Every locale the planted entity's admin labels ship for. Defaults to `['en']`. */
+  locales?: readonly string[],
 ): readonly GeneratedFile[] {
   const feature = names(target.feature);
   const dir = `${target.surfaceDir}/${target.feature}`;
-  return ifAbsent([
-    ...(needs.includes('entity') ? entityFiles(target.feature, target) : []),
-    ...(needs.includes('policy') ? policyFiles(target.feature, target) : []),
-    ...(needs.includes('errors')
-      ? [{ path: `${dir}/errors.ts`, contents: errorsSource(feature) }]
-      : []),
-  ]);
+  return [
+    ...ifAbsent([
+      ...(needs.includes('entity') ? entityFiles(target.feature, target) : []),
+      ...(needs.includes('policy') ? policyFiles(target.feature, target) : []),
+      ...(needs.includes('errors')
+        ? [{ path: `${dir}/errors.ts`, contents: errorsSource(feature) }]
+        : []),
+    ]),
+    // A planted entity joins the typed handle, and an entity in the handle IS an admin screen —
+    // so it gets the labels `x g entity` writes for one, or its nav entry renders a missing-key
+    // marker. A catalog MERGE, never `if-absent`: a key already there keeps the value it has.
+    ...(needs.includes('entity') ? adminCatalogFiles(target.feature, target, locales) : []),
+  ];
 }
 
 /** The exported names an `export { a, b as c }` list declares — `c`, never `b`. */
@@ -117,10 +126,39 @@ export function sliceExports(source: string, name: string): boolean {
   const code = stripComments(source);
   // `(?:async\s+)?` before `function`: an `export async function byId` — every repo function
   // `x g entity` scaffolds — matched neither this nor `listedExports`, so a caller checking for
-  // `byId`/`listByOrg` on a real repo.ts always read `false`. `async` has no meaning before
+  // `byId`/`list` on a real repo.ts always read `false`. `async` has no meaning before
   // `class`/`const`/`let`/`var`/`enum`, so it is scoped to `function` only.
   const declared = new RegExp(
     `\\bexport\\s+(?:abstract\\s+)?(?:class|const|let|var|(?:async\\s+)?function|enum)\\s+${name}\\b`,
   );
   return declared.test(code) || listedExports(code).includes(name);
 }
+
+/** `    title: text({ max: 200 }),` — one column of an entity, as its name and its builder. */
+const COLUMN_LINE = /^ {4}([A-Za-z_$][\w$]*): ([A-Za-z_$][\w$]*)\(/gm;
+
+const columnsOf = (entitySource: string): string =>
+  [...stripComments(entitySource).matchAll(COLUMN_LINE)]
+    .map((match) => `${match[1] ?? ''}: ${match[2] ?? ''}`)
+    .join(', ');
+
+/**
+ * Whether a generated TEST may store a row in this slice: its entity declares exactly the columns
+ * `x g entity` scaffolds for this feature — read off the entity this generator would write, never
+ * a second list — and its `repo.ts`, when one is on disk, still exports `insert`. A slice an author
+ * reshaped has a row this generator cannot spell (one more required column is enough), so its
+ * tests assert the branches that need none and leave the stored-row case to the author.
+ */
+export function sliceTakesScaffoldRow(
+  target: FeatureTarget,
+  sliceEntity: string | undefined,
+  sliceRepo: string | undefined,
+): boolean {
+  if (sliceEntity === undefined) return false;
+  const scaffold = entityFiles(target.feature, target).find((file) =>
+    file.path.endsWith('/entity.ts'),
+  );
+  const wanted = columnsOf(String(scaffold?.contents ?? ''));
+  if (wanted === '' || columnsOf(sliceEntity) !== wanted) return false;
+  return sliceRepo === undefined || sliceExports(sliceRepo, 'insert');
+}

package/src/test-counts.ts

@@ -11,8 +11,21 @@ export interface TestCounts {
   readonly ran: number;
   /** Tests bun reported as skipped or todo, which is the same thing here: they did not run. */
   readonly skipped: number;
+  /**
+   * Errors raised OUTSIDE any test — a `describe` body or a module that threw on load, a failed
+   * hook — which bun counts on a line of their own (`1 error`) beside `0 fail`. Present only when
+   * there were some: the exit code already makes the step red, and without this number the step
+   * line read "12 ran, 0 skipped" over a run whose file never got as far as declaring a test.
+   */
+  readonly errors?: number;
 }
 
+/** Bun's own `N error` / `N errors` summary line: the last one, as `parseBunTest` reads the rest. */
+const errorsIn = (output: string): number => {
+  const last = [...output.matchAll(/^\s*(\d+)\s+errors?\s*$/gm)].at(-1);
+  return last === undefined ? 0 : Number.parseInt(last[1] ?? '0', 10);
+};
+
 /**
  * Summed across every process the step spawned, because a step is one line in the gate whether it
  * ran on one worker or eight.
@@ -26,10 +39,13 @@ export interface TestCounts {
 export const countsOf = (results: readonly ExecResult[]): TestCounts => {
   let ran = 0;
   let skipped = 0;
+  let errors = 0;
   for (const result of results) {
-    const run = parseBunTest(execOutput(result), result.durationMs);
+    const output = execOutput(result);
+    const run = parseBunTest(output, result.durationMs);
     ran += run.passed + run.failed;
     skipped += run.skipped;
+    errors += errorsIn(output);
   }
-  return { ran, skipped };
+  return { ran, skipped, ...(errors === 0 ? {} : { errors }) };
 };

package/src/transport-calls.ts

@@ -0,0 +1,105 @@
+// The four ways browser code opens its own connection, found in ONE file's text: a `fetch(` CALL,
+// `new WebSocket(`, `new XMLHttpRequest(`, `new EventSource(`. Pure, so every false positive the
+// rule has to leave alone is a fixture string. Which file may hold which shape is the caller's.
+
+import { maskLiterals } from '@ultimat3/core';
+import { lineIndex } from './ts-scan';
+
+export type TransportShape = 'fetch' | 'websocket' | 'xhr' | 'eventsource';
+
+export interface TransportCall {
+  readonly shape: TransportShape;
+  readonly line: number;
+  /** What the source spells — `fetch`, `globalThis.fetch`, `WebSocket` — so a finding quotes it. */
+  readonly spelled: string;
+}
+
+const CONSTRUCTED: ReadonlyMap<string, TransportShape> = new Map([
+  ['WebSocket', 'websocket'],
+  ['XMLHttpRequest', 'xhr'],
+  ['EventSource', 'eventsource'],
+]);
+
+/** The global object's three spellings. `server.fetch(` is a method, never the global. */
+const GLOBAL = String.raw`(?:(?:globalThis|window|self)\s*\.\s*)`;
+const NEW = new RegExp(
+  String.raw`\bnew\s+${GLOBAL}?(WebSocket|XMLHttpRequest|EventSource)\s*\(`,
+  'g',
+);
+const FETCH = new RegExp(String.raw`(?<![\w$.])(${GLOBAL}?)fetch\s*\(`, 'g');
+
+/**
+ * Whether the file binds `fetch` itself — a `const`/`let`/`var`/`function`, an import, a
+ * destructured declaration or a parameter — which makes a BARE `fetch(` its own function, not the
+ * page's. `packages/action/src/idempotency-postgres.ts` calls a local `fetch(key)`. Per file, not
+ * per scope: a floor, and the one direction it errs is silence on a file that shadows the global
+ * AND calls it bare. `globalThis.fetch(` is reported regardless.
+ */
+export function bindsFetch(code: string): boolean {
+  return (
+    /\b(?:const|let|var|function)\s+fetch\b/.test(code) ||
+    /\bimport\s+[^;]*\bfetch\b[^;]*\bfrom\b/.test(code) ||
+    /\b(?:const|let|var)\s*\{[^}]*\bfetch\b[^}]*\}\s*=/.test(code) ||
+    /\(\s*(?:[\w$]+\s*(?::[^,()]+)?,\s*)*fetch\s*[?:,)=][^()]*\)\s*(?::[^={;]+)?(?:=>|\{)/.test(
+      code,
+    )
+  );
+}
+
+/**
+ * The `)` closing the `(` at `open`, or `-1`. A bare depth count is exact HERE and only here: the
+ * text is `maskLiterals`' output, where every string, template, comment and regex body is already
+ * blank — so each parenthesis left is code.
+ */
+function closeOf(masked: string, open: number): number {
+  let depth = 0;
+  for (let index = open; index < masked.length; index += 1) {
+    if (masked[index] === '(') depth += 1;
+    else if (masked[index] === ')') {
+      depth -= 1;
+      if (depth === 0) return index;
+    }
+  }
+  return -1;
+}
+
+/** `fetch(req) {` and `fetch(req): Promise<Response> {` define a method; they call nothing. */
+function isDefinition(masked: string, open: number, start: number): boolean {
+  if (/\b(?:function|async|get|set)\s*$/.test(masked.slice(Math.max(0, start - 16), start))) {
+    return true;
+  }
+  const close = closeOf(masked, open);
+  if (close < 0) return false;
+  const after = masked.slice(close + 1).trimStart();
+  return after.startsWith('{') || (after.startsWith(':') && !after.startsWith('::'));
+}
+
+/** A file naming none of the four cannot call one — and masking it is the expensive half. */
+const NAMES_A_TRANSPORT = /fetch|WebSocket|XMLHttpRequest|EventSource/;
+
+export function transportCalls(source: string): readonly TransportCall[] {
+  if (!NAMES_A_TRANSPORT.test(source)) return [];
+  // Comments AND string contents blanked, offsets kept: `'fetch('` in a message is not a call, and
+  // neither is the one a template-literal scaffold emits for somebody else's file.
+  const masked = maskLiterals(source);
+  const lineAt = lineIndex(masked);
+  const calls: TransportCall[] = [];
+  for (const found of masked.matchAll(NEW)) {
+    const name = found[1] ?? '';
+    const shape = CONSTRUCTED.get(name);
+    if (shape !== undefined) calls.push({ shape, line: lineAt(found.index), spelled: name });
+  }
+  const local = bindsFetch(masked);
+  for (const found of masked.matchAll(FETCH)) {
+    const qualified = (found[1] ?? '').length > 0;
+    if (!qualified && local) continue;
+    const open = found.index + found[0].length - 1;
+    if (!qualified && isDefinition(masked, open, found.index)) continue;
+    calls.push({
+      shape: 'fetch',
+      line: lineAt(found.index),
+      spelled: qualified ? `${(found[1] ?? '').replace(/\s/g, '')}fetch` : 'fetch',
+    });
+  }
+  return calls.sort((a, b) => a.line - b.line);
+}

package/src/unscanned-admin.ts

@@ -0,0 +1,54 @@
+// A `defineAdmin()` the app scan never imports. The admin's one home is `apps/admin/app/admin/`
+// (`ADMIN_FILE`, what `x new` and `x g admin:page` write); `apps/<app>/src/` is outside every
+// glob `app-load.ts` imports, so a declaration there never runs and `/admin` is never mounted —
+// silently, which is how the reference app shipped an admin nobody could open.
+
+import { renderFixShellArg, stripComments } from '@ultimat3/core';
+import { describeRoutes } from '@ultimat3/render';
+import { ADMIN_FILE } from './admin-registration';
+import type { Finding } from './output';
+import { hasPathSegment } from './path-segments';
+import { isTest } from './source-files';
+
+/** The one place an admin used to be written that the scan cannot see. */
+const UNSCANNED = 'apps/*/src/**/*.{ts,tsx}';
+
+const DECLARES = /\bdefineAdmin\(/;
+
+/** Any admin this process mounted — then every declaration was reached, wherever it sits. */
+export const adminMounted = (): boolean =>
+  describeRoutes().some((route) => route.mount?.by === 'defineAdmin');
+
+/** Where the file belongs: its own name under the admin's home, `index.ts` as the declaration. */
+const homeOf = (file: string): string => {
+  const name = file.slice(file.lastIndexOf('/') + 1);
+  const home = ADMIN_FILE.slice(0, ADMIN_FILE.lastIndexOf('/'));
+  return /^index\.tsx?$/.test(name) ? ADMIN_FILE : `${home}/${name}`;
+};
+
+const unscannedFinding = (file: string): Finding => ({
+  code: 'X_ADMIN_UNSCANNED',
+  cause: `${file} calls defineAdmin(), and the app scan imports apps/*/{site,app,api,shared}/** only — no boot evaluates it, so the admin is never mounted and /admin answers 404`,
+  // A file name is the app's: screened, so a name carrying shell syntax reads as a placeholder.
+  fix: `git mv ${renderFixShellArg(file, '<the file above>')} ${renderFixShellArg(homeOf(file), '<apps/admin/app/admin/its-name.ts>')}   # then repoint its relative imports and x verify --only manifest --json`,
+  at: file,
+});
+
+/**
+ * One finding per unscanned file that declares an admin. Read only when nothing mounted one: an app
+ * whose admin is mounted pays for no glob, and comments are masked so prose naming the call is not
+ * a declaration.
+ */
+export async function unscannedAdminFindings(
+  root: string,
+  mounted: () => boolean = adminMounted,
+): Promise<readonly Finding[]> {
+  if (mounted()) return [];
+  const files: string[] = [];
+  for await (const file of new Bun.Glob(UNSCANNED).scan({ cwd: root })) {
+    const path = file.replaceAll('\\', '/');
+    if (hasPathSegment(path, 'node_modules') || isTest(path)) continue;
+    if (DECLARES.test(stripComments(await Bun.file(`${root}/${path}`).text()))) files.push(path);
+  }
+  return files.sort().map(unscannedFinding);
+}

package/src/verify-checks.ts

@@ -15,6 +15,7 @@ import {
 import type { MetaIssue } from '@ultimat3/seo';
 import { validateMeta } from '@ultimat3/seo';
 import { checkAgentsMd } from './app-agents-md';
+import { readAppSources } from './app-boundaries';
 import { envExampleFindings } from './app-env';
 import { appManifest, readAppManifest } from './app-manifest';
 import { OPENAPI_FILE, openApiStaleness } from './app-openapi';
@@ -36,10 +37,12 @@ import { msg } from './messages';
 import type { Finding } from './output';
 import { findingFrom } from './output';
 import { checkMigrationDrift } from './schema-drift';
+import { checkSchemaDump } from './schema-dump-drift';
 import { scanSiteMeta } from './seo-meta';
 import { quoteArg } from './shell-quote';
 import { readStaticReport } from './static-report';
 import { floorProblemFindings, readVerifyFloor } from './verify-floor';
+import { roleLoadFindings } from './verify-role-load';
 import type { VerifyStep } from './verify-step';
 import { fromExec, fromFindings, hostFindings } from './verify-step';
 import { TEST_STEPS } from './verify-tests';
@@ -90,7 +93,8 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
   },
   {
     name: 'boundaries',
-    summary: "surface, layer and package-tier imports, and the app's own guards",
+    summary:
+      "surface, layer and package-tier imports, one browser transport, and the app's own guards",
     // An app's `guards/` rides here rather than becoming a step of its own, for the reason the
     // seam already states: a host adds findings to a step, it can never add, remove, reorder or
     // skip one — so "green" keeps meaning exactly what it meant. This is the step whose host slot
@@ -101,12 +105,18 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
     // Discovered, not registered: `guardFindings` reads the directory. A guard that had to
     // announce itself is a guard an app can forget to announce, which is the coupling axiom 8's
     // extension model rejects.
-    run: async (ctx) =>
-      fromFindings([
-        ...(await appBoundaryFindings(ctx.root)),
-        ...(await guardFindings(ctx.root)),
+    //
+    // ONE read of the app's surface files for the whole step: the import rules, the transport
+    // rule and every guard are handed the same text. The guards used to walk and read the tree a
+    // second time (`guard-sources.ts`).
+    async run(ctx) {
+      const sources = await readAppSources(ctx.root);
+      return fromFindings([
+        ...(await appBoundaryFindings(ctx.root, sources)),
+        ...(await guardFindings(ctx.root, sources)),
         ...(await hostFindings(ctx, 'boundaries')),
-      ]),
+      ]);
+    },
   },
   {
     name: 'filesize',
@@ -161,7 +171,7 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
   {
     name: 'drift',
     summary:
-      'entity declarations vs migrations, every destructive statement declared, and every statement no declaration carries',
+      'entity declarations vs migrations, every destructive statement declared, every statement no declaration carries, and the committed schema dump',
     // Only an app owns migrations; a package monorepo's `packages/db` is the driver, not a schema.
     // Source, not database: the gate runs in CI with nothing listening, and the database half is
     // the post-migrate verification `runMigrations` performs where a connection is already open.
@@ -179,6 +189,10 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
         // a squash silently drops. Same directory, same reader, no database — this step's own
         // question, which is why it is not a step of its own.
         ...(await checkUngeneratableMigrations(ctx.root)),
+        // The fourth, and the only one that opens a database — a scratch embedded one it boots
+        // itself, so CI still needs nothing listening: the committed `packages/db/schema/` against
+        // what replaying the migrations produces, and that dump loaded back (`X_SCHEMA_DUMP_DRIFT`).
+        ...(await checkSchemaDump(ctx.root, ctx.env ?? Bun.env)),
       ]),
   },
   {
@@ -328,6 +342,8 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
       const agents = await checkAgentsMd(ctx.root, floor?.agentsMdMaxBytes);
       // The app's load failures, once, here — every other step that loaded it points at this one.
       const app = existsSync(join(ctx.root, APP_CONFIG_FILE));
+      // Started first and awaited last: it is a child process, and it runs beside the rest.
+      const roleLoad = app ? roleLoadFindings(ctx.root, ctx.runner) : Promise.resolve([]);
       const drift = await driftFindings(ctx.root);
       const findings = [
         ...manifestMissingFindings(ctx.root),
@@ -336,6 +352,9 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
         ...(existsSync(join(ctx.root, APP_CONFIG_FILE))
           ? await unregisteredJobFindings(ctx.root)
           : []),
+        // What a worker never registers: a declaration beside a component the API index does not
+        // import (`verify-role-load.ts`). The boot checks jobs and tasks only, and only at boot.
+        ...(await roleLoad),
         ...(await envExampleFindings(ctx.root)),
         ...floorProblemFindings(floor),
         ...agents.findings,