@ultimat3/cli 22.14.0 → 23.0.0

package/src/cmd-secrets.ts

@@ -30,6 +30,7 @@ import {
 } from '@ultimat3/core';
 import { ENV_SCHEMA_EXPORT, loadEnvSchema } from './app-env';
 import { requireAppRoot } from './app-root';
+import { appSecrets, dropRetired, retire, retiredKeyIds } from './cmd-secrets-ring';
 import { secretsSpec } from './cmd-secrets-spec';
 import type { CliCommand, CommandContext } from './command';
 import {
@@ -40,6 +41,7 @@ import {
 } from './errors';
 import { msg } from './messages';
 import type { CommandResult, JsonValue } from './output';
+import { flagString } from './parse';
 import { recoverRotation, rotateMasterKey } from './secrets-rotation';
 import { shredOnSignal } from './signal-shred';
 import { renderTable } from './table';
@@ -244,36 +246,65 @@ async function set(ctx: CommandContext, io: SecretsIo): Promise<CommandResult> {
   };
 }
 
+/**
+ * The closing half of a rotation: one retired key leaves the ring, by id, once nothing sealed
+ * under it is left. No new key is generated and the key file is not touched — the committed file
+ * is resealed under the key already in force.
+ */
+async function drop(session: Session, keyId: string): Promise<CommandResult> {
+  const { root, key } = session;
+  const after = await dropRetired(await readSecretsFile(root, key), keyId);
+  await writeSecretsFile(root, after, key);
+  const retired = await retiredKeyIds(after);
+  return {
+    ok: true,
+    command: 'secrets',
+    summary: msg('cli.secrets.dropped', { path: SECRETS_FILE, kid: keyId, count: retired.length }),
+    data: {
+      path: SECRETS_FILE,
+      keyId: await masterKeyIdOf(key),
+      dropped: keyId,
+      retiredKeyIds: [...retired],
+    },
+  };
+}
+
 /**
  * A new master key over the same values: staged beside the old one, the file sealed with it, then
  * made live (`rotateMasterKey`). Sealed first with the key file written last, a crash between the
  * two left a committed file no key on disk could open.
+ *
+ * The key being replaced joins the ring INSIDE the sealed file (`cmd-secrets-ring.ts`), so a value
+ * `seal()` wrote under it still opens and a deploy is still handed exactly one key.
  */
 async function rotate(ctx: CommandContext): Promise<CommandResult> {
-  const { root, key } = await open(ctx, 'rotate');
-  const values = await readSecretsFile(root, key);
+  const session = await open(ctx, 'rotate');
+  const dropping = flagString(ctx.args, 'drop');
+  if (dropping !== undefined) return drop(session, dropping);
+  const { root, key } = session;
+  const values = retire(await readSecretsFile(root, key), key.hex);
   const previous = await masterKeyIdOf(key);
   // Ignored BEFORE any key file is written, staged one included; the order inside is
   // `secrets-rotation.ts`'s: stage the key, seal, then rename it live.
   await ensureIgnored(root);
   const next = await rotateMasterKey(root, values);
   const keyId = await masterKeyIdOf(next);
+  const count = Object.keys(appSecrets(values)).length;
   return {
     ok: true,
     command: 'secrets',
-    summary: msg('cli.secrets.rotated', {
-      path: SECRETS_FILE,
-      from: previous,
-      to: keyId,
-      count: Object.keys(values).length,
-    }),
-    lines: [msg('cli.secrets.redeploy', { env: SECRETS_KEY_ENV, keyPath: SECRETS_KEY_FILE })],
+    summary: msg('cli.secrets.rotated', { path: SECRETS_FILE, from: previous, to: keyId, count }),
+    lines: [
+      msg('cli.secrets.redeploy', { env: SECRETS_KEY_ENV, keyPath: SECRETS_KEY_FILE }),
+      msg('cli.secrets.retired', { kid: previous }),
+    ],
     data: {
       path: SECRETS_FILE,
       keyPath: SECRETS_KEY_FILE,
       previousKeyId: previous,
       keyId,
-      count: Object.keys(values).length,
+      count,
+      retiredKeyIds: [...(await retiredKeyIds(values))],
     },
   };
 }
@@ -285,9 +316,12 @@ async function rotate(ctx: CommandContext): Promise<CommandResult> {
  */
 async function show(ctx: CommandContext): Promise<CommandResult> {
   const { root, key } = await open(ctx, 'show');
-  const values = await readSecretsFile(root, key);
+  const sealed = await readSecretsFile(root, key);
+  // The ring is the framework's own entry: reported by key id below, never as an app secret that
+  // `envSchema` forgot to declare.
+  const retired = await retiredKeyIds(sealed);
   const schema = await loadEnvSchema(root);
-  const summaries = describeSecrets(values);
+  const summaries = describeSecrets(appSecrets(sealed));
   const keyId = await masterKeyIdOf(key);
   const declared = (name: string): boolean | undefined =>
     schema === undefined ? undefined : schema[name] !== undefined;
@@ -309,6 +343,7 @@ async function show(ctx: CommandContext): Promise<CommandResult> {
       : [
           msg('cli.secrets.undeclared', { count: undeclared.length, names: undeclared.join(', ') }),
         ]),
+    ...(retired.length === 0 ? [] : [msg('cli.secrets.ring', { kids: retired.join(', ') })]),
   ];
   return {
     ok: true,
@@ -322,6 +357,7 @@ async function show(ctx: CommandContext): Promise<CommandResult> {
       path: SECRETS_FILE,
       keySource: key.source,
       keyId,
+      retiredKeyIds: [...retired],
       count: summaries.length,
       secrets: summaries.map((entry) => ({
         name: entry.name,

package/src/cmd-tasks.ts

@@ -1,22 +1,25 @@
 // `x tasks [list|show <name>]` — introspect scheduled cron tasks: cadence, timezone, the jobs
-// each enqueues, and real next-occurrence instants from `@ultimat3/time`'s cron math instead of
-// an agent reading `0 3 * * *` and guessing. CLI wiring only; the pure computation lives in
-// `tasks-facts.ts` — the same split `cmd-jobs.ts` makes against `jobs-report.ts`.
+// each enqueues, the occurrence the scheduler LAST dispatched (off the queue's own record) and
+// real next-occurrence instants from `@ultimat3/time`'s cron math instead of an agent reading
+// `0 3 * * *` and guessing. CLI wiring only; the pure computation lives in `tasks-facts.ts` — the
+// same split `cmd-jobs.ts` makes against `jobs-report.ts`.
 
 import { nearestName, systemClock } from '@ultimat3/core';
-import type { TaskHandle } from '@ultimat3/jobs';
+import type { JobDriver, TaskFire, TaskHandle } from '@ultimat3/jobs';
 import type { CronPhrases } from '@ultimat3/time';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
 import { tasksSpec } from './cmd-tasks-spec';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, DeclarationUnknownError } from './errors';
+import { withJobDriver } from './jobs-driver';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue } from './output';
 import { flagString } from './parse';
 import { renderTable } from './table';
 import {
   findTaskHandle,
+  isoInZone,
   knownTaskNames,
   listTaskFacts,
   parseCountFlag,
@@ -24,7 +27,41 @@ import {
   taskShowFacts,
 } from './tasks-facts';
 
-const HEADER = ['name', 'cron', 'tz', 'catchUp', 'jobs', 'next'] as const;
+const HEADER = ['name', 'cron', 'tz', 'catchUp', 'jobs', 'last', 'next'] as const;
+
+/**
+ * When a task last fired, flat beside `nextMs` / `next`. All three are `null` for a task the
+ * scheduler has never dispatched — a key that is sometimes absent is a question asked two ways.
+ */
+interface LastFire {
+  /** Epoch ms of the occurrence it was scheduled FOR — the instant `last` renders. */
+  readonly lastMs: number | null;
+  readonly last: string | null;
+  /** Epoch ms the scheduler dispatched it, on the queue's clock. Later than `lastMs` by its lag. */
+  readonly lastFiredAtMs: number | null;
+}
+
+const NEVER_FIRED: LastFire = { lastMs: null, last: null, lastFiredAtMs: null };
+
+/**
+ * The last occurrence each task DISPATCHED, by task name — `JobIntrospection.taskFires()`, never
+ * the scheduler's watermark, which arming and skipping move too. A driver with no introspection
+ * answers none, and every task then reads as never fired.
+ */
+async function lastFires(driver: JobDriver): Promise<ReadonlyMap<string, TaskFire>> {
+  const fires = (await driver.introspect?.taskFires()) ?? [];
+  return new Map(fires.map((fire) => [fire.task, fire]));
+}
+
+const lastFireOf = (fires: ReadonlyMap<string, TaskFire>, name: string, tz: string): LastFire => {
+  const fire = fires.get(name);
+  if (fire === undefined) return NEVER_FIRED;
+  return {
+    lastMs: fire.occurrenceMs,
+    last: isoInZone(fire.occurrenceMs, tz),
+    lastFiredAtMs: fire.firedAt,
+  };
+};
 
 /**
  * The vocabulary `describeCron` interpolates. The cron *math* stays in `tasks-facts.ts` — it is
@@ -57,17 +94,25 @@ const detailLines = (payload: Readonly<Record<string, JsonValue>>): readonly str
 
 const jobsCell = (jobs: readonly string[]): string => (jobs.length === 0 ? '-' : jobs.join(','));
 
-const row = (fact: TaskFact): readonly string[] => [
+const row = (fact: TaskFact & LastFire): readonly string[] => [
   fact.name,
   fact.cron,
   fact.tz,
   fact.catchUp,
   jobsCell(fact.jobs),
+  fact.last ?? '-',
   fact.next,
 ];
 
-function runList(nowMs: number, findings: readonly Finding[]): CommandResult {
-  const facts = listTaskFacts(nowMs);
+function runList(
+  nowMs: number,
+  fires: ReadonlyMap<string, TaskFire>,
+  findings: readonly Finding[],
+): CommandResult {
+  const facts = listTaskFacts(nowMs).map((fact) => ({
+    ...fact,
+    ...lastFireOf(fires, fact.name, fact.tz),
+  }));
   return {
     ok: findings.length === 0,
     command: 'tasks',
@@ -101,13 +146,23 @@ function requireHandle(ctx: CommandContext): TaskHandle {
   );
 }
 
-function runShow(ctx: CommandContext, nowMs: number, findings: readonly Finding[]): CommandResult {
-  const handle = requireHandle(ctx);
-  const count = parseCountFlag(flagString(ctx.args, 'count'));
-  const { descriptor, describe, upcoming } = taskShowFacts(handle, nowMs, count, cronPhrases());
+function runShow(
+  shown: { readonly handle: TaskHandle; readonly count: number },
+  nowMs: number,
+  fires: ReadonlyMap<string, TaskFire>,
+  findings: readonly Finding[],
+): CommandResult {
+  const { descriptor, describe, upcoming } = taskShowFacts(
+    shown.handle,
+    nowMs,
+    shown.count,
+    cronPhrases(),
+  );
   const first = upcoming[0];
+  const fired = lastFireOf(fires, descriptor.name, descriptor.tz);
   const lines = [
     ...detailLines(asJson(descriptor)),
+    `  last: ${fired.last ?? '-'}`,
     `  ${describe}`,
     ...upcoming.map((occurrence) => `    ${occurrence.at}`),
   ];
@@ -124,6 +179,7 @@ function runShow(ctx: CommandContext, nowMs: number, findings: readonly Finding[
     findings,
     data: {
       ...asJson(descriptor),
+      ...fired,
       describe,
       upcoming: upcoming.map((occurrence) => asJson(occurrence)),
     },
@@ -136,8 +192,21 @@ export const tasksCommand: CliCommand = {
     const root = requireAppRoot('tasks', ctx.cwd).dir;
     const { findings } = await loadApp(root);
     const nowMs = systemClock.now().getTime();
-    return ctx.args.subcommand === 'show'
-      ? runShow(ctx, nowMs, findings)
-      : runList(nowMs, findings);
+    // Everything argv can get wrong is refused BEFORE the queue is opened: a typo in a task name
+    // must not cost a database boot to be told about.
+    const shown =
+      ctx.args.subcommand === 'show'
+        ? { handle: requireHandle(ctx), count: parseCountFlag(flagString(ctx.args, 'count')) }
+        : undefined;
+    // Nothing to join a fire to: an app that declares no task never pays for a queue.
+    if (shown === undefined && knownTaskNames().length === 0) {
+      return runList(nowMs, new Map(), findings);
+    }
+    return withJobDriver(root, ctx, async (driver) => {
+      const fires = await lastFires(driver);
+      return shown === undefined
+        ? runList(nowMs, fires, findings)
+        : runShow(shown, nowMs, fires, findings);
+    });
   },
 };

package/src/cmd-verify.ts

@@ -23,12 +23,14 @@ import { VERIFY_STEPS } from './verify-checks';
 import { VerifyMergeInputError, VerifyShardInvalidError } from './verify-errors';
 import { readVerifyFloor } from './verify-floor';
 import type { VerifyPart } from './verify-merge';
-import { mergeParts, parsePart } from './verify-merge';
+import { coverageRiders, mergeParts, parsePart } from './verify-merge';
+import { stepStream } from './verify-progress';
 import { runVerify } from './verify-run';
 import type { ShardSpec, Timings } from './verify-shard';
 import { assertShardable, parseShard, readTimings } from './verify-shard';
 import type { VerifyStepName } from './verify-step';
 import { VERIFY_STEP_NAMES } from './verify-step';
+import { writeErrorLine } from './write-line';
 
 // One import path for the gate, unchanged by the split: `index.ts`, `x build` and the MCP host all
 // reach the list and the runner through this module, and a second path to either would be the
@@ -55,6 +57,9 @@ export const verifyCommand: CliCommand = {
       ...(only === undefined ? {} : { only }),
       ...(shard === undefined ? {} : { shard }),
       ...(isolate === undefined ? {} : { isolate }),
+      // `--json` prints one document when the run ends; a line per finished step on stderr is
+      // what a cancelled CI job's log ends on (#589). stdout stays the single document.
+      ...stepStream(ctx.args.json, writeErrorLine),
     });
     return shard === undefined ? result : withShardData(result, shard);
   },
@@ -119,7 +124,10 @@ async function mergeCommand(
     }
     parts.push(parsePart(file, await handle.text()));
   }
-  return mergeParts(parts, await readVerifyFloor(root));
+  const floor = await readVerifyFloor(root);
+  return mergeParts(parts, floor, VERIFY_STEP_NAMES, {
+    riders: await coverageRiders(parts, root, floor),
+  });
 }
 
 /**

package/src/comment-safe.ts

@@ -0,0 +1,16 @@
+// A path read off the repository being scanned, made safe to ride in the `#` comment of a `fix:`
+// line. One definition: every finding that names a scanned file in its fix writes it through this.
+
+/**
+ * Control characters, `\u00xx`-escaped. The path is a value read off the repository being scanned,
+ * and it rides in a `#` comment: a directory holding a NEWLINE ends that comment, so everything
+ * after it is a second command in a line whose whole purpose is to be pasted into a shell.
+ * Escaped rather than deleted, because the comment still has to name the file the reader owns.
+ */
+export const commentSafe = (path: string): string =>
+  [...path]
+    .map((char) => {
+      const code = char.codePointAt(0) ?? 0;
+      return code < 0x20 || code === 0x7f ? `\\u${code.toString(16).padStart(4, '0')}` : char;
+    })
+    .join('');

package/src/coverage-floor.ts

@@ -0,0 +1,334 @@
+// The coverage floor an app states in `x.verify.json`, what the unit suite measured against the
+// app's WHOLE source tree, and the findings where the two disagree. A finding of the `unit` step,
+// never a step of its own: the step list is as stable as an error code.
+
+// why: Bun ships no synchronous existence check and no path-join primitive; the fix a
+// below-floor finding carries depends on whether the test beside the worst file exists.
+import { existsSync } from 'node:fs';
+// why: Bun ships no path-join primitive.
+import { join } from 'node:path';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import type { CoverageMap } from './coverage-lcov';
+import { percent } from './coverage-lcov';
+import { appSourceFiles, hasExecutableCode, readSource, unloadedWeight } from './coverage-source';
+import { msg } from './messages';
+import type { Finding } from './output';
+import { quoteArg } from './shell-quote';
+
+/** The `x.verify.json` key. */
+export const COVERAGE_FIELD = 'coverage';
+
+/**
+ * Lines and functions, the framework's own code and every app's — one bar. **A floor, not the
+ * goal**: coverage measures execution, not validation, and a test added to raise it is proven by
+ * mutation (break the source, watch it go red, restore). A covered branch whose test cannot fail
+ * is worse than an uncovered one.
+ */
+export const COVERAGE_BAR = 95;
+
+/** How far above a floor under the bar the tree may measure before the floor has to rise. */
+export const FLOOR_SLACK = 1.5;
+
+/** How many files a below-floor finding names. */
+export const LOSS_LIMIT = 10;
+
+const FLOOR_FILE = 'x.verify.json';
+
+export interface CoverageExclude {
+  /** Relative to the app root. */
+  readonly glob: string;
+  /** Why a unit test cannot execute it — a browser-only mount, a container entry point. */
+  readonly why: string;
+}
+
+export interface CoverageFloor {
+  readonly lines: number;
+  readonly funcs: number;
+  /** Required while either number is under `COVERAGE_BAR`: what is uncovered, who closes it. */
+  readonly why?: string;
+  readonly exclude: readonly CoverageExclude[];
+}
+
+const isPercent = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 100;
+
+const isText = (value: unknown): value is string =>
+  typeof value === 'string' && value.trim().length > 0;
+
+/**
+ * `coverage` out of `x.verify.json`, or the reasons it is not a floor. A number that is not a
+ * percentage is refused rather than read as zero — `measured < NaN` is false for every reading,
+ * so a typo would stop the floor enforcing and report green. An `exclude` entry with no `why` is
+ * refused too, and DROPPED: it excludes nothing until it says what it is for.
+ */
+export function readCoverageFloor(payload: Record<string, unknown> | undefined): {
+  coverage?: CoverageFloor;
+  problems: readonly string[];
+} {
+  const raw = payload?.[COVERAGE_FIELD];
+  if (raw === undefined) return { problems: [] };
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    return { problems: [`"${COVERAGE_FIELD}" is not an object of { "lines", "funcs" }`] };
+  }
+  const record = raw as Record<string, unknown>;
+  const problems: string[] = [];
+  for (const key of ['lines', 'funcs'] as const) {
+    if (!isPercent(record[key])) {
+      problems.push(
+        `"${COVERAGE_FIELD}.${key}" is ${JSON.stringify(record[key])}, which is not a percentage from 0 to 100`,
+      );
+    }
+  }
+  if (record['why'] !== undefined && !isText(record['why'])) {
+    problems.push(`"${COVERAGE_FIELD}.why" is not a sentence`);
+  }
+  const exclude: CoverageExclude[] = [];
+  const list = record['exclude'];
+  if (list !== undefined && !Array.isArray(list)) {
+    problems.push(`"${COVERAGE_FIELD}.exclude" is not a list of { "glob", "why" }`);
+  }
+  for (const entry of Array.isArray(list) ? (list as unknown[]) : []) {
+    const one =
+      typeof entry === 'object' && entry !== null ? (entry as Record<string, unknown>) : {};
+    if (!isText(one['glob'])) {
+      problems.push(`"${COVERAGE_FIELD}.exclude" holds an entry with no "glob"`);
+    } else if (!isText(one['why'])) {
+      problems.push(
+        `"${COVERAGE_FIELD}.exclude" excludes ${one['glob']} with no "why" — say why a unit test cannot execute it`,
+      );
+    } else exclude.push({ glob: one['glob'], why: one['why'] });
+  }
+  if (!isPercent(record['lines']) || !isPercent(record['funcs'])) return { problems };
+  return {
+    coverage: {
+      lines: record['lines'],
+      funcs: record['funcs'],
+      ...(isText(record['why']) ? { why: record['why'] } : {}),
+      exclude,
+    },
+    problems,
+  };
+}
+
+/** One source file's share of the gap. */
+export interface FileLoss {
+  readonly file: string;
+  /** Lines that could have run and did not. */
+  readonly uncovered: number;
+  readonly lines: number;
+  /** No unit test loaded it at all: it counts at 0%, weighed off its source. */
+  readonly unloaded: boolean;
+}
+
+export interface CoverageMeasure {
+  readonly lines: number;
+  readonly funcs: number;
+  readonly linesHit: number;
+  readonly linesFound: number;
+  readonly funcsHit: number;
+  readonly funcsFound: number;
+  /** Source files counted, loaded or not. */
+  readonly files: number;
+  /** Worst first: most uncovered lines, then by path. */
+  readonly losses: readonly FileLoss[];
+}
+
+/**
+ * The suite's coverage of the app's WHOLE source tree. `coverage` is keyed by path relative to
+ * `root`; a record for anything else — a framework package, `node_modules`, a test — is not the
+ * app's source and is dropped. A source file with executable code and no record counts at 0%.
+ */
+export async function measureCoverage(
+  root: string,
+  coverage: CoverageMap,
+  floor: CoverageFloor | undefined,
+): Promise<CoverageMeasure> {
+  const sources = appSourceFiles(root, floor?.exclude.map((entry) => entry.glob) ?? []);
+  let linesHit = 0;
+  let linesFound = 0;
+  let funcsHit = 0;
+  let funcsFound = 0;
+  let files = 0;
+  const losses: FileLoss[] = [];
+  for (const file of sources) {
+    const loaded = Object.hasOwn(coverage, file) ? coverage[file] : undefined;
+    if (loaded !== undefined) {
+      const found = loaded.hit.length + loaded.miss.length;
+      linesHit += loaded.hit.length;
+      linesFound += found;
+      funcsHit += Math.min(loaded.funcsHit, loaded.funcsFound);
+      funcsFound += loaded.funcsFound;
+      files += 1;
+      if (loaded.miss.length > 0) {
+        losses.push({ file, uncovered: loaded.miss.length, lines: found, unloaded: false });
+      }
+      continue;
+    }
+    const source = await readSource(root, file);
+    // A barrel or a types-only module emits nothing, so Bun writes no record for it when it IS
+    // loaded: absent is correct, and it weighs nothing.
+    if (source === undefined || !hasExecutableCode(source)) continue;
+    const weight = unloadedWeight(source);
+    linesFound += weight.lines;
+    funcsFound += weight.funcs;
+    files += 1;
+    losses.push({ file, uncovered: weight.lines, lines: weight.lines, unloaded: true });
+  }
+  losses.sort((a, b) => b.uncovered - a.uncovered || (a.file < b.file ? -1 : 1));
+  return {
+    lines: percent(linesHit, linesFound),
+    funcs: percent(funcsHit, funcsFound),
+    linesHit,
+    linesFound,
+    funcsHit,
+    funcsFound,
+    files,
+    losses,
+  };
+}
+
+/** One decimal, rounded DOWN: a printed number never claims more than was measured. */
+const shown = (value: number): string => (Math.floor(value * 10) / 10).toFixed(1);
+
+/**
+ * The floor a measured number supports: the bar once it clears it, the whole number under it
+ * below — up to a point of room, so one uncovered line in an unrelated file is not a red gate,
+ * and less than `FLOOR_SLACK`, so the floor it writes is never stale the moment it is written.
+ */
+const floorFor = (measured: number): number =>
+  measured >= COVERAGE_BAR ? COVERAGE_BAR : Math.floor(measured);
+
+const WHY_PLACEHOLDER = '<what is uncovered and who closes it>';
+
+/** The `"coverage": { … }` text for a measured tree — what an author pastes. */
+export function floorLine(measure: Pick<CoverageMeasure, 'lines' | 'funcs'>): string {
+  const lines = floorFor(measure.lines);
+  const funcs = floorFor(measure.funcs);
+  const why = lines < COVERAGE_BAR || funcs < COVERAGE_BAR ? `, "why": "${WHY_PLACEHOLDER}"` : '';
+  return `"${COVERAGE_FIELD}": { "lines": ${String(lines)}, "funcs": ${String(funcs)}${why} }`;
+}
+
+/**
+ * `foo.ts` → `foo.test.ts`, and `page.tsx` → `page.test.ts`: where the test that covers a file
+ * lives. Always `.ts` — every generator writes it so, and a test holds no JSX: the registry leak
+ * guard's loader covers `.test.ts` only, so a `.test.tsx` this named would also be unguarded.
+ */
+export const testPathOf = (file: string): string => file.replace(/\.tsx?$/, '.test.ts');
+
+export interface JudgeOptions {
+  /** Whether `path` (relative to the app root) exists — decides which fix a below-floor gets. */
+  readonly exists: (path: string) => boolean;
+}
+
+/**
+ * The findings a measurement earns against the stated floor — none is the only pass.
+ *
+ * | State | Finding |
+ * |---|---|
+ * | no floor stated | `X_COVERAGE_FLOOR_UNSTATED`, carrying the line to add |
+ * | a floor under the bar with no `why` | `X_COVERAGE_FLOOR_UNSTATED` |
+ * | measured under the floor | `X_COVERAGE_BELOW_FLOOR`, naming the files that lose the most |
+ * | a floor under the bar, and the tree `FLOOR_SLACK` points over it | `X_COVERAGE_FLOOR_STALE` |
+ *
+ * The last row is what makes the floor only rise, and it needs no history to do it: a floor may
+ * sit under the bar only while it is what the tree measures.
+ */
+export function coverageFindings(
+  measure: CoverageMeasure,
+  floor: CoverageFloor | undefined,
+  options: JudgeOptions,
+): readonly Finding[] {
+  const measured = `${shown(measure.lines)}% of lines and ${shown(measure.funcs)}% of functions`;
+  if (floor === undefined) {
+    return [
+      {
+        code: 'X_COVERAGE_FLOOR_UNSTATED',
+        cause: `${FLOOR_FILE} states no coverage floor; the unit suite covers ${measured} of this app's own source (${String(measure.files)} files, one no test loads counted at 0%)`,
+        fix: `edit ${FLOOR_FILE} — add ${floorLine(measure)}`,
+        docs: ERROR_DOCS_URL,
+        at: FLOOR_FILE,
+      },
+    ];
+  }
+  const findings: Finding[] = [];
+  const stated = `${shown(floor.lines)}% / ${shown(floor.funcs)}%`;
+  const underBar = floor.lines < COVERAGE_BAR || floor.funcs < COVERAGE_BAR;
+  if (underBar && floor.why === undefined) {
+    findings.push({
+      code: 'X_COVERAGE_FLOOR_UNSTATED',
+      cause: `${FLOOR_FILE} states a coverage floor of ${stated}, under the ${String(COVERAGE_BAR)}% bar, and no reason for it`,
+      fix: `edit ${FLOOR_FILE} — add "why": "${WHY_PLACEHOLDER}" inside "${COVERAGE_FIELD}", or raise both numbers to ${String(COVERAGE_BAR)}`,
+      docs: ERROR_DOCS_URL,
+      at: FLOOR_FILE,
+    });
+  }
+  if (measure.lines < floor.lines || measure.funcs < floor.funcs) {
+    const worst = measure.losses.slice(0, LOSS_LIMIT);
+    const named = worst
+      .map((loss) =>
+        loss.unloaded
+          ? `${loss.file} (no unit test loads it: ${String(loss.lines)} lines)`
+          : `${loss.file} (${String(loss.uncovered)} of ${String(loss.lines)} lines)`,
+      )
+      .join(', ');
+    const first = worst[0];
+    const test = first === undefined ? undefined : testPathOf(first.file);
+    findings.push({
+      code: 'X_COVERAGE_BELOW_FLOOR',
+      cause: `the unit suite covers ${measured} of this app's own source, under the floor of ${stated} in ${FLOOR_FILE}${named === '' ? '' : ` — losing the most lines: ${named}`}`,
+      fix:
+        test === undefined
+          ? 'x verify --only unit --json'
+          : options.exists(test)
+            ? // Quoted: a route directory is `[id]`, which a shell reads as a glob.
+              `bun test --coverage ${quoteArg(test)}`
+            : `edit ${test} — no test sits beside ${first?.file ?? test}; write one that fails when the source is broken, then: bun test --coverage ${quoteArg(test)}`,
+      docs: ERROR_DOCS_URL,
+      ...(first === undefined ? {} : { at: first.file }),
+    });
+  }
+  const risen = (['lines', 'funcs'] as const).filter(
+    (key) => floor[key] < COVERAGE_BAR && measure[key] >= floor[key] + FLOOR_SLACK,
+  );
+  if (risen.length > 0) {
+    const lines = Math.max(floor.lines, floorFor(measure.lines));
+    const funcs = Math.max(floor.funcs, floorFor(measure.funcs));
+    const cleared = lines >= COVERAGE_BAR && funcs >= COVERAGE_BAR;
+    findings.push({
+      code: 'X_COVERAGE_FLOOR_STALE',
+      cause: `the unit suite now covers ${measured}, more than ${String(FLOOR_SLACK)} points over the floor of ${stated} in ${FLOOR_FILE} — the floor only rises`,
+      fix: `edit ${FLOOR_FILE} — set "lines": ${String(lines)} and "funcs": ${String(funcs)} inside "${COVERAGE_FIELD}"${cleared ? ', and delete its "why"' : ''}`,
+      docs: ERROR_DOCS_URL,
+      at: FLOOR_FILE,
+    });
+  }
+  return findings;
+}
+
+export interface CoverageVerdict {
+  readonly measure: CoverageMeasure;
+  readonly findings: readonly Finding[];
+  /** One line for the step's `output`: the numbers, and the floor they were held to. */
+  readonly output: string;
+}
+
+/** Measure `coverage` against the app at `root` and judge it against `floor` — the whole check. */
+export async function judgeCoverage(
+  root: string,
+  coverage: CoverageMap,
+  floor: CoverageFloor | undefined,
+): Promise<CoverageVerdict> {
+  const measure = await measureCoverage(root, coverage, floor);
+  return {
+    measure,
+    findings: coverageFindings(measure, floor, {
+      exists: (path) => existsSync(join(root, path)),
+    }),
+    output: msg('cli.verify.coverage', {
+      lines: shown(measure.lines),
+      funcs: shown(measure.funcs),
+      files: measure.files,
+      floor: floor === undefined ? 'unstated' : `${shown(floor.lines)}% / ${shown(floor.funcs)}%`,
+    }),
+  };
+}