@ultimat3/cli 3.0.0 → 4.0.0

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-reads.ts

@@ -0,0 +1,114 @@
+// A flag a command declares and nothing reads. The parser accepts every declared flag, so a flag
+// with no reader is not a parse error and not a type error — it is a promise in the help text with
+// no code behind it, and only a rule over the two halves together can see that.
+//
+// The bound of this rule, stated where it is enforced: it sees the flag NAME reaching a reader,
+// not the value reaching an effect. `x deploy --critical` satisfied it by being written into the
+// plan JSON, where nothing read the field; that flag is deleted rather than wired, and a second
+// one of its shape would pass here too.
+
+// `join`/`relative` are `node:`-only by necessity: Bun exposes no path-join primitive.
+import { join, relative } from 'node:path';
+import { docsFor } from './error-codes';
+import type { Finding } from './output';
+import type { CommandSpec, FlagSpec } from './parse';
+import { GLOBAL_FLAGS } from './parse';
+import { stripComments } from './ts-scan';
+
+/** A flag as declared, with the command that declares it. */
+export interface DeclaredFlag {
+  readonly command: string;
+  readonly flag: FlagSpec;
+}
+
+/**
+ * Every flag a command declares. The global four are excluded: `--json`, `--help`, `--cwd` and
+ * `--verbose` are the parser's and the dispatcher's, read once for every command rather than by
+ * the command that lists them, and a per-command rule would report all 30 of them as unread.
+ */
+export function declaredFlags(specs: readonly CommandSpec[]): readonly DeclaredFlag[] {
+  const global = new Set(GLOBAL_FLAGS.map((flag) => flag.name));
+  return specs.flatMap((spec) =>
+    (spec.flags ?? [])
+      .filter((flag) => !global.has(flag.name))
+      .map((flag) => ({ command: spec.name, flag })),
+  );
+}
+
+/** A flag name is `[a-z][a-z-]*`, so nothing in it is a regex metacharacter to escape. */
+const literalOf = (name: string): RegExp => new RegExp(`(['"\`])${name}\\1`, 'g');
+
+/**
+ * The declaration itself, which is never a read. `{ name: 'critical', … }` and its `short:` twin
+ * are the two places the name appears as a spec field; every other occurrence of the bare literal
+ * is a reader — `flagBool(ctx.args, 'critical')`, a table key, a constant the reader indexes with.
+ */
+const declarationOf = (name: string): RegExp =>
+  new RegExp(`(?:name|short)\\s*:\\s*(['"\`])${name}\\1`, 'g');
+
+const countIn = (text: string, pattern: RegExp): number => [...text.matchAll(pattern)].length;
+
+/**
+ * Whether this file reads the flag, as against merely declaring it. Deliberately generous: a flag
+ * consumed only by being echoed into `--json`, or read through a shared constant rather than by
+ * name at the call site, is still read — the rule exists to catch a flag NOTHING mentions, and a
+ * gate that guessed at intent would report findings about working commands.
+ */
+export const readsFlag = (text: string, name: string): boolean =>
+  countIn(text, literalOf(name)) > countIn(text, declarationOf(name));
+
+const declaresFlag = (text: string, name: string): boolean =>
+  countIn(text, declarationOf(name)) > 0;
+
+const unreadFinding = (declared: DeclaredFlag, at: string): Finding => ({
+  code: 'X_CLI_FLAG_UNREAD',
+  cause: `x ${declared.command} declares --${declared.flag.name} ("${declared.flag.summary}") and no file in the CLI's source reads it, so the flag parses and changes nothing`,
+  fix: `read it in ${at} with flag${declared.flag.type === 'boolean' ? 'Bool' : 'String'}(ctx.args, '${declared.flag.name}'), or delete it from the spec's flags`,
+  docs: docsFor('X_CLI_FLAG_UNREAD'),
+  at,
+});
+
+/**
+ * Every declared flag held to one rule: something reads it.
+ *
+ * Scans source rather than the runtime, because "is this value ever consumed?" is not a question
+ * a `run` can be asked without running it — and running every command is not a check, it is the
+ * program. Comments are stripped first: a flag named only in the prose above the spec is not read,
+ * and a scanner that counted it would pass exactly the flags most likely to be dead.
+ */
+export async function checkFlagReads(
+  specs: readonly CommandSpec[],
+  srcDir: string,
+): Promise<readonly Finding[]> {
+  const paths: string[] = [];
+  try {
+    for await (const path of new Bun.Glob('**/*.ts').scan({ cwd: srcDir, absolute: false })) {
+      if (!/\.test\.tsx?$/.test(path)) paths.push(path);
+    }
+  } catch {
+    // The directory is not there. `Bun.Glob.scan` raises rather than yielding nothing, so the
+    // absent case has to be caught here — see the `texts.size` guard below for why it answers [].
+    // The scan is ALL that is inside the `try`, deliberately: a file the scan found and this
+    // cannot read must propagate, or an unreadable source answers "no findings" and the rule
+    // reports green over the half it could not see.
+    return [];
+  }
+  const texts = new Map<string, string>();
+  for (const path of paths) {
+    texts.set(path, stripComments(await Bun.file(join(srcDir, path)).text()));
+  }
+  // No CLI source under this root: the rule holds two halves against each other and only one is
+  // here, so there is nothing it can decide. Derived, not "is this the framework repo" — the same
+  // condition `scripts/release-workflow.ts` uses for a tree with no publishable workspace. Scanning
+  // on would report EVERY declared flag as unread, which is the false-positive direction and the
+  // one that trains a reader to ignore the check.
+  if (texts.size === 0) return [];
+  const findings: Finding[] = [];
+  for (const declared of declaredFlags(specs)) {
+    const name = declared.flag.name;
+    if ([...texts.values()].some((text) => readsFlag(text, name))) continue;
+    const declaringFile = [...texts].find(([, text]) => declaresFlag(text, name))?.[0];
+    findings.push(unreadFinding(declared, join(relative('', srcDir), declaringFile ?? '')));
+  }
+  return findings;
+}

package/src/i18n-audit.ts

@@ -8,6 +8,7 @@
 // root-relative POSIX shape every CLI-reported path is keyed by.
 import { existsSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
+import { renderThrowable } from '@ultimat3/core';
 import type { Catalog, Extraction, ExtractReport, Locale } from '@ultimat3/i18n';
 import {
   auditCatalogs,
@@ -51,7 +52,7 @@ function parseCatalogJson(path: string, raw: string): unknown {
   try {
     return JSON.parse(raw);
   } catch (error) {
-    throw catalogInvalid(path, error instanceof Error ? error.message : String(error));
+    throw catalogInvalid(path, renderThrowable(error));
   }
 }
 

package/src/index.ts

@@ -117,12 +117,14 @@ export {
 } from './error-catalog';
 export type { CliErrorCode } from './error-codes';
 export { CLI_ERROR_CODES, CLI_ERROR_TITLES } from './error-codes';
+export type { ErrorFixReport } from './error-contract';
 export {
   BANNED_PHRASES,
   COMMAND_TOKENS,
   checkErrorCodeDocs,
   checkErrorCodeRegistry,
   checkErrorFixes,
+  checkErrorFixReport,
   collectDeclaredCodes,
   documentedCodes,
   fixProblem,
@@ -167,6 +169,12 @@ export {
   fixCitations,
   loadCommandCatalog,
 } from './fix-command';
+export type { HelperResolver } from './fix-imports';
+export { candidatePaths, createHelperResolver, scanImports } from './fix-imports';
+export type { FixHelper, FixScan } from './fix-scan';
+export { scanFixes, scanFixHelpers, scanFixSites } from './fix-scan';
+export type { DeclaredFlag } from './flag-reads';
+export { checkFlagReads, declaredFlags, readsFlag } from './flag-reads';
 export type { Guard } from './guards';
 export { findingProblem, GUARD_DIR, guardFindings, guardPaths } from './guards';
 export type { DrainFailure, DrainOutcome, DrainSkip } from './jobs-drain';
@@ -241,7 +249,6 @@ export {
   scanBorrowedCodes,
   scanCodeFixSites,
   scanCodes,
-  scanFixes,
   stripComments,
 } from './ts-scan';
 // The one spelling rule for a `references` entry. Exported because the two gate scripts ask the

package/src/jobs-drain.ts

@@ -75,7 +75,12 @@ async function copySteps(source: JobDriver, target: JobDriver, runId: string): P
 /**
  * Hand a leased job back exactly as the drain found it. `countsAsAttempt: false` is the point:
  * a transfer that failed is not a failed attempt, and burning one per `x jobs drain` retry would
- * dead-letter a job nobody ever ran. It parks as `suspended`, which every driver claims.
+ * dead-letter a job nobody ever ran.
+ *
+ * It returns to `ready`, which is what "as the drain found it" means — the drain leased a ready
+ * job and could not move it. It used to land in `suspended`, not by intent but because
+ * `countsAsAttempt: false` was the only bit the drivers had and `step.sleep` had claimed it;
+ * `NackOptions.park` now carries the suspension, so the two callers no longer share one meaning.
  */
 async function releaseLease(source: JobDriver, id: string): Promise<void> {
   try {

package/src/mcp-errors.ts

@@ -22,6 +22,11 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   // Runnable first, the narrowing behind a `#`: `x help <command> --json` pasted into a shell
   // is a redirect, not a command, and this table is copied verbatim by whoever reads it.
   X_CLI_BAD_FLAG: 'x help --json   # then narrow to the command the cause names',
+  // Not an `x` command: this rule is about the CLI's OWN declarations, it can only fire in this
+  // repo, and the suite that applies it is what reproduces the finding. A placeholder command
+  // would fail this table's own no-`<placeholder>` rule, and rightly — it would not run.
+  X_CLI_FLAG_UNREAD:
+    'bun test packages/cli/src/flag-reads.test.ts   # the finding names the flag and the file to read it in',
   X_VERIFY_FAILED: 'x verify --json',
   X_NOT_IN_APP: 'x new myapp --json && cd myapp',
   X_BUN_VERSION: 'bun upgrade',

package/src/mcp-host.ts

@@ -4,7 +4,7 @@
 // is a second catalog of routes, entities, actions, queries or jobs.
 
 import { join } from 'node:path';
-import { agentActor, isUltimateError, UltimateError } from '@ultimat3/core';
+import { agentActor, isUltimateError, renderThrowable, UltimateError } from '@ultimat3/core';
 import type { DbClient } from '@ultimat3/db';
 import {
   ensureReadOnlyRole,
@@ -199,7 +199,9 @@ function capabilities(input: DevHostInput, lazy: LazyServices): DevCapabilities
         if (isUltimateError(error)) throw error;
         throw new UltimateError({
           code: 'X_DB_MIGRATE_FAILED',
-          cause: error instanceof Error ? error.message : String(error),
+          // The blessed total renderer: `String(error)` runs the value's own `toString`, and
+          // this is the last hop before an agent is handed the three-line result.
+          cause: renderThrowable(error),
           fix: 'x db reset',
         });
       }

package/src/messages.ts

@@ -170,6 +170,9 @@ const CATALOG = {
   'cli.verify.passSkipped':
     '{passed} of {count} steps passed in {ms}ms — {skipped} skipped: {names}',
   'cli.verify.failSkipped': '{failed} of {count} steps failed — {skipped} skipped: {names}',
+  // The `errors` step's own coverage, in `output`: a scan without a parser reads most fix lines
+  // and not all of them, and a step that reports findings alone claims a completeness it lacks.
+  'cli.verify.fixCoverage': 'checked {checked} fix line(s), could not read {unreadable}',
   'cli.verify.serial': 'serial',
   'cli.verify.workers': '{workers} workers',
   'cli.env.checked': '{count} declared variable(s), all present and valid',

package/src/otlp-export.ts

@@ -7,6 +7,8 @@ import {
   configureMetrics,
   configureTelemetry,
   logger,
+  noopExporter,
+  noopMetricExporter,
   onShutdown,
   otlpMetricExporter,
   otlpSpanExporter,
@@ -29,6 +31,14 @@ export const METRIC_EXPORT_INTERVAL_MS = 60_000;
  * Both are registered with `onShutdown(..., { phase: 'close' })`: the last spans of a drain are
  * the ones that explain the drain, and a process that exits with a full queue loses exactly the
  * window an operator went looking for.
+ *
+ * The release UNINSTALLS what it installed, per signal. `configureTelemetry`/`configureMetrics`
+ * merge into process-global state, so stopping the timer and dropping the drain hooks left the
+ * first boot's exporter configured: a second `serveApp` in the same process exported its spans
+ * into a released exporter — queued against a collector nothing will flush to, on a timer nothing
+ * clears. `cmd-dev.ts`'s `stop()` hands back `noopExporter` for exactly this reason. Per signal and
+ * never unconditionally: `x dev` configures a trace RECORDER before calling this, and a boot that
+ * installed no exporter must not uninstall one it never owned.
  */
 export function startOtlpExport(env: Env = process.env): () => void {
   const releases: (() => void)[] = [];
@@ -41,6 +51,9 @@ export function startOtlpExport(env: Env = process.env): () => void {
   if (traces !== undefined) {
     const exporter = otlpSpanExporter({ endpoint: traces });
     configureTelemetry({ exporter });
+    // Pushed first, so the reversed run below applies it LAST — after the drain hook is dropped,
+    // the same order `cmd-dev.ts` releases the recorder in.
+    releases.push(() => configureTelemetry({ exporter: noopExporter }));
     releases.push(onShutdown('otlp-traces', () => exporter.shutdown(), { phase: 'close' }));
     logger.info('ultimate otlp traces', { endpoint: traces });
   }
@@ -49,6 +62,7 @@ export function startOtlpExport(env: Env = process.env): () => void {
   if (metrics !== undefined) {
     const exporter = otlpMetricExporter({ endpoint: metrics });
     configureMetrics({ exporter });
+    releases.push(() => configureMetrics({ exporter: noopMetricExporter }));
     // The push loop, and not only the exporter: `configureMetrics` names where a snapshot goes
     // and nothing decides when one is taken, so without this the collector receives one export —
     // the drain's — for the whole life of the process.

package/src/parse.ts

@@ -47,7 +47,12 @@ export interface CommandSpec {
    */
   readonly subcommandPositionals?: Readonly<Record<string, readonly string[]>>;
   readonly flags?: readonly FlagSpec[];
-  /** Command needs an app root (`app.config.ts`) — the dispatcher enforces it. */
+  /**
+   * Command needs an app root (`app.config.ts`). The dispatcher enforces it — `dispatch.ts`, before
+   * `target.run` — and until 2026-08 nothing read this field at all: the guarantee was kept only by
+   * each of the 17 declaring commands remembering to call `requireAppRoot` itself, so a new command
+   * that declared it and forgot the call ran outside an app with no refusal.
+   */
   readonly requiresApp?: boolean;
 }