@ultimat3/cli 11.0.0 → 11.2.0

package/src/reexport-manifest.ts

@@ -0,0 +1,62 @@
+// Whether a file is a pure re-export manifest — every statement in it an `import` or an `export`
+// that declares nothing. The line ceiling is a rule about REVIEWABLE LOGIC, and such a file has
+// none: its length is a function of the package's API size, so the ceiling measures the wrong
+// thing there. One added statement of logic disqualifies it and re-arms the ceiling on the spot.
+
+import { CLOSERS, maskLiterals, OPENERS } from './ts-scan';
+
+/** Every statement a manifest may hold begins with one of these two words. */
+const IMPORT_OR_EXPORT = /^(?:import|export)\b/;
+
+/**
+ * An `export` that DECLARES rather than re-exports. `export const LIMIT = 1` is a value with an
+ * initialiser, `export function` is logic outright, and both are exactly what the ceiling is for —
+ * so a file holding one is an ordinary source file that happens to start with re-exports.
+ */
+const DECLARES =
+  /^export\s+(?:default|declare|abstract|async|const|let|var|function|class|enum|namespace|module|interface)\b/;
+
+/**
+ * `export type { Ctx } from './ctx'` is a re-export; `export type Ctx = { … }` is a type alias, and
+ * an alias is a declaration a reviewer reads. The brace is the whole distinction.
+ */
+const TYPE_ALIAS = /^export\s+type\s+[A-Za-z_$]/;
+
+/**
+ * Top-level statements, split at the `;` that ends each one at bracket depth 0, over MASKED source
+ * — comments and string contents blanked — so a `;` inside a specifier or a comment is not read as
+ * a boundary. `undefined` when the file ends in something this cannot read as a statement: a scan
+ * that guesses would exempt a file on the strength of not understanding it.
+ */
+function topLevelStatements(masked: string): readonly string[] | undefined {
+  const statements: string[] = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < masked.length; i += 1) {
+    const ch = masked[i] as string;
+    if (OPENERS.has(ch)) depth += 1;
+    // Clamped, because an unbalanced closer would otherwise put every later `;` at a negative
+    // depth and the whole file would read as one unterminated statement.
+    else if (CLOSERS.has(ch)) depth = Math.max(0, depth - 1);
+    else if (ch === ';' && depth === 0) {
+      statements.push(masked.slice(start, i));
+      start = i + 1;
+    }
+  }
+  return masked.slice(start).trim() === '' ? statements : undefined;
+}
+
+/**
+ * True when every statement in `source` is an import or a declaration-free export. A file with no
+ * statement at all is NOT a manifest: an exemption has to be earned by what a file holds, and
+ * "this scan found nothing" is the one answer that must never grant one.
+ */
+export function isReExportManifest(source: string): boolean {
+  const statements = topLevelStatements(maskLiterals(source));
+  if (statements === undefined || statements.length === 0) return false;
+  return statements.every((statement) => {
+    const text = statement.trim();
+    if (text === '') return true;
+    return IMPORT_OR_EXPORT.test(text) && !DECLARES.test(text) && !TYPE_ALIAS.test(text);
+  });
+}

package/src/shot-server.ts

@@ -0,0 +1,90 @@
+// The server a shot is taken against, and the hosts the page may reach while it is: the two
+// facts a ROUTE capture and a COMPONENT capture share, and the only ones. Its own file so
+// `island-shot.ts` can have them without importing the command that photographs a route, which
+// would be a cycle between two files that otherwise have nothing to say to each other.
+
+// why: no Bun native joins a path; `.x/shot` is a path both capture paths write under.
+import { join } from 'node:path';
+import { startDev } from './cmd-dev';
+import { clearLock, isProcessAlive, lockPath, parseLock, preflight, writeLock } from './dev-lock';
+import { DEV_BINDING } from './dev-roles';
+import { resolveServices } from './dev-services';
+
+export const SHOT_DIR = join('.x', 'shot');
+
+/**
+ * How `devServerFor` starts a scratch server. A parameter with a default rather than a direct
+ * call, for the reason every `Runner` in this package is one: the failure path below — a boot that
+ * throws, and the lock it has to hand back — is otherwise only reachable by breaking a real app.
+ */
+export type BootDevServer = (input: {
+  readonly root: string;
+  readonly port: number;
+  readonly env: Readonly<Record<string, string | undefined>>;
+}) => Promise<{ readonly url: string; stop(): Promise<void> }>;
+
+export interface ShotServer {
+  readonly url: string;
+  /** Which server the picture is of. Reported, because the two have different failure modes. */
+  readonly origin: 'booted' | 'reused';
+  stop(): Promise<void>;
+}
+
+/**
+ * One rule, two branches: photograph the `x dev` this checkout already has, or boot a scratch one.
+ * Reusing is not a convenience — embedded Postgres is a single-writer directory, so a second boot
+ * on one checkout is `X_DEV_ALREADY_RUNNING` and the picture would never be taken at all.
+ */
+export async function devServerFor(
+  root: string,
+  env: Readonly<Record<string, string | undefined>>,
+  port: number,
+  boot: BootDevServer = (input) => startDev(input),
+): Promise<ShotServer> {
+  const services = resolveServices(root, env);
+  const file = Bun.file(lockPath(services.stateDir));
+  if (await file.exists()) {
+    const lock = parseLock(await file.text());
+    if (lock !== null && isProcessAlive(lock.pid)) {
+      return { url: lock.url, origin: 'reused', stop: () => Promise.resolve() };
+    }
+  }
+  const { release } = await preflight({
+    stateDir: services.stateDir,
+    port,
+    hostname: DEV_BINDING.hostname,
+    embeddedDb: services.db.mode === 'embedded',
+  });
+  // The directory is CLAIMED from here down — `preflight` returns holding it, never having merely
+  // looked — so a boot that throws has to give it back. `cmd-dev.ts` states the same rule at the
+  // same seam. Without it one failed `x shot` refused every later `x dev` and `x shot` on this
+  // checkout, naming a pid that had already exited. The original error is re-thrown untouched: a
+  // teardown must never replace the failure it is cleaning up after.
+  const dev = await boot({ root, port, env }).catch((error: unknown) => {
+    release();
+    throw error;
+  });
+  await writeLock(services.stateDir, {
+    pid: process.pid,
+    port,
+    url: dev.url,
+    startedAt: new Date().toISOString(),
+  });
+  return {
+    url: dev.url,
+    origin: 'booted',
+    async stop() {
+      clearLock(services.stateDir);
+      await dev.stop();
+    },
+  };
+}
+
+/** `--allow-hosts a.com,b.com` on top of the app's own host. Empty means the app's host alone. */
+export const allowHostsFrom = (url: string, extra: string | undefined): readonly string[] => {
+  const named = (extra ?? '')
+    .split(',')
+    .map((host) => host.trim())
+    .filter((host) => host.length > 0);
+  return [new URL(url).hostname, ...named];
+};

package/src/shot-settle.ts

@@ -1,7 +1,8 @@
-// When a shot may be TAKEN: the two rules that decide whether the page has finished hydrating,
-// separated from both the command that drives a browser and the verdict that judges what came
-// back. Plain values and an injected sleep, so the whole loop is proved with neither.
+// When a shot may be TAKEN: the rules that decide whether the page has finished, separated from
+// both the command that drives a browser and the verdict that judges what came back. Plain values
+// and an injected sleep, so every loop here is proved with neither.
 
+import type { IslandReadiness } from './island-verdict';
 import type { IslandCount } from './shot-verdict';
 
 /**
@@ -55,3 +56,32 @@ export async function settleIslands(
   }
   return answer;
 }
+
+/**
+ * Read the harness's readiness until the page goes QUIET or the window runs out.
+ *
+ * Quiet and not idle, which is the whole rule: the page's own watcher sets `ready` after N
+ * consecutive frames in which no request started and none settled, so a state whose fixture is
+ * deliberately `pending` still reaches it. Waiting for nothing in flight would hang on exactly the
+ * state an author declared on purpose, and a fixed sleep would photograph whatever a slow machine
+ * had painted by then.
+ *
+ * A `null` answer never overwrites a real one, for `settleIslands`' reason: `null` is "the page
+ * answered no probe", and a probe that fails once must not turn a ready page into an unready one.
+ */
+export async function settleReadiness(
+  probe: () => Promise<IslandReadiness | null>,
+  options: SettleOptions,
+): Promise<IslandReadiness | null> {
+  const sleep = options.sleep ?? ((ms: number): Promise<void> => Bun.sleep(ms));
+  let answer = await probe();
+  let waited = 0;
+  while (answer?.ready !== true && waited < options.windowMs) {
+    // At least 1ms, or a `pollMs` of zero is a loop with no exit while the window stands.
+    const step = Math.max(1, Math.min(options.pollMs, options.windowMs - waited));
+    await sleep(step);
+    waited += step;
+    answer = (await probe()) ?? answer;
+  }
+  return answer;
+}

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(['(', '[', '{']);
@@ -150,10 +161,18 @@ export function lineIndex(text: string): (index: number) => number {
 }
 
 /**
- * Every string literal in the value expression starting at `from`, at the expression's own bracket
- * depth. Spanning the expression is what makes `cond ? 'a' : 'b'` and `table[k] ?? 'c'` checkable
- * 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.
+ * Every string literal the value expression starting at `from` can EVALUATE TO, at the
+ * expression's own bracket depth. Spanning the expression is what makes `cond ? 'a' : 'b'` and
+ * `table[k] ?? 'c'` checkable 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.
+ *
+ * A ternary's CONDITION is dropped, which is the difference between reading the expression and
+ * reading every literal in it. `fix: input.slug === '' ? 'x g …' : 'x g …'` published the empty
+ * string as a fix line — `X_ERROR_FIX_INVALID`, "the fix line is empty", against source whose two
+ * real fixes are both correct — and `input.key === 'timeZone' ? … : …` published `timeZone`, a
+ * string then judged for banned phrases and cited paths that is not a fix at all. Costly enough
+ * that `@ultimat3/testing`'s island-state errors carry two classes under one code rather than one
+ * class with a ternary in it.
  */
 export function valueLiterals(
   masked: string,
@@ -162,21 +181,42 @@ export function valueLiterals(
   lineAt: (index: number) => number,
 ): readonly FixSite[] {
   const found: { value: string; index: number }[] = [];
+  // The literals of the segment being read. A segment ended by `?` is a condition and is dropped
+  // whole; one ended by `:` or by the end of the expression is a value the fix can evaluate to.
+  let segment: { value: string; index: number }[] = [];
+  const keep = (): void => {
+    found.push(...segment);
+    segment = [];
+  };
   let depth = 0;
+  /** Open `?`s still waiting for their `:`, so a `:` outside a ternary stays an ordinary char. */
+  let conditionals = 0;
   for (let i = from; i < masked.length; i += 1) {
     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 });
+      if (depth === 0) segment.push({ value: source.slice(i + 1, end - 1), index: i });
       i = end - 1;
     } else if (OPENERS.has(ch)) depth += 1;
     else if (CLOSERS.has(ch)) {
       if (depth === 0) break;
       depth -= 1;
+    } else if (depth === 0 && ch === '?') {
+      // `??` and `?.` are operators and end no segment: `input?.fix ?? 'x help'` evaluates to the
+      // literal, and dropping what came before it would drop the only answer the expression has.
+      if (masked[i + 1] === '?') i += 1;
+      else if (masked[i + 1] !== '.') {
+        segment = [];
+        conditionals += 1;
+      }
+    } else if (depth === 0 && ch === ':' && conditionals > 0) {
+      keep();
+      conditionals -= 1;
     } else if (depth === 0 && (ch === ',' || ch === ';')) break;
   }
+  keep();
   return found.map((literal) => ({
     at: '',
     line: lineAt(literal.index),
@@ -202,27 +242,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 +374,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 +389,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 +428,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', {

package/src/workspace-checks.ts

@@ -1,12 +1,20 @@
-// Four shape rules the gate owns: one file, one job (a hard line ceiling), every workspace
-// package shipping the same contract files, every published package's tarball matching what its
-// manifest promises, and every published package being in the root build graph. All report
-// findings — a shape rule that is only written down is not a rule (axiom 3).
+// Four shape rules the gate owns: one file, one job (a hard line ceiling on REVIEWABLE LOGIC),
+// every workspace package shipping the same contract files, every published package's tarball
+// matching what its manifest promises, and every published package being in the root build graph.
+// All report findings — a shape rule that is only written down is not a rule (axiom 3).
+//
+// The ceiling exempts a pure re-export manifest, and only that. Such a file has one job by
+// construction and its length is a function of the package's API size rather than of its
+// complexity: `@ultimat3/core`'s `src/index.ts` reached 514 lines with 513 statements and not one
+// of them logic, so the ceiling had stopped protecting anything and started refusing every new
+// public subject. `isReExportManifest` is the whole carve-out — one statement of logic in such a
+// file re-arms the ceiling on the same save, which is what keeps it from being a hole.
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { ERROR_DOCS_URL, renderCauseValue } from '@ultimat3/core';
 import type { Finding } from './output';
+import { isReExportManifest } from './reexport-manifest';
 import { eachSourceFile, isGenerated } from './source-files';
 import { checkRootReferences } from './tsconfig-references';
 
@@ -30,13 +38,21 @@ export const tooLongFinding = (path: string, lines: number): Finding => ({
 export const countLines = (text: string): number =>
   text === '' ? 0 : text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
 
-/** Files are the unit of review: one file, one job, hard ceiling 500 lines. */
+/**
+ * Files are the unit of review: one file, one job, hard ceiling 500 lines of reviewable logic.
+ *
+ * The source is read before the count is judged rather than after, because the exemption is a
+ * question about CONTENTS: a 3,000-line file of re-exports is one job and a 501-line file with one
+ * statement of logic in it is not, and only reading tells them apart.
+ */
 export async function checkFileSizes(root: string): Promise<readonly Finding[]> {
   const findings: Finding[] = [];
   for await (const path of eachSourceFile(root)) {
     if (isGenerated(path)) continue;
-    const lines = countLines(await Bun.file(join(root, path)).text());
-    if (lines > LINE_CEILING) findings.push(tooLongFinding(path, lines));
+    const source = await Bun.file(join(root, path)).text();
+    const lines = countLines(source);
+    if (lines <= LINE_CEILING || isReExportManifest(source)) continue;
+    findings.push(tooLongFinding(path, lines));
   }
   return findings;
 }