@ultimat3/cli 2.0.0 → 4.0.0

package/src/ts-scan.ts

@@ -1,7 +1,8 @@
-// Reading two things out of TypeScript source without a parser: the strings a `fix:` can evaluate
-// to, and the `X_*` codes a package declares. Deliberately not `tsc` — a regex over a masked file
-// is the whole job. Masking is the load-bearing part: the contract's own 3-line rendering appears
-// verbatim in doc blocks and template literals, and a scanner that reads it as code invents work.
+// Reading TypeScript source without a parser: the masking every scan here shares, and the `X_*`
+// codes a package declares. Deliberately not `tsc` — a regex over a masked file is the whole job.
+// Masking is the load-bearing part: the contract's own 3-line rendering appears verbatim in doc
+// blocks and template literals, and a scanner that reads it as code invents work. What a `fix:`
+// can evaluate to is `fix-scan.ts`, which reads these primitives and is the only file that grew.
 
 export interface SourceSite {
   /** Repo-relative file the site was read from. */
@@ -18,9 +19,10 @@ export interface CodeSite extends SourceSite {
   readonly code: string;
 }
 
-const QUOTES = new Set(["'", '"', '`']);
-const OPENERS = new Set(['(', '[', '{']);
-const CLOSERS = new Set([')', ']', '}']);
+// `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(['(', '[', '{']);
+export const CLOSERS: ReadonlySet<string> = new Set([')', ']', '}']);
 const WORD = /[\w$]/;
 
 /** After one of these words a `/` opens a regex; after any other identifier it divides. */
@@ -28,14 +30,23 @@ const REGEX_AFTER_WORDS = new Set(
   'await case delete do else in instanceof new of return throw typeof void yield'.split(' '),
 );
 
-/** Index just past the closing quote of the literal opening at `from`, or the end of the text. */
-function endOfLiteral(text: string, from: number): number {
+/**
+ * Index just past the closing quote of the literal opening at `from`, or `from + 1` when a `'`/`"`
+ * does not close on its own line — which makes it text, not a literal. Only a template literal may
+ * span a newline, so the apostrophe in `<p>Don't panic</p>` is JSX text; read as an opener it ran
+ * forward to the next `'` in the FILE (the next `fix:` line) and blanked every declaration between,
+ * silently emptying the `errors` gate for the whole file. Same rule `endOfRegex` applies to a `/`.
+ * An escaped newline is still a continuation: the escape is consumed before the line test.
+ */
+export function endOfLiteral(text: string, from: number): number {
   const quote = text[from] as string;
+  const spansLines = quote === '`';
   for (let i = from + 1; i < text.length; i += 1) {
     if (text[i] === '\\') i += 1;
     else if (text[i] === quote) return i + 1;
+    else if (!spansLines && text[i] === '\n') return from + 1;
   }
-  return text.length;
+  return spansLines ? text.length : from + 1;
 }
 
 /**
@@ -123,7 +134,7 @@ export const maskLiterals = (text: string): string => blankRegions(text, true);
  * asking for a line per literal pays once per literal — measured at ~15s over the framework's own
  * package tree, against ~1s for the same walk with this. One offset table, then a binary search.
  */
-function lineIndex(text: string): (index: number) => number {
+export function lineIndex(text: string): (index: number) => number {
   const newlines: number[] = [];
   for (let i = 0; i < text.length; i += 1) if (text[i] === '\n') newlines.push(i);
   return (index) => {
@@ -144,7 +155,7 @@ function lineIndex(text: string): (index: number) => number {
  * instead of silently skipped; the depth rule is what keeps `command.join(' ')`'s separator and
  * `table['key']`'s key out — an argument is not a fix.
  */
-function valueLiterals(
+export function valueLiterals(
   masked: string,
   source: string,
   from: number,
@@ -156,6 +167,8 @@ function valueLiterals(
     const ch = masked[i] as string;
     if (QUOTES.has(ch)) {
       const end = endOfLiteral(masked, i);
+      // A quote that never closes is one character of code, not an empty literal to report.
+      if (end === i + 1) continue;
       if (depth === 0) found.push({ value: source.slice(i + 1, end - 1), index: i });
       i = end - 1;
     } else if (OPENERS.has(ch)) depth += 1;
@@ -171,170 +184,6 @@ function valueLiterals(
   }));
 }
 
-/** 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 local function that builds an error and takes its fix positionally, and where in its list. */
-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;
-
-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 '';
-}
-
-function fixHelpers(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 params = bracketSpan(masked, open);
-    // 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`.
-    if (params === undefined || params.includes('...')) continue;
-    const parts = topLevelParts(params);
-    if (parts.some((part) => /^\s*[[{]/.test(part))) continue;
-    const index = parts.findIndex((part) => FIX_PARAM.test(part));
-    if (index === -1) continue;
-    if (!BUILDS_ERROR.test(bodyOf(masked, open + params.length + 2))) continue;
-    helpers.push({ name, index });
-  }
-  return helpers;
-}
-
-/**
- * The argument in that position at every call to that helper IN THIS FILE.
- *
- * Same file, deliberately: resolving `dbNotImplemented` imported from `@ultimat3/db` would mean a
- * cross-file symbol table, and a scanner that guessed at which import a name came from would read
- * an unrelated function's argument as a fix. The gap that leaves is named in `CLAUDE.md`.
- */
-function helperFixSites(
-  masked: string,
-  source: string,
-  at: string,
-  helper: FixHelper,
-  lineAt: (index: number) => 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];
-    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)) continue;
-    const literal = argument.indexOf(quote);
-    if (argument.slice(endOfLiteral(argument, literal)).trim() !== '') 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 });
-  }
-  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.
- *
- * Two 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.
- */
-export function scanFixes(source: string, at: string): readonly FixSite[] {
-  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 });
-    }
-  }
-  for (const helper of fixHelpers(masked)) {
-    sites.push(...helperFixSites(masked, source, at, helper, lineAt));
-  }
-  return sites;
-}
-
 const CODE_TABLE = /\bexport const [A-Z][A-Z0-9_]*_ERROR_(?:CODES|TITLES)\b/;
 
 /**

package/src/tsconfig-references.ts

@@ -9,6 +9,7 @@
 import { join } from 'node:path';
 import { docsFor } from './error-codes';
 import type { Finding } from './output';
+import { maskLiterals, stripComments } from './ts-scan';
 
 const ROOT_TSCONFIG = 'tsconfig.json';
 
@@ -22,15 +23,39 @@ const ROOT_TSCONFIG = 'tsconfig.json';
 export const normalizeReferencePath = (path: string): string =>
   path.replace(/^\.\//, '').replace(/\/+$/, '');
 
+/**
+ * A tsconfig is JSONC and `JSON.parse` is not, so the comments and trailing commas `tsc` accepts —
+ * and `tsc --init` writes — are removed before the parse. `Bun.file().json()` rejects both, and
+ * the rejection was mapped to "this root does not use project references": the check went dark on
+ * exactly the roots most likely to have been written by hand, while `typecheck` stayed green over
+ * every package it then skipped. `stripComments` is `ts-scan.ts`'s, so a `//` inside a string is a
+ * URL and not a comment; the trailing-comma pass reads MASKED text for the same reason.
+ */
+function parseJsonc(text: string): unknown {
+  const uncommented = stripComments(text);
+  const masked = maskLiterals(uncommented);
+  const chars = [...uncommented];
+  for (let i = 0; i < masked.length; i += 1) {
+    if (masked[i] !== ',') continue;
+    let next = i + 1;
+    while (next < masked.length && /\s/.test(masked[next] as string)) next += 1;
+    if (masked[next] === '}' || masked[next] === ']') chars[i] = ' ';
+  }
+  return JSON.parse(chars.join('')) as unknown;
+}
+
 /**
  * `undefined` means "this root does not use project references" — a different repo shape, not an
  * empty graph. A scaffolded app is that shape (`extends` + `include`, no references at all), and
  * telling its author to add an entry to a list that does not exist is a fix that makes the build
- * worse. A tsconfig that will not parse is `typecheck`'s to report, with tsc's own message.
+ * worse. A tsconfig that will not parse EVEN AS JSONC is `typecheck`'s to report, with tsc's own
+ * message — this check has no code that would mean "the file is broken" and must not borrow one
+ * that means something else.
  */
 async function referencedPaths(root: string): Promise<ReadonlySet<string> | undefined> {
   const payload: unknown = await Bun.file(join(root, ROOT_TSCONFIG))
-    .json()
+    .text()
+    .then(parseJsonc)
     .catch(() => undefined);
   const references =
     typeof payload === 'object' && payload !== null

package/src/verify-step.ts

@@ -28,6 +28,11 @@ export const VERIFY_STEP_NAMES = [
   'drift',
   'contract-diff',
   'budgets',
+  // Eighteenth, and a deliberate widening of a closed list rather than a `HostCheck`: an SEO gate
+  // is a MECHANISM every app with a `site/` surface wants (axiom 8), not a rule one host repo
+  // enforces — and `verifyCommand.run` passes no host checks at all, so the app path could not
+  // have carried it. It runs beside `budgets` because both read the app the same load produced.
+  'seo',
   'manifest',
   'roadmap',
 ] as const;