@ultimat3/cli 2.0.0 → 4.0.0

package/src/error-catalog.ts

@@ -36,6 +36,7 @@ export const CATALOG_PACKAGES = [
   '@ultimat3/realtime',
   '@ultimat3/render',
   '@ultimat3/schema',
+  '@ultimat3/scraping',
   '@ultimat3/seo',
   '@ultimat3/storage',
   '@ultimat3/testing',

package/src/error-codes.ts

@@ -67,6 +67,11 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_DB_MIGRATE_FAILED',
   'X_DB_BRANCH_FAILED',
   'X_DB_STUDIO_FAILED',
+  // Refusing to seed production is a REFUSAL, not a malformed invocation, so it is not
+  // `X_CLI_BAD_FLAG`: the argv was well formed and the answer is no. Its own code is what lets
+  // `x errors explain` hand back the one remedy — name the tier — instead of the flag code's
+  // "unknown flag, missing value, or a value the command refuses", which covers a dozen causes.
+  'X_SEED_ENVIRONMENT',
   // The five app-surface boundary codes. `@ultimat3/render` owns the *rule* (`checkSurfaceBoundary`)
   // and the CLI owns the diagnostic, because `x verify` and `x fix boundary` are the two commands
   // that report it — see `app-boundaries.ts`, which holds the one rule-to-code table.
@@ -81,6 +86,10 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_GUARD_INVALID',
   'X_GUARD_FAILED',
   'X_GUARD_FINDING_INVALID',
+  // The CLI's own declarations, held to each other. A flag the parser accepts and no code reads
+  // is a promise in `x help` with nothing behind it — `x deploy --critical` said "forces clients
+  // to reload" and reached no reader outside the plan JSON it was written into.
+  'X_CLI_FLAG_UNREAD',
   // The two halves of `x secrets edit` that belong to the terminal rather than to the envelope.
   // `@ultimat3/core` owns every X_SECRETS_* code about the file and the key; an editor is the
   // CLI's problem alone, and core would have no `fix:` to offer for one.
@@ -165,6 +174,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   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',
+  X_SEED_ENVIRONMENT: 'the seed tier is not one this environment runs',
   X_BOUNDARY_SITE_TO_APP: 'site/ imported app/',
   X_BOUNDARY_SHARED_LEAF: 'shared/ imported a surface',
   X_BOUNDARY_APP_TO_API: 'app/ imported api/ at runtime',
@@ -173,6 +183,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_GUARD_INVALID: 'a file in guards/ exports no usable guard',
   X_GUARD_FAILED: 'an app guard threw instead of returning findings',
   X_GUARD_FINDING_INVALID: "an app guard's finding breaks the error contract",
+  X_CLI_FLAG_UNREAD: 'a command declares a flag no code reads',
   X_SECRETS_EDITOR_MISSING: 'no $EDITOR to open the decrypted secrets in',
   X_SECRETS_EDIT_FAILED: 'the editor exited non-zero, so nothing was resealed',
 };

package/src/error-contract.ts

@@ -8,10 +8,12 @@
 import { join } from 'node:path';
 import { docsFor } from './error-codes';
 import { citedCommandProblem, loadCommandCatalog } from './fix-command';
+import { createHelperResolver } from './fix-imports';
+import { scanFixSites } from './fix-scan';
 import type { Finding } from './output';
 import { eachSourceFile, isGenerated, isTest } from './source-files';
 import type { CodeSite, FixSite } from './ts-scan';
-import { isCodeRegistry, scanBorrowedCodes, scanCodes, scanFixes } from './ts-scan';
+import { isCodeRegistry, scanBorrowedCodes, scanCodes } from './ts-scan';
 
 /** Advice, not instruction. The list is the one in `docs/architecture/04-error-contract.md`. */
 export const BANNED_PHRASES: readonly RegExp[] = [
@@ -77,12 +79,33 @@ const fixFinding = (site: FixSite, problem: string): Finding => ({
  * The catalog is loaded ONCE per run rather than per fix line: it is a dynamic import (see
  * `fix-command.ts` for the cycle it breaks) and this walks every shipped source file.
  */
-export async function checkErrorFixes(root: string): Promise<readonly Finding[]> {
+export interface ErrorFixReport {
+  readonly findings: readonly Finding[];
+  /** Fix literals actually read, and held to both rules. */
+  readonly checked: number;
+  /**
+   * Fix arguments at a known builder that hold no single literal — a parameter passed through, a
+   * concatenation, a table lookup. The step prints it, because a gate that says "checked 412,
+   * could not read 27" is honest and one that says nothing is the false green this check exists to
+   * close. It does NOT cover a builder imported from another PACKAGE: `candidatePaths` resolves
+   * relative specifiers only, and that gap is 3 call sites across this repo, measured 2026-08.
+   */
+  readonly unreadable: number;
+}
+
+export async function checkErrorFixReport(root: string): Promise<ErrorFixReport> {
   const findings: Finding[] = [];
   const catalog = await loadCommandCatalog();
+  const imports = createHelperResolver(root);
+  let checked = 0;
+  let unreadable = 0;
   for await (const path of eachSourceFile(root)) {
     if (isTest(path) || isGenerated(path)) continue;
-    for (const site of scanFixes(await Bun.file(join(root, path)).text(), path)) {
+    const source = await Bun.file(join(root, path)).text();
+    const scan = scanFixSites(source, path, await imports(path, source));
+    checked += scan.sites.length;
+    unreadable += scan.unreadable;
+    for (const site of scan.sites) {
       // The interpolation-blanked form for both rules: `x ${name}` names no command this can
       // resolve, and reading `<value>` as one would be a finding nobody can act on.
       const fix = staticFix(site.fix);
@@ -90,9 +113,13 @@ export async function checkErrorFixes(root: string): Promise<readonly Finding[]>
       if (problem !== undefined) findings.push(fixFinding(site, problem));
     }
   }
-  return findings;
+  return { findings, checked, unreadable };
 }
 
+/** The findings alone, for every caller that reports no coverage line. */
+export const checkErrorFixes = async (root: string): Promise<readonly Finding[]> =>
+  (await checkErrorFixReport(root)).findings;
+
 /**
  * A code is documented when the reference page names it. Deliberately not "owns a table row": the
  * page legitimately groups near-identical codes onto one row, and a rule that forbade that would

package/src/exec.ts

@@ -5,7 +5,10 @@
 // `UltimateError` straight from core rather than a class in `./errors`: this module is imported by
 // every command, and `./errors` runs `registerErrorCodes` on import — a subprocess boundary must
 // not decide when the CLI's registry is populated. `X_CLI_UNEXPECTED` is owned there all the same.
-import { UltimateError } from '@ultimat3/core';
+import { renderThrowable, UltimateError } from '@ultimat3/core';
+// `shell-quote.ts` is a leaf — it imports nothing, so the subprocess boundary stays importable
+// from anywhere, this file's header rule about a single boundary included.
+import { quoteArg } from './shell-quote';
 
 export interface ExecResult {
   readonly command: readonly string[];
@@ -27,6 +30,43 @@ export type Runner = (command: readonly string[], options: ExecOptions) => Promi
 /** performance.now(), not Date.now(): the test preload freezes the wall clock on purpose. */
 const now = (): number => performance.now();
 
+/**
+ * The failure mode this file's header already promised was identical everywhere, and the one it
+ * never coded. `x deploy` on a machine without `docker` threw Bun's own `Error: Executable not
+ * found in $PATH`; `dispatch.ts` rendered it as `X_CLI_UNEXPECTED` with `fix: x doctor --json`,
+ * and `runDoctor` checks nothing about an absent binary — an instruction that cannot close the
+ * error is axiom 4 inverted. The code stays `X_CLI_UNEXPECTED` (the CLI already owns it for a
+ * failure of its own machinery); what changes is that the fix names the program to install.
+ *
+ * The program name goes through `quoteArg` at BOTH references: `docker compose` or any name a
+ * shell would resplit produced a `fix:` that runs something else, which is axiom 4 inverted twice
+ * in one line.
+ *
+ * The thrown value goes through core's render helper and is never interpolated: an `unknown`
+ * reaching a `cause:` through `${…}` is what `bun run error-render` refuses, and this one is
+ * genuinely unknown — Bun raises `ENOENT` for a missing program, `EACCES` for an unrunnable one.
+ *
+ * The return type is inferred so this stays one statement of `Bun.spawn`'s own shape.
+ */
+function spawnOrRefuse(command: readonly string[], options: ExecOptions) {
+  const [head = '', ...rest] = command;
+  try {
+    return Bun.spawn([head, ...rest], {
+      cwd: options.cwd,
+      env: options.env === undefined ? Bun.env : { ...Bun.env, ...options.env },
+      stdin: options.stdin === undefined ? 'ignore' : new TextEncoder().encode(options.stdin),
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+  } catch (error) {
+    throw new UltimateError({
+      code: 'X_CLI_UNEXPECTED',
+      cause: `the CLI could not run "${head}" from ${options.cwd}: ${renderThrowable(error)}`,
+      fix: `install ${quoteArg(head)} and put it on PATH, then re-run — confirm with: command -v ${quoteArg(head)}`,
+    });
+  }
+}
+
 export const exec: Runner = async (command, options) => {
   const started = now();
   const [head, ...rest] = command;
@@ -40,13 +80,7 @@ export const exec: Runner = async (command, options) => {
       fix: 'pass the program as the first element: exec(["bun", "test"], { cwd })',
     });
   }
-  const proc = Bun.spawn([head, ...rest], {
-    cwd: options.cwd,
-    env: options.env === undefined ? Bun.env : { ...Bun.env, ...options.env },
-    stdin: options.stdin === undefined ? 'ignore' : new TextEncoder().encode(options.stdin),
-    stdout: 'pipe',
-    stderr: 'pipe',
-  });
+  const proc = spawnOrRefuse([head, ...rest], options);
   const [stdout, stderr, code] = await Promise.all([
     new Response(proc.stdout).text(),
     new Response(proc.stderr).text(),

package/src/fix-command.ts

@@ -28,8 +28,15 @@ import { GLOBAL_FLAGS } from './parse';
 // in `@ultimat3/mcp` — is `X_CLI_UNKNOWN_COMMAND` when run and resolved clean while a placeholder
 // was invisible to the reader. Second and fourth slots are open positionals (`x new my-app`,
 // `x db branch drop <name>`), where a placeholder is exactly right.
-const CITATION =
-  /(?:^|[\s;|&("'`])x\s+([a-z][a-z\d-]*)(?:\s+([a-z][a-z\d-]*))?(?:\s+([a-z][a-z\d-]*|<[^>]*>))?/g;
+// A `:` is part of a word only when a letter follows it, which is what separates the shipped
+// positional `admin:page` from prose that ends a citation with a colon (`x verify: the gate`).
+// Read without it, `x g admin:page` cites `x g admin` — a positional the CLI does not ship —
+// and the one documented invocation of the admin-page generator was a standing false finding.
+const WORD = String.raw`[a-z][a-z\d-]*(?::[a-z][a-z\d-]*)?`;
+const CITATION = new RegExp(
+  String.raw`(?:^|[\s;|&("'\x60])x\s+(${WORD})(?:\s+(${WORD}))?(?:\s+(${WORD}|<[^>]*>))?`,
+  'g',
+);
 
 /**
  * A long flag, `--` stripped. `--no-<name>` is the parser's negation of a boolean, so it resolves

package/src/fix-imports.ts

@@ -0,0 +1,118 @@
+// A fix-building helper the calling file did not declare: `invalidIconDataError` lives in
+// `packages/ui/src/errors.ts` and every fix it is handed is written in `icons/build-icons.ts`.
+// One specifier, one file read, one parameter position — deliberately still not `tsc`.
+
+// `dirname`/`join` are `node:`-only by necessity: Bun exposes no path-join primitive.
+import { dirname, join } from 'node:path';
+import type { FixHelper } from './fix-scan';
+import { scanFixHelpers } from './fix-scan';
+import { endOfLiteral, maskLiterals } from './ts-scan';
+
+/**
+ * A named import, matched over the MASKED source and anchored at the start of a line, so an
+ * `import …` written inside a template literal is not read as one — `packages/cli/src/templates/`
+ * emits a dozen of them as generated app source, and resolving those pointed the scan at a module
+ * that only exists in the app the template writes. Masking blanks a literal's contents and keeps
+ * its delimiters, so the specifier is read back out of the raw source at the quote's own offset.
+ *
+ * `import type` is skipped whole: a type has no call site. A default or namespace import is not
+ * matched at all — this repo ships no default exports, and `errors.raise(…)` is a member access
+ * that `helperFixSites` refuses by design.
+ */
+const IMPORT_CLAUSE = /^import\s+(type\s+)?\{([^}]*)\}\s*from\s*['"]/gm;
+
+/** `a`, `a as b`, and the inline `type a` that carries no value. */
+const parseClause = (clause: string): { readonly exported: string; readonly local: string }[] =>
+  clause
+    .split(',')
+    .map((part) => part.trim())
+    .filter((part) => part !== '' && !/^type\s/.test(part))
+    .map((part) => {
+      const [exported, local] = part.split(/\s+as\s+/);
+      return { exported: (exported ?? '').trim(), local: (local ?? exported ?? '').trim() };
+    })
+    .filter((name) => /^[A-Za-z_$][\w$]*$/.test(name.exported) && name.local !== '');
+
+interface LocalImport {
+  readonly specifier: string;
+  readonly names: readonly { readonly exported: string; readonly local: string }[];
+}
+
+/** Every value import in this file, specifier as written. */
+export function scanImports(source: string): readonly LocalImport[] {
+  const masked = maskLiterals(source);
+  const imports: LocalImport[] = [];
+  for (const match of masked.matchAll(IMPORT_CLAUSE)) {
+    if (match[1] !== undefined) continue;
+    const names = parseClause(match[2] ?? '');
+    const quote = match.index + match[0].length - 1;
+    const specifier = source.slice(quote + 1, endOfLiteral(masked, quote) - 1);
+    if (names.length > 0 && specifier !== '') imports.push({ specifier, names });
+  }
+  return imports;
+}
+
+/**
+ * The repo-relative paths a relative specifier could name, in resolution order. Only relative
+ * ones: `@ultimat3/db` and `node:path` are somebody else's file set, and a scanner that guessed
+ * which package a bare name came from would read an unrelated function's argument as a fix. That
+ * gap is real and named — `x verify`'s `errors` step counts what it could not read rather than
+ * passing over it silently, which is the failure this file exists to end.
+ */
+export function candidatePaths(from: string, specifier: string): readonly string[] {
+  if (!specifier.startsWith('./') && !specifier.startsWith('../')) return [];
+  const base = join(dirname(from), specifier);
+  // A path that climbed out of the repo root is not a file this scan may open.
+  if (base.startsWith('..')) return [];
+  return [`${base}.ts`, `${base}.tsx`, join(base, 'index.ts'), join(base, 'index.tsx')];
+}
+
+/**
+ * The helpers one file can call, named as that file names them.
+ *
+ * Deliberately NOT also a count of the imports it could not open: that number is 1504 in this
+ * repo and 1310 of them are `@ultimat3/*` names like `join` and `UltimateError` — a figure nobody
+ * can act on. What the gate reports instead is `FixScan.unreadable`, which counts only arguments
+ * in a KNOWN fix position, and is therefore a count of fixes rather than of imports.
+ */
+export type HelperResolver = (path: string, source: string) => Promise<readonly FixHelper[]>;
+
+/**
+ * One resolver per run, because the module cache is the whole point: `packages/ui/src/errors.ts`
+ * is imported by every file in the package, and re-reading and re-scanning it per importer turns
+ * a one-pass walk into a quadratic one.
+ *
+ * A name declared in the imported module wins by NAME alone — no export check. The tree
+ * typechecks, so a name this file imports is a name that module exports; a second rule reading
+ * `export` keywords would only be able to disagree with `tsc`, never to add anything.
+ */
+export function createHelperResolver(root: string): HelperResolver {
+  const modules = new Map<string, readonly FixHelper[] | undefined>();
+
+  const helpersIn = async (path: string): Promise<readonly FixHelper[] | undefined> => {
+    const cached = modules.get(path);
+    if (cached !== undefined || modules.has(path)) return cached;
+    const file = Bun.file(join(root, path));
+    const found = (await file.exists())
+      ? scanFixHelpers(maskLiterals(await file.text()))
+      : undefined;
+    modules.set(path, found);
+    return found;
+  };
+
+  return async (path, source) => {
+    const helpers: FixHelper[] = [];
+    for (const declaration of scanImports(source)) {
+      let declared: readonly FixHelper[] | undefined;
+      for (const candidate of candidatePaths(path, declaration.specifier)) {
+        declared = await helpersIn(candidate);
+        if (declared !== undefined) break;
+      }
+      for (const name of declaration.names) {
+        const helper = (declared ?? []).find((one) => one.name === name.exported);
+        if (helper !== undefined) helpers.push({ name: name.local, index: helper.index });
+      }
+    }
+    return helpers;
+  };
+}

package/src/fix-scan.ts

@@ -0,0 +1,251 @@
+// Every string a `fix:` can evaluate to, in the three shapes a fix arrives in: under a key, in the
+// argument position of a factory that builds an error, and in the argument position of an error
+// class's constructor. Split out of `ts-scan.ts` when the third shape and cross-file resolution
+// (`fix-imports.ts`) took the file past the 500-line ceiling; the masking primitives stay there.
+
+import type { FixSite } from './ts-scan';
+import {
+  CLOSERS,
+  endOfLiteral,
+  lineIndex,
+  maskLiterals,
+  OPENERS,
+  QUOTES,
+  valueLiterals,
+} from './ts-scan';
+
+/** The lookbehind rejects member access: `cond ? e.fix : ''` is a ternary, not a declaration. */
+const FIX_KEY = /(?<![.\w$])fix\s*:\s*/g;
+
+/** Text between the bracket at `open` and its match, or `undefined` when it never closes. */
+function bracketSpan(masked: string, open: number): string | undefined {
+  let depth = 0;
+  for (let i = open; i < masked.length; i += 1) {
+    const ch = masked[i] as string;
+    // Only `()[]{}`. An angle bracket is a generic in a parameter list and the tail of `=>` in the
+    // very same list, so counting it makes `(fn: () => void)` end the span in the wrong place.
+    if (OPENERS.has(ch)) depth += 1;
+    else if (CLOSERS.has(ch)) {
+      depth -= 1;
+      if (depth === 0) return masked.slice(open + 1, i);
+    }
+  }
+  return undefined;
+}
+
+/** Split at depth-0 commas. Safe on masked text, where a comma inside a literal is already gone. */
+function topLevelParts(text: string): readonly string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i] as string;
+    if (OPENERS.has(ch)) depth += 1;
+    else if (CLOSERS.has(ch)) depth -= 1;
+    else if (ch === ',' && depth === 0) {
+      parts.push(text.slice(start, i));
+      start = i + 1;
+    }
+  }
+  parts.push(text.slice(start));
+  return parts;
+}
+
+/** A callable that builds an error and takes its fix positionally, and where in its list. */
+export interface FixHelper {
+  readonly name: string;
+  readonly index: number;
+}
+
+const HELPER_DECL =
+  /(?<![.\w$])(?:function\s+([A-Za-z_$][\w$]*)\s*\(|(?:const|let)\s+([A-Za-z_$][\w$]*)\s*(?::[^=;]*)?=\s*(?:async\s+)?\()/g;
+
+/**
+ * A class, and — because the helper's NAME is the class's and the parameter list is its
+ * constructor's — the two are found in two steps rather than one regex. `@ultimat3/render`'s
+ * `errors.ts` declares fourteen of these taking `(cause, fix)` positionally, and until this the
+ * form was unread everywhere: measured over the tree, it has ZERO same-file call sites, so the
+ * same-file rule was dead code for it and 15 of render's codes never had a fix line checked.
+ */
+const CLASS_DECL = /(?<![.\w$])class\s+([A-Za-z_$][\w$]*)[^{;]*\{/g;
+const CONSTRUCTOR = /(?<![.\w$])constructor\s*\(/;
+
+const FIX_PARAM = /^\s*fix\s*:\s*string\s*$/;
+
+/**
+ * What separates a helper that BUILDS a fix from one that CONSUMES one. `citedCommandProblem(fix:
+ * string, …)` in `fix-command.ts` takes a fix in order to judge it, and reading its call sites as
+ * declarations would report findings about strings that are already findings. A builder names a
+ * `code` or constructs an `…Error`; a consumer does neither.
+ */
+const BUILDS_ERROR = /(?<![.\w$])code\s*[:=]|new\s+[A-Za-z_$][\w$]*Error\s*\(/;
+
+/**
+ * The body of the declaration whose parameter list ends at `after`, and never a `{` belonging to
+ * something below it. An unbounded `indexOf('{')` reads the next object literal in the FILE when
+ * the body is a concise expression, so `const label = (fix: string) => fix.trim();` followed
+ * anywhere by a `{ code: … }` was read as an error builder and every `label(…)` call handed the
+ * gate a string to judge as a fix — a false gate failure over innocent source.
+ *
+ * The scan therefore ends at the `;` that ends the declaration, or at a bracket closing a scope
+ * this declaration is inside. Both directions of that bound answer `''`, which classifies the
+ * helper as a non-builder: a missed fix line costs one unchecked citation, a wrongly claimed one
+ * costs a build. A `{` inside a return-type annotation (`(): { ok: boolean } => …`) is read as the
+ * body and answers `''` for the same reason.
+ */
+function bodyOf(masked: string, after: number): string {
+  for (let i = after; i < masked.length; i += 1) {
+    const ch = masked[i] as string;
+    if (ch === '{') return bracketSpan(masked, i) ?? '';
+    if (ch === ';' || CLOSERS.has(ch)) break;
+  }
+  return '';
+}
+
+/**
+ * One declaration judged: it must build an error, and its fix must sit at a position a call site
+ * can be read at. A rest parameter makes the position of everything after it unknowable, and a
+ * destructured one has no position at all — its `fix:` key at the CALL site is already read by
+ * `FIX_KEY`.
+ */
+function helperAt(masked: string, name: string, open: number): FixHelper | undefined {
+  const params = bracketSpan(masked, open);
+  if (params === undefined || params.includes('...')) return undefined;
+  const parts = topLevelParts(params);
+  if (parts.some((part) => /^\s*[[{]/.test(part))) return undefined;
+  const index = parts.findIndex((part) => FIX_PARAM.test(part));
+  if (index === -1) return undefined;
+  if (!BUILDS_ERROR.test(bodyOf(masked, open + params.length + 2))) return undefined;
+  return { name, index };
+}
+
+/**
+ * Every fix-building callable this file declares — a function, an arrow bound to a const, or a
+ * class whose constructor takes the fix. Exported because `fix-imports.ts` asks the same question
+ * of a file this one merely imports FROM; there is no second reader of a declaration.
+ */
+export function scanFixHelpers(masked: string): readonly FixHelper[] {
+  const helpers: FixHelper[] = [];
+  for (const declaration of masked.matchAll(HELPER_DECL)) {
+    const name = declaration[1] ?? declaration[2];
+    const open = declaration.index + declaration[0].length - 1;
+    if (name === undefined || masked[open] !== '(') continue;
+    const helper = helperAt(masked, name, open);
+    if (helper !== undefined) helpers.push(helper);
+  }
+  for (const declaration of masked.matchAll(CLASS_DECL)) {
+    const name = declaration[1];
+    const body = declaration.index + declaration[0].length - 1;
+    const inner = bracketSpan(masked, body);
+    const found = inner === undefined ? null : CONSTRUCTOR.exec(inner);
+    if (name === undefined || found === null) continue;
+    const helper = helperAt(masked, name, body + 1 + found.index + found[0].length - 1);
+    if (helper !== undefined) helpers.push(helper);
+  }
+  return helpers;
+}
+
+/**
+ * A fix argument this scan could not read, at a call site it could: the callee is a known helper
+ * and the fix position holds something other than one literal. Counted rather than dropped, so
+ * `x verify`'s `errors` step can say "checked 412, could not read 27" — a gate that stays silent
+ * about its own blind spot is the false green this file exists to close (axiom 4 applies to it too).
+ */
+export interface FixScan {
+  readonly sites: readonly FixSite[];
+  readonly unreadable: number;
+}
+
+/**
+ * The argument in that position at every call to that helper in this file. `new X(…)` is a call
+ * like any other here: the lookbehind sees the space after `new`, so a class needs no second rule.
+ */
+function helperFixSites(
+  masked: string,
+  source: string,
+  at: string,
+  helper: FixHelper,
+  lineAt: (index: number) => number,
+  unreadable: { count: number },
+): readonly FixSite[] {
+  const sites: FixSite[] = [];
+  // The lookbehind is `FIX_KEY`'s: `reporter.rejected(…)` is some other object's method.
+  const call = new RegExp(`(?<![.\\w$])${helper.name}\\s*\\(`, 'g');
+  for (const match of masked.matchAll(call)) {
+    const open = match.index + match[0].length - 1;
+    const args = bracketSpan(masked, open);
+    if (args === undefined) continue;
+    const parts = topLevelParts(args);
+    const argument = parts[helper.index];
+    // A call one argument short passes no fix at all — nothing was written here to read.
+    if (argument === undefined) continue;
+    // Stricter than the `fix:` path, and deliberately: the whole argument must BE one literal.
+    // `valueLiterals` alone reads `prefix + 'x doctor'` as one literal, because the identifier
+    // half contributes none — and publishing half a fix as the whole one is the failure
+    // `soleLiteral` already names. A key at least declares that what follows is the value.
+    const quote = argument.trim()[0];
+    if (quote === undefined || !QUOTES.has(quote)) {
+      unreadable.count += 1;
+      continue;
+    }
+    const literal = argument.indexOf(quote);
+    if (argument.slice(endOfLiteral(argument, literal)).trim() !== '') {
+      unreadable.count += 1;
+      continue;
+    }
+    const from = parts.slice(0, helper.index).reduce((n, part) => n + part.length + 1, open + 1);
+    const literals = valueLiterals(masked, source, from, lineAt);
+    if (literals.length === 1) sites.push({ ...(literals[0] as FixSite), at });
+    else unreadable.count += 1;
+  }
+  return sites;
+}
+
+/**
+ * Every string a `fix:` can evaluate to. Searched over the masked source, so a `fix:` written
+ * inside a doc comment or interpolated into a message is not mistaken for a declaration. A `fix`
+ * computed at runtime — a bare identifier, a parameter, a table lookup with no literal fallback —
+ * has nothing to read and is beyond a static scan; the gate says so rather than guessing.
+ *
+ * Three shapes, because a fix does not always arrive under a key. `@ultimat3/mcp`'s
+ * `readonly-sql.ts` hands every one of its fixes positionally to a local `rejected(cause, fix)`
+ * helper, so the key rule alone returned `[]` for the whole file — 20 non-test files in that
+ * package and the scanner saw fixes in three — and two stale `x db branch <name>` lines shipped
+ * through the hole.
+ *
+ * `imported` is the third: the helpers this file can call that it did not declare, resolved by
+ * `fix-imports.ts` and passed in, because a scanner over one string cannot open a second file.
+ * The four rules a call site is read under are `helperAt`'s and do not change with where the
+ * declaration was found.
+ */
+export function scanFixSites(
+  source: string,
+  at: string,
+  imported: readonly FixHelper[] = [],
+): FixScan {
+  const unreadable = { count: 0 };
+  const masked = maskLiterals(source);
+  const lineAt = lineIndex(masked);
+  const sites: FixSite[] = [];
+  for (const key of masked.matchAll(FIX_KEY)) {
+    const start = key.index + key[0].length;
+    for (const literal of valueLiterals(masked, source, start, lineAt)) {
+      sites.push({ ...literal, at });
+    }
+  }
+  // A name declared here wins over one imported under the same name: the declaration is what a
+  // call in this file actually reaches, and reading both would report one argument twice.
+  const local = scanFixHelpers(masked);
+  const names = new Set(local.map((helper) => helper.name));
+  for (const helper of [...local, ...imported.filter((one) => !names.has(one.name))]) {
+    sites.push(...helperFixSites(masked, source, at, helper, lineAt, unreadable));
+  }
+  return { sites, unreadable: unreadable.count };
+}
+
+/** The sites alone, for every caller that has no second file to resolve an import against. */
+export const scanFixes = (
+  source: string,
+  at: string,
+  imported: readonly FixHelper[] = [],
+): readonly FixSite[] => scanFixSites(source, at, imported).sites;

package/src/flag-number.ts

@@ -54,3 +54,14 @@ export const intFlagOr = (args: ParsedArgs, flag: IntFlag, fallback: number): nu
  * free port. Two ranges for one concept is the drift this constant exists to prevent.
  */
 export const PORT_RANGE = { min: 0, max: 65_535 } as const;
+
+/**
+ * A free-port suggestion the thing being fixed will actually accept. `port + 1` at the top of the
+ * range names 65536, which is not a port — so a `fix:` built that way reproduces a failure instead
+ * of ending one: `x doctor` emitted `x dev --port 65536`, which `x dev` refuses with
+ * `X_CLI_BAD_FLAG`. The neighbour below is a port; the one above does not exist. Here rather than
+ * beside either caller, because two ports-are-bounded rules is the drift `PORT_RANGE` above
+ * already exists to prevent.
+ */
+export const neighbouringPort = (port: number): number =>
+  port < PORT_RANGE.max ? port + 1 : PORT_RANGE.max - 1;