@ultimat3/cli 11.0.0 → 11.1.0

package/CLAUDE.md

@@ -256,6 +256,33 @@ that named the code in its `<PKG>_BORROWED_ERROR_CODES`. The docs check reads it
 framework's own `framework.manifest.json`, because a second scanner over a narrower file set is a
 manifest that claims completeness it does not have.
 
+**A `code:` is a literal, a module-scope const in the same file, or a finding** — `As of 2026-08-23`,
+and until then it was a literal or silence. `scanCodes` matched `code\s*[:=]\s*'X_…'`, so
+`const STALE = 'X_DOC_PACKAGE_GRAPH_STALE'` followed by `code: STALE` — the DRY thing to write, and
+what `scripts/package-map-graph.ts` really wrote — was a declaration to nobody: no manifest row, no
+row demanded on `wiki/Error-Codes.md`, no entry for `bun run gate-codes`, and `x errors explain`
+answering `X_ERROR_CODE_UNKNOWN` for a code the build throws. Silent, and in the **permissive**
+direction: the DRYer the author, the less the gate saw (#277).
+
+`scanCodeDeclarations` is that one pass, and it returns both halves. It resolves the identifier
+against the module-scope consts of the **same file** — anchored at column 0, which is what makes it
+module scope without a parser — and reports every name it cannot resolve as `X_ERROR_CODE_UNRESOLVED`
+rather than skipping it, which is the whole point: a scanner that reads only what it likes enforces
+only what it sees. `scanCodes` is its `.sites`, so the manifest, the docs check, `bun run gate-codes`
+and `x errors explain` (through `scanCodeFixSites`, which resolves the same way) cannot see different
+sets. Cross-file resolution was **refused** even though `fix-imports.ts` already does the harder
+version for `fix:`: it would make the scan async for every caller, and the finding is the better
+answer anyway — one file holds both the code and its only spelling.
+
+Three shapes are deliberately not judged, each measured over the framework and both tracked apps
+before the rule shipped. A name that resolves to something that is **not** a code is an answer, not
+a gap (`const STATUS_NOT_FOUND = 404` in `@ultimat3/realtime`'s NATS fake, the one live instance). A
+**table read** is not judged — `SEO_ERROR_CODES.metaMissing` is how `@ultimat3/seo` and
+`@ultimat3/ui` raise all 18 of their codes, and the registry those literals live in already declares
+them. A **lowercase** name is not judged: 164 sit at a `code:` position in this tree and every one is
+a type annotation (`readonly code: string`) or a re-raise (`code: opts.code`). Measured on all three
+roots: **0 findings**, so it enforces outright with no pin table.
+
 An empty `fix`, or a `fix` that says `check` / `make sure` / `try` / `see the docs` and names no
 command, call or file path, is `X_ERROR_FIX_INVALID`. A declared code the host's error reference
 does not name is `X_ERROR_CODE_UNDOCUMENTED` — `wiki/Error-Codes.md` here, nothing in a generated

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "11.0.0",
+  "version": "11.1.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -37,33 +37,33 @@
   },
   "dependencies": {
     "@babel/core": "^7.28.4",
-    "@ultimat3/action": "11.0.0",
-    "@ultimat3/admin": "11.0.0",
-    "@ultimat3/ai": "11.0.0",
-    "@ultimat3/auth": "11.0.0",
-    "@ultimat3/cache": "11.0.0",
-    "@ultimat3/core": "11.0.0",
-    "@ultimat3/db": "11.0.0",
-    "@ultimat3/entity": "11.0.0",
-    "@ultimat3/flags": "11.0.0",
-    "@ultimat3/http": "11.0.0",
-    "@ultimat3/i18n": "11.0.0",
-    "@ultimat3/jobs": "11.0.0",
-    "@ultimat3/mail": "11.0.0",
-    "@ultimat3/manifest": "11.0.0",
-    "@ultimat3/mcp": "11.0.0",
-    "@ultimat3/money": "11.0.0",
-    "@ultimat3/policy": "11.0.0",
-    "@ultimat3/pwa": "11.0.0",
-    "@ultimat3/query": "11.0.0",
-    "@ultimat3/realtime": "11.0.0",
-    "@ultimat3/render": "11.0.0",
-    "@ultimat3/schema": "11.0.0",
-    "@ultimat3/scraping": "11.0.0",
-    "@ultimat3/seo": "11.0.0",
-    "@ultimat3/storage": "11.0.0",
-    "@ultimat3/testing": "11.0.0",
-    "@ultimat3/time": "11.0.0",
+    "@ultimat3/action": "11.1.0",
+    "@ultimat3/admin": "11.1.0",
+    "@ultimat3/ai": "11.1.0",
+    "@ultimat3/auth": "11.1.0",
+    "@ultimat3/cache": "11.1.0",
+    "@ultimat3/core": "11.1.0",
+    "@ultimat3/db": "11.1.0",
+    "@ultimat3/entity": "11.1.0",
+    "@ultimat3/flags": "11.1.0",
+    "@ultimat3/http": "11.1.0",
+    "@ultimat3/i18n": "11.1.0",
+    "@ultimat3/jobs": "11.1.0",
+    "@ultimat3/mail": "11.1.0",
+    "@ultimat3/manifest": "11.1.0",
+    "@ultimat3/mcp": "11.1.0",
+    "@ultimat3/money": "11.1.0",
+    "@ultimat3/policy": "11.1.0",
+    "@ultimat3/pwa": "11.1.0",
+    "@ultimat3/query": "11.1.0",
+    "@ultimat3/realtime": "11.1.0",
+    "@ultimat3/render": "11.1.0",
+    "@ultimat3/schema": "11.1.0",
+    "@ultimat3/scraping": "11.1.0",
+    "@ultimat3/seo": "11.1.0",
+    "@ultimat3/storage": "11.1.0",
+    "@ultimat3/testing": "11.1.0",
+    "@ultimat3/time": "11.1.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/error-codes.ts

@@ -26,6 +26,10 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_ERROR_FIX_PATH_MISSING',
   'X_ERROR_CODE_UNDOCUMENTED',
   'X_ERROR_CODE_UNREGISTERED',
+  // The third: a `code:` the scan cannot read at all. `const STALE = 'X_…'` in another file and
+  // `code: STALE` here is invisible to every reader of the code set, and silence there is
+  // permissive — the DRYer the author, the less the gate sees (#277).
+  'X_ERROR_CODE_UNRESOLVED',
   // Reported as `Finding`s rather than thrown, and unregistered until now because of it — so
   // `x errors explain X_TYPECHECK_FAILED` refused a code `x verify` had just printed. A finding
   // carries an `X_*` code to the same reader a throw does; the registry is what makes that code
@@ -171,6 +175,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_ERROR_FIX_PATH_MISSING: "an error's fix line cites a file this repository does not have",
   X_ERROR_CODE_UNDOCUMENTED: 'a shipped error code has no row in the error reference',
   X_ERROR_CODE_UNREGISTERED: 'the error reference documents a code no package registers',
+  X_ERROR_CODE_UNRESOLVED: 'an error code is written as a name this repository cannot resolve',
   X_STORAGE_UNWRITABLE: 'the storage disk this process needs cannot be written to',
   X_STORAGE_SECRET_DEV: 'upload grants would be signed with the shipped development key',
   X_CLI_UNEXPECTED: 'the CLI itself failed',

package/src/error-contract.ts

@@ -13,8 +13,8 @@ import { citedPathProblem, FILE_TOKEN_PATTERN } from './fix-path';
 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 } from './ts-scan';
+import type { CodeSite, FixSite, UnresolvedCodeSite } from './ts-scan';
+import { isCodeRegistry, scanBorrowedCodes, scanCodeDeclarations, 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[] = [
@@ -259,6 +259,40 @@ export async function collectDeclaredCodes(root: string): Promise<readonly CodeS
   return [...sites.values()].map(([site]) => site).sort((a, b) => a.code.localeCompare(b.code));
 }
 
+/**
+ * A `code:` this scan could not turn into a code. Its own finding rather than a silent skip, which
+ * is the whole of #277: `const STALE = 'X_DOC_PACKAGE_GRAPH_STALE'` and then `code: STALE` is the
+ * DRY thing to write, `scripts/package-map-graph.ts` wrote it, and the code went into no manifest,
+ * demanded no row on the reference, was exempt from `bun run gate-codes` and could not be explained
+ * — every reader silent, and every one of them permissive. Resolution closes the same-file case;
+ * this closes the rest, because a scanner that reads only what it likes enforces only what it sees.
+ */
+const unresolvedCodeFinding = (site: UnresolvedCodeSite): Finding => ({
+  code: 'X_ERROR_CODE_UNRESOLVED',
+  cause: `the code at ${site.at}:${site.line} is the name ${site.name}, and no module-scope const in that file gives it a value — so the manifest, the reference page and "x errors explain" are all blind to whatever code it holds`,
+  fix: `write the X_* code as a string literal at ${site.at}:${site.line}, or declare it as a module-scope const in that same file`,
+  docs: ERROR_DOCS_URL,
+  at: `${site.at}:${site.line}`,
+});
+
+/**
+ * The other half of `collectDeclaredCodes`, on its own walk rather than folded into that one: this
+ * asks whether a file's codes are READABLE, and the collector's callers — `x manifest`, the gate's
+ * `errors` step, `bun run gate-codes` — want the codes and not the findings. It runs wherever
+ * source does, with no reference page to check against, which is why it is not a host check.
+ */
+export async function checkErrorCodeResolution(root: string): Promise<readonly Finding[]> {
+  const findings: Finding[] = [];
+  for await (const source of eachSourceFile(root)) {
+    if (isTest(source) || isGenerated(source)) continue;
+    const text = await Bun.file(join(root, source)).text();
+    for (const site of scanCodeDeclarations(text, source).unresolved) {
+      findings.push(unresolvedCodeFinding(site));
+    }
+  }
+  return findings;
+}
+
 /**
  * Every `X_*` code shipped source declares must appear on the repo's error reference. The page is
  * the host repo's to name — a framework monorepo publishes one, a generated app does not — which

package/src/index.ts

@@ -130,6 +130,7 @@ export {
   COMMAND_TOKENS,
   checkErrorCodeDocs,
   checkErrorCodeRegistry,
+  checkErrorCodeResolution,
   checkErrorFixes,
   checkErrorFixReport,
   collectDeclaredCodes,
@@ -283,11 +284,19 @@ export { belongsToType, discoverTests, sampleFiles } from './test-select';
 export type { ReproduceOptions, RunShardsOptions, Shard } from './test-shards';
 export { planShards, reproduceFor, runShards, shardArgs } from './test-shards';
 export { availableCpus, defaultWorkers, WORKER_CEILING } from './test-workers';
-export type { CodeFixSite, CodeSite, FixSite, SourceSite } from './ts-scan';
+export type {
+  CodeFixSite,
+  CodeScan,
+  CodeSite,
+  FixSite,
+  SourceSite,
+  UnresolvedCodeSite,
+} from './ts-scan';
 export {
   isCodeRegistry,
   maskLiterals,
   scanBorrowedCodes,
+  scanCodeDeclarations,
   scanCodeFixSites,
   scanCodes,
   stripComments,

package/src/mcp-errors.ts

@@ -62,6 +62,8 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_ERROR_CODE_UNDOCUMENTED: 'x verify --json   # the finding names the code and the missing page',
   X_ERROR_CODE_UNREGISTERED:
     'x errors list --json   # register the code in its package src/errors.ts, or move its row under "Reserved codes"',
+  X_ERROR_CODE_UNRESOLVED:
+    'x verify --json   # the finding names the file, the line and the name it could not resolve',
   X_CLI_UNEXPECTED: 'x doctor --json',
   X_TYPECHECK_FAILED: 'bunx tsc -b --pretty false',
   X_LINT_FAILED: 'bunx biome check --write .',

package/src/ts-scan.ts

@@ -19,6 +19,17 @@ export interface CodeSite extends SourceSite {
   readonly code: string;
 }
 
+export interface UnresolvedCodeSite extends SourceSite {
+  /** The identifier exactly as written at the `code:` position. */
+  readonly name: string;
+}
+
+/** One file's codes, and the names at a `code:` position this scan could not turn into one. */
+export interface CodeScan {
+  readonly sites: readonly CodeSite[];
+  readonly unresolved: readonly UnresolvedCodeSite[];
+}
+
 // `ReadonlySet`, so a consumer cannot mutate what every scan in this package reads.
 export const QUOTES: ReadonlySet<string> = new Set(["'", '"', '`']);
 export const OPENERS: ReadonlySet<string> = new Set(['(', '[', '{']);
@@ -202,27 +213,111 @@ const CODE_AT_KEY = /\bcode\s*[:=]\s*(['"`])(X_[A-Z0-9_]+)\1/g;
 const CODE_LITERAL = /(['"`])(X_[A-Z0-9_]+)\1/g;
 const CODE_KEY = /^[\t ]*(X_[A-Z0-9_]+)\s*:/gm;
 
+/**
+ * A `code` KEY, and never a member assignment: `found.code = SOMETHING` projects somebody else's
+ * code and declares none. The literal form above keeps its looser `\b` deliberately — a scanner
+ * that stopped collecting a code it has collected for four majors would shrink the manifest.
+ */
+const CODE_KEY_POSITION = /(?<![.\w$])code\s*[:=]\s*/g;
+
+/** Cheap enough to run on every file, so the masking pass below is paid only where it can pay. */
+const HAS_CODE_IDENTIFIER = /(?<![.\w$])code\s*[:=]\s*[A-Za-z_$]/;
+
+/** Sticky: the value expression is read at an exact offset, never out of a slice that may cut. */
+const VALUE_IDENTIFIER = /([A-Za-z_$][\w$]*)\s*([.([]?)/y;
+
+/**
+ * A module-scope `const NAME = 'X_…'`, and the names of every other module-scope const. Anchored
+ * at column 0, which is what makes it module scope without a parser: a `const` inside a function
+ * can be shadowed by another in a sibling scope, and a resolver that picked one of them would be
+ * guessing. The second set is the answer "that name IS declared here, and it is not a code" —
+ * `const STATUS_NOT_FOUND = 404` in `@ultimat3/realtime`'s NATS fake is the live instance, and a
+ * rule that reported it would be a rule the reader has to argue with.
+ */
+const CODE_CONST =
+  /^(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*(?::[^=\n]*)?=\s*(['"`])(X_[A-Z0-9_]+)\2/gm;
+const MODULE_CONST = /^(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*[:=]/gm;
+
+/** House shape for a constant. A lowercase name at a `code:` is a type annotation or a re-raise. */
+const CODE_CONSTANT_NAME = /^[A-Z][A-Z0-9_]+$/;
+
+interface ModuleConstants {
+  /** Name → the code it holds. */
+  readonly codes: ReadonlyMap<string, string>;
+  /** Every module-scope const name, code-valued or not. */
+  readonly names: ReadonlySet<string>;
+}
+
+function moduleConstants(text: string): ModuleConstants {
+  const codes = new Map<string, string>();
+  const names = new Set<string>();
+  for (const match of text.matchAll(MODULE_CONST)) names.add(match[1] as string);
+  for (const match of text.matchAll(CODE_CONST)) codes.set(match[1] as string, match[3] as string);
+  return { codes, names };
+}
+
+/**
+ * The bare identifier a key's value is, or `undefined` when the value is anything else. A member
+ * read, an index and a call are all refused: `SEO_ERROR_CODES.metaMissing` is how two packages
+ * raise every code they own, the registry branch below already collects those literals, and
+ * judging the read would report eighteen working sites as broken.
+ */
+function valueIdentifier(masked: string, from: number): string | undefined {
+  VALUE_IDENTIFIER.lastIndex = from;
+  const match = VALUE_IDENTIFIER.exec(masked);
+  return match === null || match[2] !== '' ? undefined : match[1];
+}
+
 /**
  * Codes this file declares: every `code:` / `code =` throw site, plus — in a package's own code
  * registry — every entry of its code list or title table, whichever shape it uses. A registry is
  * the only place a bare `X_*` literal is a declaration; anywhere else it is a reference (an env
  * var named `X_BUILD_ID`, an HTTP status map keyed by code) and collecting it would invent a code.
+ *
+ * A `code:` written as an IDENTIFIER is resolved against the module-scope consts of the same file,
+ * and reported as `unresolved` when nothing there gives it a value (#277). Both halves matter and
+ * neither is optional: `const STALE = 'X_DOC_PACKAGE_GRAPH_STALE'` is what a DRY author writes, and
+ * a scan that skipped it silently left the code out of the manifest, out of `wiki/Error-Codes.md`'s
+ * demanded rows, out of `bun run gate-codes` and out of `x errors explain` — permissive, and quiet.
+ * The identifier half reads the MASKED text: `packages/cli/src/templates/` emits app source by the
+ * dozen inside template literals, and a `code: STALE` in one of those is text, not a declaration.
  */
-export function scanCodes(source: string, at: string): readonly CodeSite[] {
+export function scanCodeDeclarations(source: string, at: string): CodeScan {
   const text = stripComments(source);
   const lineAt = lineIndex(text);
   const sites = new Map<string, CodeSite>();
+  const unresolved: UnresolvedCodeSite[] = [];
   const add = (code: string, index: number): void => {
     if (!sites.has(code)) sites.set(code, { at, line: lineAt(index), code });
   };
   for (const match of text.matchAll(CODE_AT_KEY)) add(match[2] as string, match.index);
+  if (HAS_CODE_IDENTIFIER.test(text)) {
+    const masked = maskLiterals(source);
+    const constants = moduleConstants(text);
+    for (const key of masked.matchAll(CODE_KEY_POSITION)) {
+      const name = valueIdentifier(masked, key.index + key[0].length);
+      if (name === undefined) continue;
+      const code = constants.codes.get(name);
+      if (code !== undefined) add(code, key.index);
+      else if (!constants.names.has(name) && CODE_CONSTANT_NAME.test(name)) {
+        unresolved.push({ at, line: lineAt(key.index), name });
+      }
+    }
+  }
   if (isCodeRegistry(text)) {
     for (const match of text.matchAll(CODE_LITERAL)) add(match[2] as string, match.index);
     for (const match of text.matchAll(CODE_KEY)) add(match[1] as string, match.index);
   }
-  return [...sites.values()];
+  return { sites: [...sites.values()], unresolved };
 }
 
+/**
+ * The codes alone, for every caller that has no report to attach a finding to. One scanner, one
+ * answer: the manifest, the docs check, `bun run gate-codes` and `x errors explain` all read this.
+ */
+export const scanCodes = (source: string, at: string): readonly CodeSite[] =>
+  scanCodeDeclarations(source, at).sites;
+
 export interface CodeFixSite extends CodeSite {
   /**
    * The fix literal exactly as written, `${…}` included. Absent when the throw site builds its
@@ -250,6 +345,8 @@ function soleLiteral(
   return found.length === 1 ? found[0] : undefined;
 }
 
+const CODE_NAME = /^X_[A-Z0-9_]+$/;
+
 /**
  * Every `X_*` code paired with the `fix:` written beside it — in the SAME object literal, which is
  * the whole rule. `new UltimateError({ code, cause, fix })` is the one shape this framework raises
@@ -263,6 +360,15 @@ function soleLiteral(
 export function scanCodeFixSites(source: string, at: string): readonly CodeFixSite[] {
   const masked = maskLiterals(source);
   const lineAt = lineIndex(masked);
+  // Lazily, because most files hold no `code:` at all and stripping is a whole extra pass over
+  // the text. Same resolver `scanCodeDeclarations` reads, so `x errors explain` can never see a
+  // smaller set of throw sites than the manifest does.
+  let constants: ModuleConstants | undefined;
+  const constantCode = (name: string | undefined): string | undefined => {
+    if (name === undefined) return undefined;
+    constants ??= moduleConstants(stripComments(source));
+    return constants.codes.get(name);
+  };
   const keys = new Map<number, { readonly kind: 'code' | 'fix'; readonly from: number }>();
   for (const key of masked.matchAll(CODE_OR_FIX_KEY)) {
     keys.set(key.index, {
@@ -293,11 +399,16 @@ export function scanCodeFixSites(source: string, at: string): readonly CodeFixSi
     const scope = stack.at(-1);
     if (key === undefined || scope === undefined) continue;
     const literal = soleLiteral(masked, source, key.from, lineAt);
-    if (literal === undefined) continue;
     if (key.kind === 'fix') {
-      if (!fixes.has(scope)) fixes.set(scope, literal.fix);
-    } else if (/^X_[A-Z0-9_]+$/.test(literal.fix) && !codes.has(scope)) {
-      codes.set(scope, { at, line: literal.line, code: literal.fix });
+      if (literal !== undefined && !fixes.has(scope)) fixes.set(scope, literal.fix);
+      continue;
+    }
+    // A fix has no second reading, so it stays literal-only; a code has exactly one, which is the
+    // module-scope const its own file declares it in.
+    const code =
+      literal === undefined ? constantCode(valueIdentifier(masked, key.from)) : literal.fix;
+    if (code !== undefined && CODE_NAME.test(code) && !codes.has(scope)) {
+      codes.set(scope, { at, line: literal?.line ?? lineAt(key.from), code });
     }
   }
   return [...codes].map(([scope, site]) => {

package/src/verify-checks.ts

@@ -24,7 +24,7 @@ import { checkBudgets, readBuildStats } from './budgets';
 import { checkDestructiveMigrations } from './db-destructive';
 import { checkDocumentStyles, documentSurfaces } from './document-styles';
 import { checkSourceDrift } from './drift';
-import { checkErrorFixReport } from './error-contract';
+import { checkErrorCodeResolution, checkErrorFixReport } from './error-contract';
 import { guardFindings } from './guards';
 import { catalogFindings } from './i18n-registration';
 import { liveRouteFindings } from './live-routes';
@@ -125,7 +125,15 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
     // it does not have. "checked 412, could not read 27" is what a reader can act on.
     async run(ctx) {
       const report = await checkErrorFixReport(ctx.root);
-      const findings = [...report.findings, ...(await hostFindings(ctx, 'errors'))];
+      // The third rule on this step, and the one that is about the code rather than the fix: a
+      // `code:` reached through a name nothing in its own file declares is a code no reader of the
+      // set can see — not the manifest, not the reference page's coverage rule, not
+      // `x errors explain`. It runs here because it needs source and nothing else (#277).
+      const findings = [
+        ...report.findings,
+        ...(await checkErrorCodeResolution(ctx.root)),
+        ...(await hostFindings(ctx, 'errors')),
+      ];
       return {
         ...fromFindings(findings),
         output: msg('cli.verify.fixCoverage', {