@ultimat3/cli 13.0.0 → 15.0.0

package/src/e2e-selection.ts

@@ -0,0 +1,182 @@
+// What an e2e locator SELECTS, as a value, plus the one in-page expression that resolves it.
+// `locator`/`getByRole`/`getByText` are lazy handles, so the selection has to survive as data
+// until something asks a question about it — and only then does it become a string the browser
+// can run.
+
+/** Where the driver parks its click target. Removed again as soon as the click has been made. */
+export const MARK_ATTRIBUTE = 'data-x-e2e';
+
+/** One selection, exactly as the test spelled it. `first` is `.first()`, applied at resolve time. */
+export type E2eSelection =
+  | { readonly kind: 'css'; readonly selector: string; readonly first: boolean }
+  | {
+      readonly kind: 'role';
+      readonly role: string;
+      readonly name?: string | undefined;
+      readonly level?: number | undefined;
+      readonly first: boolean;
+    }
+  | { readonly kind: 'text'; readonly text: string; readonly first: boolean };
+
+/**
+ * What the page answers for one selection. `count` is how many elements matched AFTER `first`
+ * narrowed it, `visible` is about the first match alone, and `marked` says the click target now
+ * carries `MARK_ATTRIBUTE` — three facts in one round trip, because a locator that asked twice
+ * could be answered about two different renders.
+ */
+export interface E2eResolution {
+  readonly count: number;
+  readonly visible: boolean;
+  readonly marked: boolean;
+}
+
+/**
+ * The elements that carry a role IMPLICITLY, so `getByRole('button')` finds a `<button>` that
+ * never wrote the attribute. A `Map` and not an object literal: the key is a role a test typed,
+ * and a computed read of a `Record` answers `Object.prototype` members — the defect
+ * `bun run proto-index` exists for.
+ *
+ * Deliberately not the whole of WAI-ARIA. A role absent from this table still resolves through
+ * its explicit `[role="…"]` attribute, which is why an unknown role is not refused: refusing
+ * `role="feed"` because a table in the framework is short would be the framework deciding an app's
+ * markup is wrong.
+ */
+const IMPLICIT_ROLE_ELEMENTS = new Map<string, readonly string[]>([
+  ['banner', ['header']],
+  ['button', ['button', 'input[type="button"]', 'input[type="submit"]', 'input[type="reset"]']],
+  ['checkbox', ['input[type="checkbox"]']],
+  ['combobox', ['select']],
+  ['contentinfo', ['footer']],
+  ['dialog', ['dialog']],
+  ['form', ['form']],
+  ['heading', ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']],
+  ['img', ['img']],
+  ['link', ['a[href]']],
+  ['list', ['ul', 'ol']],
+  ['listitem', ['li']],
+  ['main', ['main']],
+  ['navigation', ['nav']],
+  ['option', ['option']],
+  ['radio', ['input[type="radio"]']],
+  ['table', ['table']],
+  ['textbox', ['input[type="text"]', 'input[type="email"]', 'input[type="search"]', 'textarea']],
+]);
+
+/** Elements whose text is markup rather than page copy — `getByText` must never land on one. */
+const TEXT_SKIP_TAGS = ['SCRIPT', 'STYLE', 'HEAD', 'TITLE', 'META', 'LINK', 'NOSCRIPT'];
+
+/** A CSS attribute selector takes a double-quoted string, which is what `JSON.stringify` writes. */
+const roleSelector = (role: string): string =>
+  [`[role=${JSON.stringify(role)}]`, ...(IMPLICIT_ROLE_ELEMENTS.get(role) ?? [])].join(',');
+
+/**
+ * The call a test wrote, rebuilt from the selection. Every refusal below quotes it, because
+ * "an e2e locator matched nothing" names no line of the test file and this does.
+ */
+export function selectionCall(selection: E2eSelection): string {
+  const tail = selection.first ? '.first()' : '';
+  if (selection.kind === 'css') return `page.locator(${JSON.stringify(selection.selector)})${tail}`;
+  if (selection.kind === 'text') return `page.getByText(${JSON.stringify(selection.text)})${tail}`;
+  const options = [
+    ...(selection.name === undefined ? [] : [`name: ${JSON.stringify(selection.name)}`]),
+    ...(selection.level === undefined ? [] : [`level: ${String(selection.level)}`]),
+  ];
+  const role = JSON.stringify(selection.role);
+  const suffix = options.length === 0 ? '' : `, { ${options.join(', ')} }`;
+  return `page.getByRole(${role}${suffix})${tail}`;
+}
+
+/**
+ * The candidate list, as a JS expression evaluating to an array of elements.
+ *
+ * `getByRole` and `getByText` are not CSS and cannot be: a role is implicit in a tag name, an
+ * accessible name comes off four different attributes before it comes off the text, and
+ * `getByText` has to pick the INNERMOST element that contains the string. So the union selector
+ * is only the cheap first pass and every rule after it runs in JS, in the page.
+ */
+function candidateSource(selection: E2eSelection): string {
+  if (selection.kind === 'css') return `all(${JSON.stringify(selection.selector)})`;
+  if (selection.kind === 'text') {
+    const needle = JSON.stringify(selection.text.replace(/\s+/g, ' ').trim().toLowerCase());
+    // Innermost FIRST and the skip list second, in that order. Reversed, `<html>` becomes the
+    // innermost survivor of a page whose only copy of the string is inside a `<script>` — the
+    // ancestor inherits the match its own excluded child made, which is worse than not filtering
+    // at all: it reports one match, at the document root, for text no reader can see.
+    return `innermost(all('*').filter((el) => norm(el.textContent).toLowerCase().indexOf(${needle}) !== -1)).filter((el) => ${JSON.stringify(TEXT_SKIP_TAGS)}.indexOf(el.tagName) === -1)`;
+  }
+  const byRole = `all(${JSON.stringify(roleSelector(selection.role))}).filter((el) => { const own = el.getAttribute('role'); return own === null || norm(own).toLowerCase() === ${JSON.stringify(selection.role.toLowerCase())}; })`;
+  const byLevel =
+    selection.level === undefined
+      ? byRole
+      : `${byRole}.filter((el) => level(el) === ${String(selection.level)})`;
+  return selection.name === undefined
+    ? byLevel
+    : `${byLevel}.filter((el) => accName(el).toLowerCase() === ${JSON.stringify(selection.name.replace(/\s+/g, ' ').trim().toLowerCase())})`;
+}
+
+/**
+ * The helpers the candidate source above calls, defined once inside the IIFE.
+ *
+ * `visible` is `display`/`visibility`/`opacity`, which is character for character what
+ * `@ultimat3/scraping`'s `snapshotExpression` computes for `ElementSnapshot.visible`. That is a
+ * COPY and it is the wrong shape: `ScrapeTarget.query()` already answers a snapshot per element
+ * and `ScrapeFrame` does not expose it, so this driver cannot reach the framework's one definition
+ * of visible without an edit to `packages/scraping/src/page.ts`. Mirrored deliberately rather than
+ * invented, so the two cannot disagree about a page until that edit lands.
+ */
+const HELPERS = `
+  const norm = (s) => (s || '').replace(/\\s+/g, ' ').trim();
+  const all = (sel) => Array.prototype.slice.call(document.querySelectorAll(sel));
+  const innermost = (found) => found.filter((el) => !found.some((other) => other !== el && el.contains(other)));
+  const level = (el) => {
+    const aria = el.getAttribute('aria-level');
+    if (aria !== null) return Number(aria);
+    const tag = el.tagName.toLowerCase();
+    return /^h[1-6]$/.test(tag) ? Number(tag.slice(1)) : undefined;
+  };
+  const accName = (el) => {
+    const label = el.getAttribute('aria-label');
+    if (label !== null && norm(label) !== '') return norm(label);
+    const by = el.getAttribute('aria-labelledby');
+    if (by !== null) {
+      const parts = norm(by).split(' ').map((id) => document.getElementById(id)).filter((n) => n).map((n) => norm(n.textContent));
+      if (norm(parts.join(' ')) !== '') return norm(parts.join(' '));
+    }
+    const tag = el.tagName.toLowerCase();
+    if (tag === 'input') { const v = el.getAttribute('value'); if (v !== null && norm(v) !== '') return norm(v); }
+    if (tag === 'img') { const a = el.getAttribute('alt'); if (a !== null) return norm(a); }
+    const text = norm(el.textContent);
+    if (text !== '') return text;
+    const title = el.getAttribute('title');
+    return title !== null ? norm(title) : '';
+  };`;
+
+/**
+ * Returns JSON TEXT rather than an object, the same bargain `cdp-snapshot.ts` makes: a CDP round
+ * trip serialises the answer anyway, and a string has ONE deserialiser — a schema parse — instead
+ * of an implicit one inside the browser library plus a cast on this side.
+ */
+export function selectionExpression(selection: E2eSelection, mark?: string): string {
+  const marker = mark === undefined ? 'null' : JSON.stringify(mark);
+  return `(() => {${HELPERS}
+  const found = ${candidateSource(selection)};
+  const matches = ${selection.first ? 'found.slice(0, 1)' : 'found'};
+  const el = matches[0];
+  let visible = false;
+  if (el) {
+    const style = getComputedStyle(el);
+    visible = style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0';
+  }
+  const mark = ${marker};
+  let marked = false;
+  if (mark !== null && el) { el.setAttribute(${JSON.stringify(MARK_ATTRIBUTE)}, mark); marked = true; }
+  return JSON.stringify({ count: matches.length, visible: visible, marked: marked });
+})()`;
+}
+
+/** The CSS the marked element answers to — what `ScrapePage.click` is handed once one is marked. */
+export const markSelector = (mark: string): string => `[${MARK_ATTRIBUTE}=${JSON.stringify(mark)}]`;
+
+/** Undo. Best effort by design: a click that navigated took the whole document with it. */
+export const unmarkExpression = (mark: string): string =>
+  `(() => { const el = document.querySelector(${JSON.stringify(markSelector(mark))}); if (el) el.removeAttribute(${JSON.stringify(MARK_ATTRIBUTE)}); return JSON.stringify(true); })()`;

package/src/error-codes.ts

@@ -92,6 +92,22 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_GENERATE_CONFLICT',
   'X_PORT_IN_USE',
   'X_DB_GEN_FAILED',
+  // The two directions of the drift a hash cannot see, and they are two repairs. The `drift` step
+  // compared a schema-source HASH to a `.hash` sidecar and never read what the migration recorded,
+  // so nine declared CHECK constraints that had never reached any database were green for as long
+  // as nobody edited the schema. `UNMIGRATED` means the entities declare it and no migration
+  // carries it — the database will never get it. `UNDECLARED` means a migration recorded it and
+  // nothing in source declares it any more. One code over both would hand two readers one wrong
+  // edit, which is the reason `X_ERROR_FIX_PATH_MISSING` is not `X_ERROR_FIX_INVALID` either.
+  'X_DB_SCHEMA_UNMIGRATED',
+  'X_DB_SCHEMA_UNDECLARED',
+  // The third thing the `drift` step asks, and the one no declaration-based check can answer: SQL
+  // in a committed migration that `x db gen` could never have written, which a squash discards in
+  // silence because a regenerated sidecar equals the declaration by construction. CLI-owned rather
+  // than `@ultimat3/db`'s — that package classifies the statements and deliberately declares no
+  // code, because the only remedy available for all of them is a line in the migration file, and
+  // where that file lives is this package's fact.
+  'X_MIGRATION_UNGENERATABLE',
   'X_DB_MIGRATE_FAILED',
   'X_DB_BRANCH_FAILED',
   'X_DB_STUDIO_FAILED',
@@ -132,6 +148,16 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_SHOT_ISLAND_UNPHOTOGRAPHABLE',
   'X_SHOT_ISLAND_UNSTUBBED_REQUEST',
   'X_SHOT_ISLAND_MISSING',
+  // The browser-backed e2e driver — `e2e-driver.ts` and the three modules under it. Owned by the
+  // CLI because the ADAPTER is: `@ultimat3/testing` declares `PageLike` and may not import a
+  // browser, `@ultimat3/scraping` owns the browser and may not import the harness, and neither
+  // package can name a failure that only exists where the two meet.
+  'X_E2E_EVALUATE_UNSUPPORTED',
+  'X_E2E_EVALUATE_CAPTURED',
+  'X_E2E_EVALUATE_THREW',
+  'X_E2E_LOCATOR_EMPTY',
+  'X_E2E_LOCATOR_AMBIGUOUS',
+  'X_E2E_SERVICE_WORKER_ABSENT',
   'X_GH_UNAVAILABLE',
   'X_GH_NOT_AUTHENTICATED',
   'X_GH_COMMAND_FAILED',
@@ -229,6 +255,9 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_GENERATE_CONFLICT: 'a generator would overwrite a file',
   X_PORT_IN_USE: 'the dev port is taken',
   X_DB_GEN_FAILED: 'x db gen failed',
+  X_DB_SCHEMA_UNMIGRATED: 'an entity declaration no migration recorded',
+  X_DB_SCHEMA_UNDECLARED: 'a migration records schema no entity declares',
+  X_MIGRATION_UNGENERATABLE: 'this migration holds SQL no declaration carries and does not say so',
   X_DB_MIGRATE_FAILED: 'x db migrate failed',
   X_DB_BRANCH_FAILED: 'an x db branch step failed',
   X_DB_STUDIO_FAILED: 'x db studio failed',
@@ -250,6 +279,12 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_SHOT_ISLAND_UNPHOTOGRAPHABLE: 'the island never reached a state worth photographing',
   X_SHOT_ISLAND_UNSTUBBED_REQUEST: 'the island requested something no state stub answers',
   X_SHOT_ISLAND_MISSING: 'a declared island picture is not on disk',
+  X_E2E_EVALUATE_UNSUPPORTED: 'a page.evaluate() closure cannot be sent into the browser',
+  X_E2E_EVALUATE_CAPTURED: 'a page.evaluate() closure named a binding the page does not have',
+  X_E2E_EVALUATE_THREW: 'an expression an e2e page ran threw inside the browser',
+  X_E2E_LOCATOR_EMPTY: 'an e2e locator matched no element',
+  X_E2E_LOCATOR_AMBIGUOUS: 'an e2e locator matched more than one element and was asked to click',
+  X_E2E_SERVICE_WORKER_ABSENT: 'no service worker took control of the page within the budget',
   X_GH_UNAVAILABLE: 'the GitHub CLI is not runnable from here',
   X_GH_NOT_AUTHENTICATED: 'gh holds no credentials for this host',
   X_GH_COMMAND_FAILED: 'a gh invocation exited non-zero',

package/src/index.ts

@@ -113,6 +113,33 @@ export {
   schemaHash,
   writeSchemaHash,
 } from './drift';
+// The browser-backed e2e driver. `installE2eDriver` is the ONE entry point an app's test preload
+// calls; everything below it is exported because the adapter's own pieces are what a driver author
+// re-uses, and a deep import into `src/` would make each of them a compatibility promise anyway.
+export type { E2eDriverOptions } from './e2e-driver';
+export { e2eFixtures, installE2eDriver } from './e2e-driver';
+export {
+  E2eEvaluateCapturedError,
+  E2eEvaluateThrewError,
+  E2eEvaluateUnsupportedError,
+  E2eLocatorAmbiguousError,
+  E2eLocatorEmptyError,
+  E2eServiceWorkerAbsentError,
+} from './e2e-errors';
+export type { EvaluablePage } from './e2e-evaluate';
+export { closureSource, evaluateClosure, evaluateExpression } from './e2e-evaluate';
+export type { LocatablePage } from './e2e-locator';
+export { e2eLocator, resetLocatorMarks } from './e2e-locator';
+export type { E2eBrowserPage, E2ePageOptions } from './e2e-page';
+export { DEFAULT_E2E_TIMEOUT_MS, DEFAULT_SERVICE_WORKER_TIMEOUT_MS, e2ePage } from './e2e-page';
+export type { E2eResolution, E2eSelection } from './e2e-selection';
+export {
+  MARK_ATTRIBUTE,
+  markSelector,
+  selectionCall,
+  selectionExpression,
+  unmarkExpression,
+} from './e2e-selection';
 export type { ErrorCatalog } from './error-catalog';
 export {
   buildErrorCatalog,
@@ -248,6 +275,11 @@ export { flagBool, flagList, flagString, GLOBAL_FLAGS, nearest, parseArgs } from
 export type { PrerenderedPage, PrerenderOptions, PrerenderReport } from './prerender';
 export { DEFAULT_ORIGIN, isPrerenderable, prerenderSite } from './prerender';
 export { COMMANDS, cliVersion, commandFor, SPECS } from './registry';
+export type { SchemaDifference, SchemaDirection, SchemaPart } from './schema-diff';
+export { diffDeclaredSchema } from './schema-diff';
+// The drift a hash cannot see, and the composition both the gate step and `x doctor` read.
+export type { DeclaredEntities } from './schema-drift';
+export { checkMigrationDrift, checkSnapshotDrift } from './schema-drift';
 export { FrameworkSchemaFailedError } from './schema-errors';
 export type { MigratedApp, ServedApp, ServeOptions, StartedApp } from './serve';
 export {

package/src/mcp-errors.ts

@@ -64,6 +64,20 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x help shot --json   # the cause lists every request the state must answer under routes',
   X_SHOT_ISLAND_MISSING:
     'x help shot --json   # every absent picture carries its own named refusal in the run above',
+  // The six e2e-driver codes. Every one of them is raised inside a running suite, so the runnable
+  // half is the command that re-runs that suite — the cause already names the closure, the locator
+  // call or the budget, and no `x` command can edit a test for its author.
+  X_E2E_EVALUATE_UNSUPPORTED:
+    'x test e2e --json   # the cause quotes the closure; page.evaluate takes a zero-parameter arrow',
+  X_E2E_EVALUATE_CAPTURED:
+    'x test e2e --json   # the fix line names the binding to inline into the closure',
+  X_E2E_EVALUATE_THREW:
+    'x dev --json   # then run the expression the cause quotes in the browser console; the throw is the page\u2019s',
+  X_E2E_LOCATOR_EMPTY:
+    'x test e2e --json   # the fix line carries the toBeVisible() assertion to await first',
+  X_E2E_LOCATOR_AMBIGUOUS:
+    'x test e2e --json   # the fix line carries the same call with .first() on it',
+  X_E2E_SERVICE_WORKER_ABSENT: 'x build --target static --json',
   X_GH_UNAVAILABLE: 'gh auth login   # install first from https://cli.github.com',
   X_GH_NOT_AUTHENTICATED: 'gh auth login',
   X_GH_COMMAND_FAILED: 'x ci --json   # the finding carries the gh invocation that failed',
@@ -142,6 +156,18 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   // so the fix answered a failed step with X_CLI_UNKNOWN_COMMAND. `x doctor` is what reports
   // reachability and drift, and is already this table's answer for X_DB_STUDIO_FAILED.
   X_DB_GEN_FAILED: 'x doctor --json   # cause carries the Postgres error verbatim',
+  // Both directions resolve through the same command, and the CAUSE is what differs: one names a
+  // declaration the migrations never carried, the other one they carry and nothing declares. The
+  // narrowing is deliberately not a second command — there is only one generator.
+  X_DB_SCHEMA_UNMIGRATED:
+    'x db gen "add the declaration the cause names" --json   # then x db migrate --json',
+  X_DB_SCHEMA_UNDECLARED:
+    'x db gen "drop the declaration the cause names" --json   # or re-declare it on the entity',
+  // Not `x db gen`: regenerating is exactly what DISCARDS these statements, so the one command
+  // that must not be offered here is the one every other db code answers with. The gate is what
+  // reproduces the finding, and the finding names the file and the header line to add.
+  X_MIGRATION_UNGENERATABLE:
+    'x verify --only drift --json   # then add the `-- ungeneratable: <n>` header line the finding names',
   X_DB_MIGRATE_FAILED: 'x doctor --json   # cause carries the Postgres error verbatim',
   X_DB_BRANCH_FAILED: 'x db branch ls --json',
   X_DB_STUDIO_FAILED: 'x doctor --json',

package/src/schema-diff.ts

@@ -0,0 +1,275 @@
+// Single responsibility: what two GENERATED schema snapshots disagree about, as data. One side is
+// `snapshotOf(describeEntities())` — what the app declares right now — and the other is the
+// `.snapshot.json` the newest migration wrote down.
+//
+// Not `@ultimat3/db`'s `diffSchema`, and it never can be: that one compares a LIVE catalog to a
+// snapshot, so a predicate, a type name and a default are the server's own rewriting and are
+// deliberately left uncompared. Here both sides come out of `snapshotOf`, which is what makes a
+// check, a default and a column type comparable at all — and those are exactly the three the
+// `drift` gate step could not see.
+
+import type {
+  CheckDescription,
+  ColumnDescription,
+  ForeignKeyDescription,
+  IndexDescription,
+  SchemaDescription,
+  TableDescription,
+} from '@ultimat3/db';
+import { indexMethodOf } from '@ultimat3/db';
+
+/**
+ * Which side holds a declaration the other does not, and they are two different repairs.
+ * `unmigrated` means the app declares it and no migration carries it, so no database will ever
+ * get it. `undeclared` means a migration recorded it and nothing in source declares it any more.
+ */
+export type SchemaDirection = 'unmigrated' | 'undeclared';
+
+/** The part of a table a difference is about. Rendered into the cause verbatim. */
+export type SchemaPart = 'table' | 'column' | 'index' | 'foreign key' | 'check';
+
+export interface SchemaDifference {
+  readonly direction: SchemaDirection;
+  readonly part: SchemaPart;
+  readonly table: string;
+  /** The column, index, constraint or table name. */
+  readonly name: string;
+  /** One line naming what differs — it reaches a `cause:`, so it never spans lines. */
+  readonly detail: string;
+}
+
+const DECLARED_ONLY = 'is declared by the entities and no migration recorded it';
+const RECORDED_ONLY = 'was recorded by the newest migration and no entity declares it';
+
+const columns = (names: readonly string[]): string => names.join(', ');
+
+/** A default is SQL or nothing at all, and "nothing" has to read as a value in the sentence. */
+const defaultSql = (value: string | null): string => (value === null ? 'no default' : value);
+
+function columnDetail(
+  declared: ColumnDescription,
+  recorded: ColumnDescription,
+): string | undefined {
+  if (declared.dataType !== recorded.dataType) {
+    return `is declared ${declared.dataType} and was recorded ${recorded.dataType}`;
+  }
+  if (declared.nullable !== recorded.nullable) {
+    return declared.nullable
+      ? 'is declared nullable and was recorded not null'
+      : 'is declared not null and was recorded nullable';
+  }
+  if (declared.default !== recorded.default) {
+    return `is declared ${defaultSql(declared.default)} and was recorded ${defaultSql(recorded.default)}`;
+  }
+  // Absent and absent agree; absent against an expression is a column the database computes on one
+  // side and a writer supplies on the other, which is a `23502` on the first insert.
+  if ((declared.generated ?? null) !== (recorded.generated ?? null)) {
+    return `is declared generated as ${declared.generated ?? 'nothing'} and was recorded ${
+      recorded.generated ?? 'not generated'
+    }`;
+  }
+  return undefined;
+}
+
+/**
+ * Absent `using` is `btree` and absent `order` is `asc` — both are Postgres' own defaults and what
+ * every index recorded before those fields existed is. Read literally, every app with a sidecar
+ * from before them would report a difference on every index it has.
+ */
+function indexDetail(declared: IndexDescription, recorded: IndexDescription): string | undefined {
+  if (columns(declared.columns) !== columns(recorded.columns)) {
+    return `is declared over (${columns(declared.columns)}) and was recorded over (${columns(recorded.columns)})`;
+  }
+  if (declared.unique !== recorded.unique) {
+    return declared.unique
+      ? 'is declared unique and was recorded non-unique'
+      : 'is declared non-unique and was recorded unique';
+  }
+  if (indexMethodOf(declared) !== indexMethodOf(recorded)) {
+    return `is declared ${indexMethodOf(declared)} and was recorded ${indexMethodOf(recorded)}`;
+  }
+  if ((declared.order ?? 'asc') !== (recorded.order ?? 'asc')) {
+    return `is declared ${declared.order ?? 'asc'} and was recorded ${recorded.order ?? 'asc'}`;
+  }
+  if (declared.where !== recorded.where) {
+    return `is declared ${declared.where === null ? 'over every row' : `where ${declared.where}`} and was recorded ${
+      recorded.where === null ? 'over every row' : `where ${recorded.where}`
+    }`;
+  }
+  return undefined;
+}
+
+function keyDetail(
+  declared: ForeignKeyDescription,
+  recorded: ForeignKeyDescription,
+): string | undefined {
+  const target = (key: ForeignKeyDescription): string =>
+    `(${columns(key.columns)}) -> "${key.referencedTable}" (${columns(key.referencedColumns)})`;
+  if (target(declared) !== target(recorded)) {
+    return `is declared ${target(declared)} and was recorded ${target(recorded)}`;
+  }
+  // `null` is "no rule declared", which Postgres records as `no action` — a real answer, and the
+  // difference between an orphan row and a cascading delete.
+  if (declared.onDelete !== recorded.onDelete) {
+    return `is declared on delete ${declared.onDelete ?? 'unset'} and was recorded on delete ${
+      recorded.onDelete ?? 'unset'
+    }`;
+  }
+  return undefined;
+}
+
+const checkDetail = (declared: CheckDescription, recorded: CheckDescription): string | undefined =>
+  declared.expression === recorded.expression
+    ? undefined
+    : `is declared "${declared.expression}" and was recorded "${recorded.expression}"`;
+
+interface ListComparison<T> {
+  readonly part: SchemaPart;
+  readonly table: string;
+  readonly declared: readonly T[];
+  readonly recorded: readonly T[];
+  readonly key: (item: T) => string;
+  /** What differs between two items of the same name, or `undefined` when they agree. */
+  readonly detail: (declared: T, recorded: T) => string | undefined;
+}
+
+/**
+ * Both directions of one named list, in one pass. A `Map` and not an object literal: a constraint
+ * name is data, and a computed read of a `Record<…>` answers an `Object.prototype` member for a
+ * table someone called `constructor`.
+ *
+ * A CHANGED item is reported as `unmigrated`, never as its own direction: the declaration is the
+ * intent and a migration that recorded something else is the one that is behind.
+ */
+function compareList<T>(comparison: ListComparison<T>): SchemaDifference[] {
+  const { part, table } = comparison;
+  const out: SchemaDifference[] = [];
+  const recorded = new Map(comparison.recorded.map((item) => [comparison.key(item), item]));
+  for (const item of comparison.declared) {
+    const name = comparison.key(item);
+    const counterpart = recorded.get(name);
+    if (counterpart === undefined) {
+      out.push({ direction: 'unmigrated', part, table, name, detail: DECLARED_ONLY });
+      continue;
+    }
+    const detail = comparison.detail(item, counterpart);
+    if (detail !== undefined) out.push({ direction: 'unmigrated', part, table, name, detail });
+  }
+  const declared = new Set(comparison.declared.map(comparison.key));
+  for (const item of comparison.recorded) {
+    const name = comparison.key(item);
+    if (declared.has(name)) continue;
+    out.push({ direction: 'undeclared', part, table, name, detail: RECORDED_ONLY });
+  }
+  return out;
+}
+
+/**
+ * `checks` is absent — never `[]` — on a table that declares none, deliberately, so a sidecar
+ * written before the field existed reads as "nothing recorded" rather than "recorded none". Both
+ * sides normalise to empty here for the same reason: a table that never had a constraint must not
+ * report one, and a table that has nine of them must.
+ */
+function compareTable(declared: TableDescription, recorded: TableDescription): SchemaDifference[] {
+  const table = declared.name;
+  const out: SchemaDifference[] = [];
+  // Read into locals first, and NOT named `…Key`: `bun run secret-compare` matches an operand
+  // whose NAME says it holds a credential, and a row's identity is the opposite of a secret — it
+  // is in every URL the app serves.
+  const declaredIdentity = columns(declared.primaryKey);
+  const recordedIdentity = columns(recorded.primaryKey);
+  if (declaredIdentity !== recordedIdentity) {
+    out.push({
+      direction: 'unmigrated',
+      part: 'table',
+      table,
+      name: table,
+      detail: `declares primary key (${columns(declared.primaryKey)}) and the migration recorded (${columns(recorded.primaryKey)})`,
+    });
+  }
+  out.push(
+    ...compareList({
+      part: 'column',
+      table,
+      declared: declared.columns,
+      recorded: recorded.columns,
+      key: (column) => column.name,
+      detail: columnDetail,
+    }),
+    ...compareList({
+      part: 'index',
+      table,
+      declared: declared.indexes,
+      recorded: recorded.indexes,
+      key: (index) => index.name,
+      detail: indexDetail,
+    }),
+    ...compareList({
+      part: 'foreign key',
+      table,
+      declared: declared.foreignKeys,
+      recorded: recorded.foreignKeys,
+      key: (key) => key.name,
+      detail: keyDetail,
+    }),
+    ...compareList({
+      part: 'check',
+      table,
+      declared: declared.checks ?? [],
+      recorded: recorded.checks ?? [],
+      key: (check) => check.name,
+      detail: checkDetail,
+    }),
+  );
+  return out;
+}
+
+const PART_ORDER: readonly SchemaPart[] = ['table', 'column', 'index', 'foreign key', 'check'];
+
+/**
+ * Pure and total: the same two snapshots always produce the same ordered report, so a diff of two
+ * gate runs on two machines is readable.
+ *
+ * A table present on only one side is ONE difference and the columns under it are not descended
+ * into — the repair is a single statement, and a finding per column would be twelve instructions
+ * for it.
+ */
+export function diffDeclaredSchema(
+  declared: SchemaDescription,
+  recorded: SchemaDescription,
+): readonly SchemaDifference[] {
+  const out: SchemaDifference[] = [];
+  const byName = new Map(recorded.tables.map((table) => [table.name, table]));
+  for (const table of declared.tables) {
+    const counterpart = byName.get(table.name);
+    if (counterpart === undefined) {
+      out.push({
+        direction: 'unmigrated',
+        part: 'table',
+        table: table.name,
+        name: table.name,
+        detail: DECLARED_ONLY,
+      });
+      continue;
+    }
+    out.push(...compareTable(table, counterpart));
+  }
+  const declaredTables = new Set(declared.tables.map((table) => table.name));
+  for (const table of recorded.tables) {
+    if (declaredTables.has(table.name)) continue;
+    out.push({
+      direction: 'undeclared',
+      part: 'table',
+      table: table.name,
+      name: table.name,
+      detail: RECORDED_ONLY,
+    });
+  }
+  out.sort((a, b) => {
+    if (a.table !== b.table) return a.table < b.table ? -1 : 1;
+    if (a.part !== b.part) return PART_ORDER.indexOf(a.part) - PART_ORDER.indexOf(b.part);
+    if (a.direction !== b.direction) return a.direction < b.direction ? -1 : 1;
+    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+  });
+  return out;
+}