@ultimat3/cli 1.2.0 → 3.0.0

package/src/cmd-verify.ts

@@ -5,6 +5,7 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { renderThrowable } from '@ultimat3/core';
 import type { Manifest } from '@ultimat3/manifest';
 import {
   AGENTS_MD_FILENAME,
@@ -14,22 +15,39 @@ import {
 } from '@ultimat3/manifest';
 import { checkAgentsMd } from './app-agents-md';
 import { checkAppBoundaries } from './app-boundaries';
+import { envExampleFindings } from './app-env';
 import { appManifest, readAppManifest } from './app-manifest';
 import { OPENAPI_FILE, openApiJson } from './app-openapi';
 import { APP_CONFIG_FILE, requireAppRoot } from './app-root';
 import { checkBudgets, readBuildStats } from './budgets';
 import type { CliCommand, CommandContext } from './command';
-import { checkDrift } from './drift';
+import { checkDestructiveMigrations } from './db-destructive';
+import { checkDocumentStyles, documentSurfaces } from './document-styles';
+import { checkSourceDrift } from './drift';
 import { checkErrorFixes } from './error-contract';
+import { readIntFlag } from './flag-number';
+import { guardFindings } from './guards';
 import { msg } from './messages';
 import type { CommandResult, Finding, StepResult } from './output';
 import { findingFrom } from './output';
+import type { ParsedArgs } from './parse';
+import { WORKER_CEILING, WORKER_FLOOR, WORKER_OVERSUBSCRIBE } from './test-workers';
+import {
+  floorProblemFindings,
+  floorRequires,
+  readVerifyFloor,
+  skippedSuiteFinding,
+  vanishedSuiteFinding,
+} from './verify-floor';
 import type { StepOutcome, VerifyContext, VerifyStep, VerifyStepName } from './verify-step';
-import { fromExec, fromFindings, hostFindings, passed } from './verify-step';
+import { fromExec, fromFindings, hostFindings } from './verify-step';
 import { TEST_STEPS } from './verify-tests';
 import { checkFileSizes, checkPackageShape, hasWorkspacePackages } from './workspace-checks';
 
 /** The whole contract, in cost order. Every check the framework knows how to make lives here. */
+/** The one file that makes the `roadmap` step answerable, and therefore what `applies` reads. */
+const ROADMAP_FILE = join('docs', 'idea', '14-roadmap.md');
+
 export const VERIFY_STEPS: readonly VerifyStep[] = [
   {
     name: 'typecheck',
@@ -47,7 +65,11 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
   },
   {
     name: 'lint',
-    summary: 'biome: no any, no default exports, no raw colours',
+    // Only what biome actually enforces. It claimed "no default exports" while the rule was off
+    // (it is not in `recommended`) and "no raw colours" over a file type biome ignores entirely —
+    // two thirds of the line were enforced by nothing. `noDefaultExport` is now on in `biome.json`;
+    // the colour rule is `packages/ui/src/tokens/tokens.test.ts`, and rides on the `unit` step.
+    summary: 'biome: format, no any, no default exports, no unused imports',
     async run(ctx) {
       const result = await ctx.runner(['bunx', 'biome', 'check', '.'], { cwd: ctx.root });
       return fromExec(result, {
@@ -59,10 +81,21 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
   },
   {
     name: 'boundaries',
-    summary: 'surface, layer and package-tier imports',
+    summary: "surface, layer and package-tier imports, and the app's own guards",
+    // An app's `guards/` rides here rather than becoming an eighteenth step, for the reason the
+    // seam already states: a host adds findings to a step, it can never add, remove, reorder or
+    // skip one — so "green" keeps meaning exactly what it meant. This is the step whose host slot
+    // already carries "rules this repo makes about itself that the framework cannot know" (the
+    // monorepo's tier table arrives through it), and it runs third, before any suite, so a
+    // convention failure is reported in seconds rather than after the tests.
+    //
+    // Discovered, not registered: `guardFindings` reads the directory. A guard that had to
+    // announce itself is a guard an app can forget to announce, which is the coupling axiom 8's
+    // extension model rejects.
     run: async (ctx) =>
       fromFindings([
         ...(await checkAppBoundaries(ctx.root)),
+        ...(await guardFindings(ctx.root)),
         ...(await hostFindings(ctx, 'boundaries')),
       ]),
   },
@@ -88,10 +121,20 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
   ...TEST_STEPS,
   {
     name: 'drift',
-    summary: 'schema vs migrations',
+    summary: 'schema source vs migrations, and every destructive statement declared',
     // Only an app owns migrations; a package monorepo's `packages/db` is the driver, not a schema.
+    // Source, not database: the gate runs in CI with nothing listening, and the database half is
+    // the post-migrate verification `runMigrations` performs where a connection is already open.
+    //
+    // The destructive rail rides here rather than becoming an eighteenth step because it asks this
+    // step's own question — do the committed migrations still describe what the app is doing to its
+    // schema? — off the same directory, in the same pass, with no database either.
     applies: async (ctx) => existsSync(join(ctx.root, APP_CONFIG_FILE)),
-    run: async (ctx) => fromFindings(await checkDrift(ctx.root)),
+    run: async (ctx) =>
+      fromFindings([
+        ...(await checkSourceDrift(ctx.root)),
+        ...(await checkDestructiveMigrations(ctx.root)),
+      ]),
   },
   {
     name: 'contract-diff',
@@ -112,24 +155,62 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
   },
   {
     name: 'budgets',
-    summary: 'per-route JS bytes and LCP',
+    summary: 'per-route JS bytes and LCP, and the global style layer every document carries',
+    // The global-style assertion rides here rather than becoming an eighteenth step, because this
+    // step already asks the one question it asks: what does the document this build emits actually
+    // contain? It is also the same app load — `appManifest` fills render's stylesheet registry on
+    // its way through — so a separate step would pay for a second one to answer half a question.
+    //
+    // A repo with no `app.config.ts` is the framework monorepo, which renders no documents and has
+    // no stylesheet registry to read; there is nothing for either half to weigh.
+    applies: async (ctx) => existsSync(join(ctx.root, APP_CONFIG_FILE)),
     async run(ctx) {
+      // No stats file is NOT "nothing to weigh" — it is every declared budget unmeasured, which is
+      // the case `checkBudgets` already names per route (`X_BUDGET_UNMEASURED`). Skipping the half
+      // entirely is how a step that has never run once reported green: `.x/` is gitignored, so no
+      // CI run and neither gated app has ever had a `build-stats.json` for it to read.
+      //
+      // Handed over as `undefined` and never as `?? { routes: [] }`: "no build has run here" and
+      // "a build ran and could not weigh this route" are two different instructions, and only the
+      // caller knows which of them is true. The step still does not BUILD — measuring here would
+      // make `x verify` a static build on every run (8.2s on `dummy/social-media-clone`, and 5.9s
+      // to a hard `X_PRERENDER_FAILED` on `examples/dummy`), and it would be a second builder
+      // beside `apps/web/prerender.ts`, which is where an app reads `SITE_ORIGIN`.
       const stats = await readBuildStats(ctx.root);
-      if (stats === undefined) return passed;
-      const { manifest } = await appManifest(ctx.root);
-      return fromFindings(checkBudgets(manifest, stats));
+      // The load's own findings, FIRST and never dropped. A module that would not import registers
+      // no route, so its budget is missing from the manifest and every route it declared reads as
+      // `X_BUDGET_UNMEASURED` — the symptom, pointing the reader at `x build` for a file that will
+      // not compile. `contract-diff` reports these too when it applies; two red steps naming one
+      // broken module is honest, and one of them silently green over it is the false green.
+      const { manifest, findings } = await appManifest(ctx.root);
+      return fromFindings([
+        ...findings,
+        ...checkDocumentStyles(documentSurfaces()),
+        ...checkBudgets(manifest, stats),
+      ]);
     },
   },
   {
     name: 'manifest',
-    summary: 'the two files an agent reads: generated facts, hand-written conventions',
+    summary: 'the files an agent reads: generated facts, hand-written conventions, the env example',
     // No `applies`. The drift half has nothing to compare against until `x manifest` has run
     // once, and says so by finding nothing — but `AGENTS.md` is required of every repo the gate
     // runs in, so the step always has a question to answer and must never report as skipped.
+    //
+    // `.env.example` joins this step rather than becoming an eighteenth: the question is the same
+    // one — "does a committed, generated file still describe the code?" — and the step list is the
+    // definition of shippable, so it grows only when a genuinely new question needs asking.
+    //
+    // `x.verify.json` is here for that same question and no other: this step judges the floor
+    // FILE, `runVerify` judges the suites against it. A name the gate does not run can never
+    // vanish, so a typo in the floor covers nothing — which is the false green the floor exists to
+    // close, and it is only visible if something reads the file for its own sake.
     async run(ctx) {
       const agents = await checkAgentsMd(ctx.root);
       const findings = [
         ...(await driftFindings(ctx.root)),
+        ...(await envExampleFindings(ctx.root)),
+        ...floorProblemFindings(await readVerifyFloor(ctx.root)),
         ...agents.findings,
         ...(await hostFindings(ctx, 'manifest')),
       ];
@@ -147,8 +228,11 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
     name: 'roadmap',
     summary: "every roadmap milestone's status marker matches what is actually on disk",
     // A generated app ships no `docs/idea/14-roadmap.md` — only the framework monorepo does, so
-    // only a host that registers this check has anything for the step to verify.
-    applies: async (ctx) => ctx.hostChecks?.roadmap !== undefined,
+    // the FILE is what decides. It keyed on `ctx.hostChecks?.roadmap` until `As of 2026-08`, which
+    // is a fact about the CALL: a caller of the exported `runVerify(VERIFY_STEPS, ctx)` passing no
+    // `hostChecks`, in a repo whose committed `x.verify.json` names `roadmap`, got
+    // `X_VERIFY_SUITE_VANISHED` — whose `fix:` is the command that had just failed.
+    applies: async (ctx) => existsSync(join(ctx.root, ROADMAP_FILE)),
     run: async (ctx) => fromFindings(await hostFindings(ctx, 'roadmap')),
   },
 ];
@@ -200,11 +284,24 @@ export async function runVerify(
   steps: readonly VerifyStep[],
   ctx: VerifyContext,
 ): Promise<CommandResult> {
+  const floor = await readVerifyFloor(ctx.root);
   const results: StepResult[] = [];
   for (const step of steps) {
     const applies = step.applies === undefined ? true : await step.applies(ctx);
     if (!applies) {
-      results.push({ name: step.name, ok: true, durationMs: 0, skipped: true, findings: [] });
+      // A skip this repo already ruled out is not a skip. The step ran here before — the floor is
+      // that claim, committed — so "nothing to check" now means the suite was deleted, and the
+      // gate says so on the step's own line rather than counting one more thing not to worry
+      // about. Recorded as failed and NOT as skipped, so every reader of a step table sees it:
+      // the summary, `data.failed`, and the reference-app gate's own red list.
+      const required = floorRequires(floor, step.name);
+      results.push({
+        name: step.name,
+        ok: !required,
+        durationMs: 0,
+        skipped: !required,
+        findings: required ? [vanishedSuiteFinding(step.name)] : [],
+      });
       continue;
     }
     const started = performance.now();
@@ -214,31 +311,71 @@ export async function runVerify(
         findings: [findingOf(error, step.name)],
       }),
     );
+    // A step the floor requires whose suite executed nothing is the same vanished suite as a step
+    // with no files at all — the run just had to finish before it could be seen. Appended to the
+    // step's own findings so `data.failed`, the counts and every gate reading this table carry it.
+    const vanished =
+      floorRequires(floor, step.name) && outcome.tests !== undefined && outcome.tests.ran === 0
+        ? [skippedSuiteFinding(step.name, outcome.tests.skipped)]
+        : [];
     results.push({
       name: step.name,
-      ok: outcome.ok,
+      ok: outcome.ok && vanished.length === 0,
       durationMs: Math.round(performance.now() - started),
-      findings: outcome.findings,
+      findings: [...outcome.findings, ...vanished],
       ...(outcome.output === undefined ? {} : { output: outcome.output }),
+      ...(outcome.workers === undefined ? {} : { workers: outcome.workers }),
     });
   }
   const failedSteps = results.filter((step) => !step.ok).map((step) => step.name);
+  const skippedSteps = results.filter((step) => step.skipped === true).map((step) => step.name);
   const totalMs = results.reduce((sum, step) => sum + step.durationMs, 0);
   return {
     ok: failedSteps.length === 0,
     command: 'verify',
-    summary:
-      failedSteps.length === 0
-        ? msg('cli.verify.pass', { count: results.length, ms: totalMs })
-        : msg('cli.verify.fail', { failed: failedSteps.length, count: results.length }),
+    summary: verifySummary({ results, failed: failedSteps, skipped: skippedSteps, totalMs }),
     steps: results,
-    data: { failed: failedSteps, durationMs: totalMs },
+    // `skipped` is a list beside `failed` and not a count, because the two answer the same kind of
+    // question — *which* steps, not how many — and a caller ratcheting on coverage needs the names.
+    data: { failed: failedSteps, skipped: skippedSteps, durationMs: totalMs },
     exitCode: failedSteps.length === 0 ? 0 : 1,
   };
 }
 
+/**
+ * What the counts are allowed to claim. A step that does not apply is recorded green so the run
+ * continues, and the summary counted it among the "all 17 steps passed" — so a repo whose `job`
+ * and `eval` suites do not exist reported the same line as a repo where both ran. `--json` carried
+ * the per-step flag all along; the one line every reader actually sees did not, which is how a
+ * vacuous gate stayed invisible. It names the skipped steps, not just how many: "17/17" is worth
+ * something only when the gap is visible in the same glance.
+ */
+function verifySummary(input: {
+  readonly results: readonly StepResult[];
+  readonly failed: readonly string[];
+  readonly skipped: readonly string[];
+  readonly totalMs: number;
+}): string {
+  const params = {
+    count: input.results.length,
+    passed: input.results.filter((step) => step.ok && step.skipped !== true).length,
+    failed: input.failed.length,
+    skipped: input.skipped.length,
+    names: input.skipped.join(', '),
+    ms: input.totalMs,
+  };
+  const clean = input.skipped.length === 0;
+  if (input.failed.length === 0) {
+    return msg(clean ? 'cli.verify.pass' : 'cli.verify.passSkipped', params);
+  }
+  return msg(clean ? 'cli.verify.fail' : 'cli.verify.failSkipped', params);
+}
+
 function findingOf(error: unknown, step: string): Finding {
-  const cause = error instanceof Error ? error.message : String(error);
+  // A step may throw anything, including an Error that fights being read: `instanceof` runs a
+  // Proxy's `getPrototypeOf` trap and `.message` runs a getter, so a hostile throw would take the
+  // gate's own report down with it — the one message that may never be lost.
+  const cause = renderThrowable(error);
   return {
     code: 'X_VERIFY_FAILED',
     cause: `step "${step}" threw: ${cause}`,
@@ -251,15 +388,50 @@ export const verifyCommand: CliCommand = {
   spec: {
     name: 'verify',
     summary: 'the gate: typecheck, lint, boundaries, all tests, drift, contract, budgets',
-    usage: 'x verify [--json]',
+    usage: 'x verify [--workers N] [--json]',
     requiresApp: true,
-    flags: [],
+    // The only flag, and it is not `--only`/`--skip` in disguise: it changes how wide the test
+    // steps spread, never which steps run. Every step still runs, so "green" still means the
+    // same thing at `--workers 1` as at `--workers 8`.
+    flags: [
+      {
+        name: 'workers',
+        type: 'string',
+        summary: `test processes per parallel step (default: ${WORKER_OVERSUBSCRIBE}x CPUs, min ${WORKER_FLOOR}, max ${WORKER_CEILING})`,
+      },
+    ],
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('verify', ctx.cwd).dir;
-    return runVerify(VERIFY_STEPS, { root, runner: ctx.runner });
+    const workers = readWorkers(ctx.args);
+    return runVerify(VERIFY_STEPS, {
+      root,
+      runner: ctx.runner,
+      ...(workers === undefined ? {} : { workers }),
+    });
   },
 };
 
+/**
+ * Both bounds are the constants the flag summary already names, so `x help verify` and the reader
+ * cannot disagree. Exported for the test that pins them: the command's `run` reaches this only
+ * after the whole gate would have started.
+ *
+ * `max` is the ceiling. Without it `--workers 5000` parsed, `planShards` clamped only to the file
+ * count, and `runParallel` `Promise.all`ed one Bun process per test file. `min` is `WORKER_FLOOR`,
+ * the same number `defaultWorkers` will not go below — the gate spreads or it does not shard, and
+ * `--workers 1` was a serial run the summary said was impossible. `x test --workers 1` stays legal
+ * and is deliberately NOT this reader: `runShards` clamps the width to the file count, so a
+ * one-file corpus makes `X_TEST_SHARD_FAILED`'s own `fix:` say `--workers 1`.
+ */
+export const readWorkers = (args: ParsedArgs): number | undefined =>
+  readIntFlag(args, {
+    name: 'workers',
+    command: 'verify',
+    min: WORKER_FLOOR,
+    max: WORKER_CEILING,
+    example: 'x verify --workers 4',
+  });
+
 export const verifyStepNames = (): readonly VerifyStepName[] =>
   VERIFY_STEPS.map((step) => step.name);