@ultimat3/cli 4.0.0 → 5.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -35,28 +35,28 @@
     "dev": "bun run src/bin.ts dev"
   },
   "dependencies": {
-    "@ultimat3/action": "4.0.0",
-    "@ultimat3/admin": "4.0.0",
-    "@ultimat3/ai": "4.0.0",
-    "@ultimat3/cache": "4.0.0",
-    "@ultimat3/core": "4.0.0",
-    "@ultimat3/db": "4.0.0",
-    "@ultimat3/entity": "4.0.0",
-    "@ultimat3/http": "4.0.0",
-    "@ultimat3/i18n": "4.0.0",
-    "@ultimat3/jobs": "4.0.0",
-    "@ultimat3/mail": "4.0.0",
-    "@ultimat3/manifest": "4.0.0",
-    "@ultimat3/mcp": "4.0.0",
-    "@ultimat3/policy": "4.0.0",
-    "@ultimat3/pwa": "4.0.0",
-    "@ultimat3/query": "4.0.0",
-    "@ultimat3/realtime": "4.0.0",
-    "@ultimat3/render": "4.0.0",
-    "@ultimat3/schema": "4.0.0",
-    "@ultimat3/seo": "4.0.0",
-    "@ultimat3/storage": "4.0.0",
-    "@ultimat3/testing": "4.0.0",
-    "@ultimat3/time": "4.0.0"
+    "@ultimat3/action": "5.0.0",
+    "@ultimat3/admin": "5.0.0",
+    "@ultimat3/ai": "5.0.0",
+    "@ultimat3/cache": "5.0.0",
+    "@ultimat3/core": "5.0.0",
+    "@ultimat3/db": "5.0.0",
+    "@ultimat3/entity": "5.0.0",
+    "@ultimat3/http": "5.0.0",
+    "@ultimat3/i18n": "5.0.0",
+    "@ultimat3/jobs": "5.0.0",
+    "@ultimat3/mail": "5.0.0",
+    "@ultimat3/manifest": "5.0.0",
+    "@ultimat3/mcp": "5.0.0",
+    "@ultimat3/policy": "5.0.0",
+    "@ultimat3/pwa": "5.0.0",
+    "@ultimat3/query": "5.0.0",
+    "@ultimat3/realtime": "5.0.0",
+    "@ultimat3/render": "5.0.0",
+    "@ultimat3/schema": "5.0.0",
+    "@ultimat3/seo": "5.0.0",
+    "@ultimat3/storage": "5.0.0",
+    "@ultimat3/testing": "5.0.0",
+    "@ultimat3/time": "5.0.0"
   }
 }

package/src/cmd-errors.ts

@@ -1,3 +1,4 @@
+import { singleLine } from '@ultimat3/core';
 // `x errors explain <CODE>` / `x errors list` — the error table, programmatically. An agent that
 // hits an `X_*` code should not have to leave the terminal to learn what it means, and a code it
 // invented should come back refused: the answer to an unregistered code is "no such code", never
@@ -35,9 +36,9 @@ const asJson = (explanation: ErrorExplanation): JsonValue => {
 
 /** The 3-line contract format, minus the leading blank code line `renderFinding` would add. */
 const detailLines = (explanation: ErrorExplanation): readonly string[] => [
-  `  cause: ${explanation.cause}`,
-  `  fix:   ${explanation.fix}`,
-  `  docs:  ${explanation.docs}`,
+  `  cause: ${singleLine(explanation.cause)}`,
+  `  fix:   ${singleLine(explanation.fix)}`,
+  `  docs:  ${singleLine(explanation.docs)}`,
 ];
 
 function explainOne(code: string): CommandResult {
@@ -69,7 +70,7 @@ function listAll(catalog: ErrorCatalog): CommandResult {
     ok: catalog.failed.length === 0,
     command: 'errors',
     summary: msg('cli.errors.count', { count: all.length }),
-    lines: all.map((entry) => `  ${entry.code.padEnd(30)} ${entry.cause}`),
+    lines: all.map((entry) => `  ${entry.code.padEnd(30)} ${singleLine(entry.cause)}`),
     findings: catalog.failed,
     data: {
       codes: all.map(asJson),

package/src/fix-scan.ts

@@ -201,6 +201,109 @@ function helperFixSites(
   return sites;
 }
 
+/**
+ * The identifier a `fix:` value LOOKS UP, when the value is a lookup and nothing else:
+ * `fix: SQLSTATE_FIXES[code]`, `fix: SQLSTATE_FIXES.X_DB_POOL_EXHAUSTED`, and the `.replace(…)`
+ * that `@ultimat3/db` puts after the first of those. The value expression then holds NO literal at
+ * its own depth, so `valueLiterals` answered `[]` and the site was dropped without being counted —
+ * six shipped fix lines that no rule had ever read, and nothing to catch a seventh (#97).
+ */
+/** A constant's spelling, and the only head whose failure to resolve is worth counting. */
+const TABLE_NAME = /^[A-Z][A-Z0-9_]*$/;
+
+const LOOKUP_HEAD = /^\s*([A-Za-z_$][\w$]*)\s*[[.]/;
+
+/** The one wrapper a table is allowed to arrive in. Any other call is a factory, not a table. */
+const FREEZE = 'Object.freeze(';
+
+/**
+ * Where the object literal bound to `name` opens in this file, or `undefined` when this file does
+ * not declare one. One hop and same-file only, deliberately: a table is a `const` a few lines
+ * above the factory that reads it in every instance measured here, and following a chain or a
+ * second file is where a text scan starts guessing.
+ *
+ * Conservative in three ways, and each one answers `undefined` so the caller counts the site
+ * instead of reading an unrelated object. **A name declared twice is not resolved at all**: this
+ * scan tracks no lexical scope, so a nested `const FIXES` would otherwise be read as the outer one
+ * and the gate would judge fix lines from a table the call site cannot reach. **Only a bare `{…}`
+ * or the exact `Object.freeze({…})`**: `makeTable({…})` is a call whose result this cannot know,
+ * and reading its argument would report the input to a factory as the factory's output. **And only
+ * a `const`** — a `let` can be reassigned, and the last assignment is what a call reads.
+ *
+ * `name` is always `LOOKUP_HEAD`'s capture, `[A-Za-z_$][\w$]*`, so it carries no regex
+ * metacharacter and the pattern below is linear whatever a source file contains.
+ */
+function tableOpen(masked: string, name: string): number | undefined {
+  const declaration = new RegExp(`(?<![.\\w$])const\\s+${name}\\s*(?::[^=;]*)?=\\s*`, 'g');
+  const first = declaration.exec(masked);
+  if (first === null || declaration.exec(masked) !== null) return undefined;
+  const rest = masked.slice(first.index + first[0].length);
+  const value = rest.trimStart();
+  const skipped = rest.length - value.length;
+  const from = first.index + first[0].length + skipped;
+  if (value.startsWith('{')) return from;
+  if (!value.startsWith(FREEZE)) return undefined;
+  const inner = value.slice(FREEZE.length).trimStart();
+  return inner.startsWith('{') ? from + (value.length - inner.length) : undefined;
+}
+
+/** Where this entry's value stops: the next `,` at the entry's own depth, or the table's `}`. */
+function entryEnd(masked: string, from: number): number {
+  let depth = 0;
+  for (let i = from; i < masked.length; i += 1) {
+    const ch = masked[i] as string;
+    if (QUOTES.has(ch)) {
+      i = Math.max(i, endOfLiteral(masked, i) - 1);
+      continue;
+    }
+    if (OPENERS.has(ch)) depth += 1;
+    else if (CLOSERS.has(ch)) {
+      if (depth === 0) return i;
+      depth -= 1;
+    } else if (depth === 0 && ch === ',') return i;
+  }
+  return masked.length;
+}
+
+/**
+ * Every fix string a table holds, read at its entries' own depth. A value that is a concatenation
+ * yields one site per literal, exactly as a `fix:` key does — the rule is per line, and half a fix
+ * carrying a banned phrase is still a fix line an agent is handed.
+ */
+function tableFixSites(
+  masked: string,
+  source: string,
+  at: string,
+  open: number,
+  lineAt: (index: number) => number,
+): readonly FixSite[] {
+  const sites: FixSite[] = [];
+  let depth = 0;
+  for (let i = open; i < masked.length; i += 1) {
+    const ch = masked[i] as string;
+    // A quoted KEY (`'23505': '…'`) is skipped whole, so its closing quote cannot be read as the
+    // opener of the value and shift every literal after it by one.
+    if (QUOTES.has(ch)) {
+      i = Math.max(i, endOfLiteral(masked, i) - 1);
+      continue;
+    }
+    if (OPENERS.has(ch)) depth += 1;
+    else if (CLOSERS.has(ch)) {
+      depth -= 1;
+      if (depth === 0) break;
+    } else if (depth === 1 && ch === ':') {
+      for (const literal of valueLiterals(masked, source, i + 1, lineAt)) {
+        sites.push({ ...literal, at });
+      }
+      // Past the whole value, because `valueLiterals` already read all of it. A conditional value
+      // carries a SECOND colon at this same depth — `a: on ? 'x doctor' : 'x verify'` — and
+      // resuming here would read its else branch a second time and report one entry twice.
+      i = Math.max(i, entryEnd(masked, i + 1) - 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`
@@ -227,11 +330,29 @@ export function scanFixSites(
   const masked = maskLiterals(source);
   const lineAt = lineIndex(masked);
   const sites: FixSite[] = [];
+  const tables = new Set<string>();
   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 });
+    const literals = valueLiterals(masked, source, start, lineAt);
+    for (const literal of literals) sites.push({ ...literal, at });
+    // A lookup is recorded whether or not the expression also held a literal: `TABLE[k] ?? 'x'`
+    // is two answers and both are fix lines. The NAME is collected rather than the table resolved
+    // here, so a table read at four call sites is checked once instead of reported four times.
+    const head = LOOKUP_HEAD.exec(masked.slice(start, start + 200))?.[1];
+    if (head !== undefined) tables.add(head);
+  }
+  for (const name of tables) {
+    const open = tableOpen(masked, name);
+    if (open !== undefined) {
+      sites.push(...tableFixSites(masked, source, at, open, lineAt));
+      continue;
     }
+    // Nothing resolved. `init.fix` is a property of a parameter, already read wherever that
+    // parameter was filled, and counting it would make the coverage line describe re-passes rather
+    // than blind spots. A SCREAMING_SNAKE head is the one that cannot be that: it names a constant,
+    // and a constant this file does not declare is a table in another file — a real hole, and the
+    // one shape this scan says out loud instead of dropping.
+    if (TABLE_NAME.test(name)) unreadable.count += 1;
   }
   // 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.

package/src/output.ts

@@ -2,7 +2,7 @@
 // and the JSON renderer are projections of it, so `--json` can never drift from the terminal
 // output (axiom 4). The human renderer owns the canonical 3-line error format.
 
-import { renderThrowable, stringField } from '@ultimat3/core';
+import { renderThrowable, singleLine, stringField } from '@ultimat3/core';
 import { msg } from './messages';
 
 export interface Finding {
@@ -113,13 +113,16 @@ const summaryOf = (value: UltimateErrorShape): string =>
  * ```
  */
 export function renderFinding(finding: Finding, indent = ''): string {
-  const head = finding.at === undefined ? finding.code : `${finding.code} (${finding.at})`;
+  // Every field through `singleLine`: this is the format's only renderer for the terminal and CI
+  // logs, and a `cause` carrying a newline would print a line a reader takes for a real finding.
+  const code = singleLine(finding.code);
+  const head = finding.at === undefined ? code : `${code} (${singleLine(finding.at)})`;
   const lines = [
     `${indent}${head}`,
-    `${indent}  cause: ${finding.cause}`,
-    `${indent}  fix:   ${finding.fix}`,
+    `${indent}  cause: ${singleLine(finding.cause)}`,
+    `${indent}  fix:   ${singleLine(finding.fix)}`,
   ];
-  if (finding.docs !== undefined) lines.push(`${indent}  docs:  ${finding.docs}`);
+  if (finding.docs !== undefined) lines.push(`${indent}  docs:  ${singleLine(finding.docs)}`);
   return lines.join('\n');
 }
 

package/src/templates/scaffold-repo.ts

@@ -146,7 +146,7 @@ export const config = defineConfig({
   // Env KEYS, never the value: the same image deploys to every environment. The database is
   // configured entirely from the environment — \`DATABASE_URL\` and \`DATABASE_POOL_MAX\`.
   cache: { driver: 'memory', tiers: ['memo', 'lru'] },
-  jobs: { driver: 'postgres', queues: ['${app.kebab}-default'], concurrency: 4 },
+  jobs: { queues: ['${app.kebab}-default'], concurrency: 4 },
   // In-process transport by default; set urlEnv and transport: 'nats' to scale past one node.
   realtime: { enabled: true, tier: 'live-queries', transport: 'memory' },
   pwa: { enabled: true, offline: 'runtime' },