@ultimat3/cli 2.0.0 → 3.0.0

package/src/drift.ts

@@ -62,6 +62,41 @@ export async function writeSchemaHash(root: string, migrationId: string): Promis
   return hash;
 }
 
+/**
+ * "Some migration recorded this hash" — the one predicate, read by the check below AND by the
+ * reconcile above it. Two spellings would let `x db gen` report the sidecar written while
+ * `x verify` still reports drift over the same two files.
+ */
+const isRecorded = (records: readonly MigrationRecord[], hash: string): boolean =>
+  records.some((record) => record.hash === hash);
+
+export interface HashReconciliation {
+  readonly hash: string;
+  /** False when a sidecar already held this hash — nothing was written, and nothing needed to be. */
+  readonly written: boolean;
+}
+
+/**
+ * Re-record the sidecar for a migration that is already the right one. `SCHEMA_GLOB` covers every
+ * non-test file under `packages/db/src`, not only the ones that imply DDL, so editing a seed or a
+ * helper moves the hash with no diff behind it — and `X_DB_DRIFT`'s `fix:` has to have somewhere to
+ * land or the instruction is unfollowable. The caller owes the proof that the DDL genuinely did not
+ * move (`db-generate.ts` reaches this only on an empty diff off a fully loaded registry); this
+ * function decides only whether a write is needed.
+ *
+ * A hash an OLDER migration recorded is left alone: `checkSourceDrift` already answers clean on it,
+ * and stamping the newest sidecar would claim that migration produced a schema it did not.
+ */
+export async function reconcileSchemaHash(
+  root: string,
+  migrationId: string,
+): Promise<HashReconciliation> {
+  const hash = await schemaHash(root);
+  if (isRecorded(await recordedHashes(root), hash)) return { hash, written: false };
+  await Bun.write(join(root, MIGRATIONS_DIR, hashFileName(migrationId)), `${hash}\n`);
+  return { hash, written: true };
+}
+
 /**
  * How many entities the app declares. Injected so this module's own tests need no app on disk, and
  * so a caller that has already loaded the app can answer without loading it twice.
@@ -90,6 +125,11 @@ export async function checkSourceDrift(
     // `x db gen "initial"`, which has an empty diff there, writes no `.hash`, and exits ok: a fix
     // that succeeds and changes nothing. Drift resumes the moment the author declares an entity,
     // and by then the fix genuinely writes one.
+    //
+    // An empty diff still writes no `.hash` HERE, and must: `reconcileSchemaHash` needs a migration
+    // id to record against and there is no migration at all in this branch. With an entity declared
+    // the diff is never empty — a registry against zero migrations is `create table` for all of
+    // it — so this branch's fix stays the real generation it always was.
     if ((await declaredEntities()) === 0) return [];
     return [
       {
@@ -101,7 +141,7 @@ export async function checkSourceDrift(
       },
     ];
   }
-  if (records.some((record) => record.hash === current)) return [];
+  if (isRecorded(records, current)) return [];
   return [
     {
       code: 'X_DB_DRIFT',

package/src/error-catalog.ts

@@ -36,6 +36,7 @@ export const CATALOG_PACKAGES = [
   '@ultimat3/realtime',
   '@ultimat3/render',
   '@ultimat3/schema',
+  '@ultimat3/scraping',
   '@ultimat3/seo',
   '@ultimat3/storage',
   '@ultimat3/testing',

package/src/error-codes.ts

@@ -67,6 +67,11 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_DB_MIGRATE_FAILED',
   'X_DB_BRANCH_FAILED',
   'X_DB_STUDIO_FAILED',
+  // Refusing to seed production is a REFUSAL, not a malformed invocation, so it is not
+  // `X_CLI_BAD_FLAG`: the argv was well formed and the answer is no. Its own code is what lets
+  // `x errors explain` hand back the one remedy — name the tier — instead of the flag code's
+  // "unknown flag, missing value, or a value the command refuses", which covers a dozen causes.
+  'X_SEED_ENVIRONMENT',
   // The five app-surface boundary codes. `@ultimat3/render` owns the *rule* (`checkSurfaceBoundary`)
   // and the CLI owns the diagnostic, because `x verify` and `x fix boundary` are the two commands
   // that report it — see `app-boundaries.ts`, which holds the one rule-to-code table.
@@ -165,6 +170,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_DB_MIGRATE_FAILED: 'x db migrate failed',
   X_DB_BRANCH_FAILED: 'an x db branch step failed',
   X_DB_STUDIO_FAILED: 'x db studio failed',
+  X_SEED_ENVIRONMENT: 'the seed tier is not one this environment runs',
   X_BOUNDARY_SITE_TO_APP: 'site/ imported app/',
   X_BOUNDARY_SHARED_LEAF: 'shared/ imported a surface',
   X_BOUNDARY_APP_TO_API: 'app/ imported api/ at runtime',

package/src/exec.ts

@@ -5,7 +5,10 @@
 // `UltimateError` straight from core rather than a class in `./errors`: this module is imported by
 // every command, and `./errors` runs `registerErrorCodes` on import — a subprocess boundary must
 // not decide when the CLI's registry is populated. `X_CLI_UNEXPECTED` is owned there all the same.
-import { UltimateError } from '@ultimat3/core';
+import { renderThrowable, UltimateError } from '@ultimat3/core';
+// `shell-quote.ts` is a leaf — it imports nothing, so the subprocess boundary stays importable
+// from anywhere, this file's header rule about a single boundary included.
+import { quoteArg } from './shell-quote';
 
 export interface ExecResult {
   readonly command: readonly string[];
@@ -27,6 +30,43 @@ export type Runner = (command: readonly string[], options: ExecOptions) => Promi
 /** performance.now(), not Date.now(): the test preload freezes the wall clock on purpose. */
 const now = (): number => performance.now();
 
+/**
+ * The failure mode this file's header already promised was identical everywhere, and the one it
+ * never coded. `x deploy` on a machine without `docker` threw Bun's own `Error: Executable not
+ * found in $PATH`; `dispatch.ts` rendered it as `X_CLI_UNEXPECTED` with `fix: x doctor --json`,
+ * and `runDoctor` checks nothing about an absent binary — an instruction that cannot close the
+ * error is axiom 4 inverted. The code stays `X_CLI_UNEXPECTED` (the CLI already owns it for a
+ * failure of its own machinery); what changes is that the fix names the program to install.
+ *
+ * The program name goes through `quoteArg` at BOTH references: `docker compose` or any name a
+ * shell would resplit produced a `fix:` that runs something else, which is axiom 4 inverted twice
+ * in one line.
+ *
+ * The thrown value goes through core's render helper and is never interpolated: an `unknown`
+ * reaching a `cause:` through `${…}` is what `bun run error-render` refuses, and this one is
+ * genuinely unknown — Bun raises `ENOENT` for a missing program, `EACCES` for an unrunnable one.
+ *
+ * The return type is inferred so this stays one statement of `Bun.spawn`'s own shape.
+ */
+function spawnOrRefuse(command: readonly string[], options: ExecOptions) {
+  const [head = '', ...rest] = command;
+  try {
+    return Bun.spawn([head, ...rest], {
+      cwd: options.cwd,
+      env: options.env === undefined ? Bun.env : { ...Bun.env, ...options.env },
+      stdin: options.stdin === undefined ? 'ignore' : new TextEncoder().encode(options.stdin),
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+  } catch (error) {
+    throw new UltimateError({
+      code: 'X_CLI_UNEXPECTED',
+      cause: `the CLI could not run "${head}" from ${options.cwd}: ${renderThrowable(error)}`,
+      fix: `install ${quoteArg(head)} and put it on PATH, then re-run — confirm with: command -v ${quoteArg(head)}`,
+    });
+  }
+}
+
 export const exec: Runner = async (command, options) => {
   const started = now();
   const [head, ...rest] = command;
@@ -40,13 +80,7 @@ export const exec: Runner = async (command, options) => {
       fix: 'pass the program as the first element: exec(["bun", "test"], { cwd })',
     });
   }
-  const proc = Bun.spawn([head, ...rest], {
-    cwd: options.cwd,
-    env: options.env === undefined ? Bun.env : { ...Bun.env, ...options.env },
-    stdin: options.stdin === undefined ? 'ignore' : new TextEncoder().encode(options.stdin),
-    stdout: 'pipe',
-    stderr: 'pipe',
-  });
+  const proc = spawnOrRefuse([head, ...rest], options);
   const [stdout, stderr, code] = await Promise.all([
     new Response(proc.stdout).text(),
     new Response(proc.stderr).text(),

package/src/flag-number.ts

@@ -54,3 +54,14 @@ export const intFlagOr = (args: ParsedArgs, flag: IntFlag, fallback: number): nu
  * free port. Two ranges for one concept is the drift this constant exists to prevent.
  */
 export const PORT_RANGE = { min: 0, max: 65_535 } as const;
+
+/**
+ * A free-port suggestion the thing being fixed will actually accept. `port + 1` at the top of the
+ * range names 65536, which is not a port — so a `fix:` built that way reproduces a failure instead
+ * of ending one: `x doctor` emitted `x dev --port 65536`, which `x dev` refuses with
+ * `X_CLI_BAD_FLAG`. The neighbour below is a port; the one above does not exist. Here rather than
+ * beside either caller, because two ports-are-bounded rules is the drift `PORT_RANGE` above
+ * already exists to prevent.
+ */
+export const neighbouringPort = (port: number): number =>
+  port < PORT_RANGE.max ? port + 1 : PORT_RANGE.max - 1;

package/src/index.ts

@@ -75,7 +75,7 @@ export {
   pgliteBranchName,
   previewUrl,
 } from './db-branch';
-export type { GeneratedFiles, GenerateMigrationOptions } from './db-generate';
+export type { GeneratedFiles, GenerateMigrationOptions, GenerateOutcome } from './db-generate';
 export { generateAppMigration, migrationSql } from './db-generate';
 export type { AssetRoutesOptions } from './dev-assets';
 export {
@@ -99,8 +99,14 @@ export type { DevServices, ServiceBinding } from './dev-services';
 export { describeServices, resolveServices } from './dev-services';
 export type { DispatchOptions } from './dispatch';
 export { dispatch } from './dispatch';
-export type { DeclaredEntityCount } from './drift';
-export { checkSourceDrift, recordedHashes, schemaHash, writeSchemaHash } from './drift';
+export type { DeclaredEntityCount, HashReconciliation } from './drift';
+export {
+  checkSourceDrift,
+  reconcileSchemaHash,
+  recordedHashes,
+  schemaHash,
+  writeSchemaHash,
+} from './drift';
 export type { ErrorCatalog } from './error-catalog';
 export {
   buildErrorCatalog,
@@ -213,6 +219,7 @@ export {
   runRole,
   serveApp,
 } from './serve';
+export { quoteArg } from './shell-quote';
 export {
   eachSourceFile,
   isGenerated,
@@ -225,7 +232,7 @@ export { countsOf } from './test-counts';
 export type { TestFile } from './test-select';
 export { belongsToType, discoverTests, sampleFiles } from './test-select';
 export type { ReproduceOptions, RunShardsOptions, Shard } from './test-shards';
-export { planShards, quoteArg, reproduceFor, runShards, shardArgs } 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 {

package/src/mcp-errors.ts

@@ -93,6 +93,14 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_DB_MIGRATE_FAILED: 'x doctor --json   # cause carries the Postgres error verbatim',
   X_DB_BRANCH_FAILED: 'x db branch ls --json',
   X_DB_STUDIO_FAILED: 'x doctor --json',
+  // Runnable first, the narrowing behind a `#`, exactly as X_CLI_UNKNOWN_COMMAND above: naming
+  // the tier IS the consent, and which seed to consent to is the one thing this table cannot
+  // know — a bare `x db seed --tier dev` would seed every dev fixture in production to answer a
+  // refusal about one. The dry run is what lists them, and the raised error's own `fix:` already
+  // carries the fully named invocation. `ULTIMATE_SEED_TIER=<tier>` is the other half of the
+  // consent and stays in the cause: it is the answer only for a container with a fixed argv.
+  X_SEED_ENVIRONMENT:
+    'x db seed --dry-run --json   # then name the tier: x db seed <name> --tier dev --json',
   X_BOUNDARY_SITE_TO_APP:
     'x verify --json   # then: x fix boundary <the file the finding names> --json',
   X_BOUNDARY_SHARED_LEAF:

package/src/messages.ts

@@ -46,10 +46,22 @@ const CATALOG = {
   'cli.db.branch.unknown': '-',
   'cli.db.gen.failed': 'migration not generated',
   'cli.db.gen.unchanged': 'entities and migrations agree — nothing to generate',
+  // A THIRD outcome, and it is neither of the other two: nothing to generate, but the sidecar the
+  // `drift` step reads did move — an edit under `packages/db/src` that implies no DDL. Rendering it
+  // as `written` would name a migration nobody can apply; as `unchanged`, it would hide a file this
+  // command wrote. `GeneratedFiles.outcome` is what `--json` carries the same distinction on.
+  'cli.db.gen.recorded': 'no migration needed — schema hash re-recorded in {file}',
   'cli.db.gen.written': 'migration {id} generated',
   'cli.db.migrate.applied': 'migrations applied',
   'cli.db.migrate.failed': 'migration failed',
   'cli.db.reset.done': 'database reset and migrated',
+  // Every seed counted per outcome, exactly as the backfill summary is: a replayed seed writes
+  // nothing and skips everything, and a total that hid that would make the second run look idle.
+  'cli.db.seed.done':
+    '{count} seed(s): {inserted} inserted, {updated} updated, {skipped} already stored',
+  'cli.db.seed.dryRun': '{count} seed(s) would run — nothing written while --dry-run is set',
+  'cli.db.seed.failed': '{failed} of {count} seed(s) failed',
+  'cli.db.seed.none': 'no seed matched — nothing to run',
   'cli.dev.ready': 'dev ready on {url} — /_x mounted ({panels} panels), {services}',
   // The mail and CDN halves of that boot line. Rendered text, so it lives here — while
   // `describeMail`/`describeCdn` keep the same wording as the fixed vocabulary `x dev --json`

package/src/metrics-endpoint.ts

@@ -8,7 +8,11 @@ import {
   METRICS_PATH,
   markListening,
   metricsText,
+  stringField,
+  UltimateError,
 } from '@ultimat3/core';
+import { docsFor } from './error-codes';
+import { neighbouringPort } from './flag-number';
 
 /**
  * A port of its own, and NOT the role's HTTP port, for one reason the chart makes concrete:
@@ -25,6 +29,37 @@ import {
  */
 export const DEFAULT_METRICS_PORT = 9090;
 
+/**
+ * `X_PORT_IN_USE` is the code the CLI already registers for "this dev port is taken", and the
+ * scrape port is one — a synonym here would be a second code for one condition. The fix moves the
+ * port rather than naming a process to kill, because `METRICS_PORT` is the one knob both `x dev`
+ * and the container read (`serve.ts`'s `metricsPortFromEnv`).
+ *
+ * The port it names comes from `neighbouringPort`, never `port + 1`: at the top of the range
+ * that is 65536, and an instruction that cannot run is the failure this code exists to end.
+ */
+export class MetricsPortInUseError extends UltimateError {
+  constructor(input: { port: number }) {
+    super({
+      code: 'X_PORT_IN_USE',
+      cause: `the metrics port ${input.port} is already bound, so no role could open its scrape listener`,
+      fix: `METRICS_PORT=${neighbouringPort(input.port)} x dev --json`,
+      docs: docsFor('X_PORT_IN_USE'),
+    });
+  }
+}
+
+/**
+ * Bun surfaces the bind failure as an `Error` carrying the libc code; nothing else is ours. Read
+ * through `stringField`, never `error instanceof Error` plus a property access: both run on a value
+ * this process did not build, and either can throw one line before the guard that was meant to make
+ * the path safe. Exported because whether the kernel refuses a second bind is the OS's business,
+ * not this package's — the contract worth pinning is that an EADDRINUSE-shaped throw becomes a
+ * coded refusal, and that is testable without racing a socket.
+ */
+export const isAddressInUse = (error: unknown): boolean =>
+  stringField(error, 'code') === 'EADDRINUSE';
+
 export interface MetricsEndpointOptions {
   /** 0 asks the kernel for an ephemeral port, which is what a test wants. */
   readonly port?: number;
@@ -45,20 +80,32 @@ export interface MetricsEndpoint {
  * signal at the moment of load is worse than no autoscaler.
  */
 export function startMetricsEndpoint(options: MetricsEndpointOptions = {}): MetricsEndpoint {
-  const server = Bun.serve({
-    port: options.port ?? DEFAULT_METRICS_PORT,
-    hostname: options.hostname ?? 'localhost',
-    fetch(request: Request): Response {
-      if (new URL(request.url).pathname !== METRICS_PATH) {
-        return new Response('not found', { status: 404 });
-      }
-      // `collectMetrics()` is cumulative and never reset by a read, so two scrapers cannot steal
-      // each other's samples — but a cache would hand the second one a stale window.
-      return new Response(metricsText(), {
-        headers: { 'content-type': METRICS_CONTENT_TYPE, 'cache-control': 'no-store' },
+  const port = options.port ?? DEFAULT_METRICS_PORT;
+  // `startRoles` opens this FIRST, before any role, so `Bun.serve`'s own bare `Error` was what a
+  // second `x dev` on one machine reported: no code, no fix, at the boot path this package owns.
+  // The return type is inferred, keeping `Bun.serve`'s own shape stated once.
+  function listen() {
+    try {
+      return Bun.serve({
+        port,
+        hostname: options.hostname ?? 'localhost',
+        fetch(request: Request): Response {
+          if (new URL(request.url).pathname !== METRICS_PATH) {
+            return new Response('not found', { status: 404 });
+          }
+          // `collectMetrics()` is cumulative and never reset by a read, so two scrapers cannot
+          // steal each other's samples — but a cache would hand the second one a stale window.
+          return new Response(metricsText(), {
+            headers: { 'content-type': METRICS_CONTENT_TYPE, 'cache-control': 'no-store' },
+          });
+        },
       });
-    },
-  });
+    } catch (error) {
+      if (!isAddressInUse(error)) throw error;
+      throw new MetricsPortInUseError({ port });
+    }
+  }
+  const server = listen();
   // Same rule as every other socket the framework opens: announce it, so a request back to it is
   // recognisably this process calling itself rather than egress the test seal must refuse.
   const stopListening = markListening(server.url.origin);

package/src/serve.ts

@@ -86,6 +86,20 @@ export function metricsPortFromEnv(env: Env): number {
   return portValue(env, 'METRICS_PORT', DEFAULT_METRICS_PORT);
 }
 
+/**
+ * The scrape port a boot uses, given the app port it already resolved. One expression, and it is
+ * exported because `x dev` is the second caller: `cmd-dev.ts` passed no `metricsPort` at all, so
+ * `METRICS_PORT` was honoured in the container and ignored on a laptop — the dev/prod parity break
+ * `dev-roles.ts`'s own header forbids, and a second copy of this rule would be the same break
+ * one edit later.
+ *
+ * An in-process caller asking for an ephemeral app port is a test, and a test that grabbed the
+ * fixed 9090 would fail the next suite to boot beside it. An environment that names the port still
+ * wins — that is the deploy talking.
+ */
+export const metricsPortFor = (env: Env, port: number, override?: number): number =>
+  override ?? (port === 0 && env['METRICS_PORT'] === undefined ? 0 : metricsPortFromEnv(env));
+
 /**
  * The one env var that turns error monitoring on, and the only vendor-shaped name in the boot
  * path. Not a platform primitive (axiom 7): the value is a URL to whatever the operator runs, the
@@ -302,9 +316,7 @@ async function bootRoles(boot: {
   // An in-process caller asking for an ephemeral app port is a test, and a test that grabbed the
   // fixed 9090 would fail the next suite to boot beside it. An environment that names the port
   // still wins — that is the deploy talking.
-  const metricsPort =
-    options.metricsPort ??
-    (port === 0 && options.env['METRICS_PORT'] === undefined ? 0 : metricsPortFromEnv(options.env));
+  const metricsPort = metricsPortFor(options.env, port, options.metricsPort);
   const running = await startRoles({
     roles: [role],
     port,

package/src/shell-quote.ts

@@ -0,0 +1,15 @@
+// POSIX single-quoting for a value the CLI pastes into a line a reader runs — a `fix:`, a
+// reproduce command. Its own module, and not `test-shards.ts` where it started, because the
+// subprocess boundary needs it too and `test-shards.ts` imports `exec.ts`: one leaf both can
+// reach is the alternative to an import cycle or a second quoter.
+
+const SHELL_SAFE = /^[\w@%+=:,./-]+$/;
+
+/**
+ * A program name, a `--filter` or a path holding a space, a `$` or a `;` pastes back as two
+ * arguments or as a second command, so an unquoted line runs something other than what it claims.
+ * `'\''` is the only escape a single-quoted string has. A shell-safe value is left alone, so the
+ * common case stays readable.
+ */
+export const quoteArg = (value: string): string =>
+  SHELL_SAFE.test(value) ? value : `'${value.split("'").join("'\\''")}'`;

package/src/test-shards.ts

@@ -8,6 +8,7 @@ import type { Runner } from './exec';
 import { execOutput } from './exec';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue, StepResult } from './output';
+import { quoteArg } from './shell-quote';
 import type { TestFile } from './test-select';
 import { bySizeThenPath } from './test-select';
 import type { TestType } from './verify-tests';
@@ -64,16 +65,6 @@ export const shardArgs = (shard: Shard): readonly string[] => [
   ...shard.files,
 ];
 
-const SHELL_SAFE = /^[\w@%+=:,./-]+$/;
-
-/**
- * POSIX single-quoting for the values a caller supplies. A `--filter` holding a space, a `$` or a
- * `;` pastes back as two arguments or as a second command, so an unquoted line would run something
- * other than the run it claims to reproduce. `'\''` is the only escape a single-quoted string has.
- */
-export const quoteArg = (value: string): string =>
-  SHELL_SAFE.test(value) ? value : `'${value.split("'").join("'\\''")}'`;
-
 export interface ReproduceOptions {
   /** The *effective* worker count: `planShards` clamps to the file count, and the split follows. */
   readonly workers: number;

package/src/test-workers.ts

@@ -43,5 +43,8 @@ export const WORKER_CEILING = 8;
 /** Oversubscription factor. See the table above — it is measured, not chosen for roundness. */
 export const WORKER_OVERSUBSCRIBE = 1.5;
 
+/** The floor the paragraph above names: a 1-core box shards rather than reverting to serial. */
+export const WORKER_FLOOR = 2;
+
 export const defaultWorkers = (available: number = availableCpus()): number =>
-  Math.max(2, Math.min(WORKER_CEILING, Math.round(available * WORKER_OVERSUBSCRIBE)));
+  Math.max(WORKER_FLOOR, Math.min(WORKER_CEILING, Math.round(available * WORKER_OVERSUBSCRIBE)));

package/src/ts-scan.ts

@@ -28,14 +28,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. */
+/**
+ * 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.
+ */
 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;
 }
 
 /**
@@ -156,6 +165,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;

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