@ultimat3/cli 22.14.0 → 23.0.0

package/src/verify-merge.ts

@@ -6,10 +6,21 @@
 // - the zero-tests floor applied to the SUMMED counts of a sharded step, which each shard deferred;
 // - any gap is a named `X_VERIFY_MERGE_INCOMPLETE` finding, never a silent pass.
 //
+// - an app's coverage floor judged HERE for a sharded `unit` step: one shard's slice cannot hold a
+//   floor, so each hands its facts over in its document and the fold is judged once.
+//
 // The merged document is a gate run (no `notAGateRun`), because the question it answers — did
 // every step run, over the whole tree, and pass — is the gate's question.
 
+// why: Bun ships no synchronous existence check and no path-join primitive.
+import { existsSync } from 'node:fs';
+// why: Bun ships no path-join primitive.
+import { join } from 'node:path';
 import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
+import { APP_CONFIG_FILE } from './app-root';
+import { judgeCoverage } from './coverage-floor';
+import type { CoverageMap } from './coverage-lcov';
+import { decodeCoverage, mergeCoverage } from './coverage-lcov';
 import { msg } from './messages';
 import type { CommandResult, Finding, StepResult } from './output';
 import type { TestCounts } from './test-counts';
@@ -17,7 +28,7 @@ import { VerifyMergeInputError } from './verify-errors';
 import type { VerifyFloor } from './verify-floor';
 import { floorRequires, skippedSuiteFinding } from './verify-floor';
 import { verifySummary } from './verify-run';
-import { VERIFY_STEP_NAMES } from './verify-step';
+import { GATE_COMMAND, VERIFY_STEP_NAMES } from './verify-step';
 
 interface PartStep {
   readonly name: string;
@@ -40,6 +51,19 @@ export interface VerifyPart {
   readonly file: string;
   readonly durationMs: number;
   readonly steps: readonly PartStep[];
+  /** step → what this part's slice of it covered and did not judge (`data.coverage.<step>.facts`). */
+  readonly coverage?: Readonly<Record<string, CoverageMap>>;
+}
+
+/** Findings a step earns from the parts TOGETHER, which no one part could raise. */
+export type MergeRiders = Readonly<
+  Record<string, { readonly findings: readonly Finding[]; readonly output?: string }>
+>;
+
+export interface MergeOptions {
+  /** The gate as invoked here, for the `fix:` of a gap. */
+  readonly command?: string;
+  readonly riders?: MergeRiders;
 }
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
@@ -49,12 +73,12 @@ const isRecord = (value: unknown): value is Record<string, unknown> =>
  * The LAST non-empty line that parses: `bin/check --json` prints the build's document and then
  * the gate's, and a reader takes the last one.
  */
-export function parsePart(file: string, text: string): VerifyPart {
+export function parsePart(file: string, text: string, command: string = GATE_COMMAND): VerifyPart {
   const lines = text
     .split('\n')
     .map((line) => line.trim())
     .filter((line) => line.length > 0);
-  if (lines.length === 0) throw new VerifyMergeInputError({ file, reason: 'is empty' });
+  if (lines.length === 0) throw new VerifyMergeInputError({ file, reason: 'is empty', command });
   let doc: unknown;
   try {
     doc = JSON.parse(lines[lines.length - 1] as string);
@@ -63,47 +87,101 @@ export function parsePart(file: string, text: string): VerifyPart {
       file,
       reason: `does not end in a JSON document (${renderThrowable(error)})`,
       sourceError: error,
+      command,
     });
   }
   if (!isRecord(doc) || doc['command'] !== 'verify' || !Array.isArray(doc['steps'])) {
     throw new VerifyMergeInputError({
       file,
       reason: 'is not an x verify --json document (no "command": "verify" with "steps")',
+      command,
     });
   }
   const data = isRecord(doc['data']) ? doc['data'] : {};
   const steps: PartStep[] = [];
   for (const raw of doc['steps'] as unknown[]) {
     if (!isRecord(raw) || typeof raw['name'] !== 'string' || typeof raw['ok'] !== 'boolean') {
-      throw new VerifyMergeInputError({ file, reason: 'holds a step without a name and ok' });
+      throw new VerifyMergeInputError({
+        file,
+        reason: 'holds a step without a name and ok',
+        command,
+      });
     }
     steps.push(raw as unknown as PartStep);
   }
+  const coverage = new Map<string, CoverageMap>();
+  for (const [step, entry] of Object.entries(isRecord(data['coverage']) ? data['coverage'] : {})) {
+    // A part that judged its own floor carries numbers, not facts: nothing here to fold.
+    if (!isRecord(entry) || !('facts' in entry)) continue;
+    const map = decodeCoverage(entry['facts']);
+    if (map === undefined) {
+      throw new VerifyMergeInputError({
+        file,
+        reason: `carries coverage for "${step}" that is not a coverage map`,
+        command,
+      });
+    }
+    coverage.set(step, map);
+  }
   return {
     file,
     durationMs: typeof data['durationMs'] === 'number' ? data['durationMs'] : 0,
     steps,
+    ...(coverage.size === 0 ? {} : { coverage: Object.fromEntries(coverage) }),
   };
 }
 
-const gap = (cause: string, at?: string): Finding => ({
-  code: 'X_VERIFY_MERGE_INCOMPLETE',
-  cause,
-  fix: 'x verify merge parts/*.json --json   # after every CI job uploaded its part',
-  docs: ERROR_DOCS_URL,
-  ...(at === undefined ? {} : { at }),
-});
+/** A gap finding, with a fix spelled for the entry that raised it. */
+type Gap = (cause: string, at?: string) => Finding;
+
+const gapFor =
+  (command: string): Gap =>
+  (cause, at) => ({
+    code: 'X_VERIFY_MERGE_INCOMPLETE',
+    cause,
+    fix: `${command} merge parts/*.json --json   # after every CI job uploaded its part`,
+    docs: ERROR_DOCS_URL,
+    ...(at === undefined ? {} : { at }),
+  });
+
+/** The step every part's coverage facts belong to. */
+const COVERED_STEP = 'unit';
+
+/**
+ * An app's coverage floor over a SHARDED `unit` step, judged once on the fold of every shard —
+ * the finding no shard could raise alone. Nothing when the step was not split (the whole run
+ * judged itself), when a shard is red (a failed slice wrote no lcov, and its own finding is the
+ * one to read), or outside an app. Shards that carry no facts at all fold to an empty map, which
+ * is 0% and a red gate: a split can never skip the floor by saying nothing.
+ */
+export async function coverageRiders(
+  parts: readonly VerifyPart[],
+  root: string,
+  floor: VerifyFloor | undefined,
+): Promise<MergeRiders> {
+  if (!existsSync(join(root, APP_CONFIG_FILE))) return {};
+  const shards = parts.flatMap((part) =>
+    part.steps
+      .filter((step) => step.name === COVERED_STEP && step.shard !== undefined)
+      .map((step) => ({ step, coverage: part.coverage?.[COVERED_STEP] })),
+  );
+  if (shards.length === 0 || shards.some((shard) => !shard.step.ok)) return {};
+  const folded = mergeCoverage(
+    shards.flatMap((shard) => (shard.coverage === undefined ? [] : [shard.coverage])),
+  );
+  const verdict = await judgeCoverage(root, folded, floor?.coverage);
+  return { [COVERED_STEP]: { findings: verdict.findings, output: verdict.output } };
+}
 
 const sumCounts = (steps: readonly PartStep[]): TestCounts | undefined => {
   const counted = steps.filter((step) => step.tests !== undefined);
   if (counted.length === 0) return undefined;
-  return counted.reduce<TestCounts>(
-    (sum, step) => ({
-      ran: sum.ran + (step.tests?.ran ?? 0),
-      skipped: sum.skipped + (step.tests?.skipped ?? 0),
-    }),
-    { ran: 0, skipped: 0 },
-  );
+  const errors = counted.reduce((sum, step) => sum + (step.tests?.errors ?? 0), 0);
+  return {
+    ran: counted.reduce((sum, step) => sum + (step.tests?.ran ?? 0), 0),
+    skipped: counted.reduce((sum, step) => sum + (step.tests?.skipped ?? 0), 0),
+    ...(errors === 0 ? {} : { errors }),
+  };
 };
 
 /** One step's entries from every part, folded into one step result and its gaps. */
@@ -111,6 +189,8 @@ function mergeStep(
   name: string,
   entries: readonly { readonly part: string; readonly step: PartStep }[],
   floor: VerifyFloor | undefined,
+  gap: Gap,
+  rider: MergeRiders[string] | undefined,
 ): StepResult {
   if (entries.length === 0) {
     return {
@@ -174,16 +254,23 @@ function mergeStep(
   const nothingRan = sharded.length > 0 && tests !== undefined && tests.ran === 0;
   const required = floorRequires(floor, name);
   const floorGap = nothingRan && required ? [skippedSuiteFinding(name, tests.skipped)] : [];
-  const findings = [...steps.flatMap((step) => step.findings), ...gaps, ...floorGap];
-  const output = steps
-    .filter((step) => !step.ok && step.output !== undefined && step.output.length > 0)
-    .map((step) => step.output as string)
-    .join('\n');
+  const riding = rider?.findings ?? [];
+  const findings = [...steps.flatMap((step) => step.findings), ...gaps, ...floorGap, ...riding];
+  const output = [
+    ...steps
+      .filter((step) => !step.ok && step.output !== undefined && step.output.length > 0)
+      .map((step) => step.output as string),
+    ...(rider?.output === undefined ? [] : [rider.output]),
+  ].join('\n');
   const skipped =
     sharded.length > 0 ? nothingRan && !required : steps.every((step) => step.skipped);
   return {
     name,
-    ok: steps.every((step) => step.ok) && gaps.length === 0 && floorGap.length === 0,
+    ok:
+      steps.every((step) => step.ok) &&
+      gaps.length === 0 &&
+      floorGap.length === 0 &&
+      riding.length === 0,
     // The slowest job: the parts ran side by side, and wall time is what a CI run waits on.
     durationMs: Math.max(...steps.map((step) => step.durationMs)),
     ...(skipped ? { skipped: true } : {}),
@@ -198,7 +285,9 @@ export function mergeParts(
   parts: readonly VerifyPart[],
   floor: VerifyFloor | undefined,
   declared: readonly string[] = VERIFY_STEP_NAMES,
+  options: MergeOptions = {},
 ): CommandResult {
+  const gap = gapFor(options.command ?? GATE_COMMAND);
   const unknown = parts.flatMap((part) =>
     part.steps
       .filter((step) => !declared.includes(step.name))
@@ -211,6 +300,10 @@ export function mergeParts(
         part.steps.filter((step) => step.name === name).map((step) => ({ part: part.file, step })),
       ),
       floor,
+      gap,
+      options.riders !== undefined && Object.hasOwn(options.riders, name)
+        ? options.riders[name]
+        : undefined,
     ),
   );
   const failed = steps.filter((step) => !step.ok).map((step) => step.name);

package/src/verify-progress.ts

@@ -0,0 +1,25 @@
+// One finished gate step as one line of JSON, for stderr. `x verify --json` prints its document
+// when the run ENDS, so a job cancelled mid-run used to leave a log with nothing in it (#589):
+// the last of these lines is the last step that finished, and the hung one is whichever is next.
+
+import type { StepResult } from './output';
+
+/** `{"step":"lint","ok":true,"ms":21987}` — plus `"skipped":true` for a step that did not apply. */
+export const stepLine = (step: StepResult): string =>
+  JSON.stringify({
+    step: step.name,
+    ok: step.ok,
+    ms: step.durationMs,
+    ...(step.skipped === true ? { skipped: true } : {}),
+  });
+
+/**
+ * The `onStep` a `--json` run streams through, or nothing: the human render needs no second
+ * channel. One function for both entries (`x verify`, and `bun run verify` at the framework
+ * root), so the two cannot print different lines.
+ */
+export const stepStream = (
+  json: boolean,
+  write: (line: string) => void,
+): { readonly onStep?: (step: StepResult) => void } =>
+  json ? { onStep: (step) => write(stepLine(step)) } : {};

package/src/verify-role-load-probe.ts

@@ -0,0 +1,54 @@
+// The child `verify-role-load.ts` spawns: `bun verify-role-load-probe.ts <app root>`. Imports what
+// a worker imports, then every module that load left out — one at a time — and prints what each of
+// those registered that the worker's process did not hold. Run by hand, it is the same answer.
+
+import { scanAppModules } from './app-load';
+import { scanBackground } from './role-load';
+import type { MissingRegistration } from './verify-role-load';
+import { PROBE_MARKER, registeredSince, registrations } from './verify-role-load';
+import { writeLine } from './write-line';
+
+/**
+ * What importing each module the worker load left out registered, by module — `[]` when the whole
+ * scan reported a module that would not import. Exported so a test calls it in its own process;
+ * the gate runs it as a child, where the registries hold nothing the gate's own load put there.
+ */
+export async function probeRoleLoad(root: string): Promise<readonly MissingRegistration[]> {
+  const background = await scanBackground(root);
+  const imported = new Set(background.files);
+  let held = registrations();
+  const missing: MissingRegistration[] = [];
+  let current: string | undefined;
+
+  /** Whatever appeared since the last look was registered by importing `current`. */
+  const attribute = (): void => {
+    const now = registrations();
+    if (current !== undefined) {
+      for (const one of registeredSince(held, now)) missing.push({ ...one, module: current });
+    }
+    held = now;
+  };
+
+  // The whole app, in the scan's own order. `include` is asked before each import, so the look it
+  // takes is at what the PREVIOUS module added; a module the worker already imported adds nothing.
+  const prefix = root.endsWith('/') ? root : `${root}/`;
+  const whole = await scanAppModules(root, {
+    track: false,
+    include: (absolute) => {
+      attribute();
+      const file = absolute.startsWith(prefix) ? absolute.slice(prefix.length) : absolute;
+      current = imported.has(file) ? undefined : file;
+      return true;
+    },
+  });
+  attribute();
+  // A module that would not import registered nothing in EITHER load, and the gate's own load
+  // already reports it: an answer drawn from a short scan would blame the wrong thing.
+  return whole.findings.length > 0 ? [] : missing;
+}
+
+if (import.meta.main) {
+  const answer = await probeRoleLoad(process.argv[2] ?? process.cwd());
+  writeLine(`${PROBE_MARKER}${JSON.stringify(answer)}`);
+  process.exit(0);
+}

package/src/verify-role-load.ts

@@ -0,0 +1,148 @@
+// The gate's half of per-role loading (`manifest` step): a worker and a scheduler import the API
+// index and every module that reaches no component or stylesheet (`role-load.ts`). A registration
+// made in a module that DOES reach one, and that the index does not import, exists in the web role
+// and in every tool — and not in a worker. At boot only jobs and tasks are checked, against the
+// manifest; this is the build error for everything else a job reads by name.
+
+// why: Bun ships no path API; the fix names the import relative to the API index.
+import { dirname, join, relative } from 'node:path';
+import { ERROR_DOCS_URL, registeredServiceNames, singleLine } from '@ultimat3/core';
+import { entityNames } from '@ultimat3/entity';
+import { catalogDeclarationCount } from '@ultimat3/i18n';
+import { registeredBackfills, registeredJobs, registeredTasks } from '@ultimat3/jobs';
+import { registeredLayouts, registeredMailIds } from '@ultimat3/mail';
+import { registeredChannels } from '@ultimat3/realtime';
+import { definedStorage } from '@ultimat3/storage';
+import { API_INDEX } from './app-root';
+import type { Runner } from './exec';
+import type { Finding } from './output';
+import { quoteArg } from './shell-quote';
+
+/** One thing a process registered, as a job would ask for it: by kind and by name. */
+export interface Registration {
+  readonly kind: string;
+  readonly name: string;
+}
+
+/** A registration the whole app makes and the background load does not, and the module it took. */
+export interface MissingRegistration extends Registration {
+  /** App-root-relative: the scanned module whose import registered it. */
+  readonly module: string;
+}
+
+/**
+ * Every name-keyed registry a job body can read without importing the declaration: what
+ * `ctx.<service>`, `disk('x')`, `t('key')`, a mail layout or a channel resolves through. A
+ * registry read only through a static import of its declaration is not here — the import loads it.
+ */
+export function registrations(): readonly Registration[] {
+  const of = (kind: string, names: readonly string[]): readonly Registration[] =>
+    names.map((name) => ({ kind, name }));
+  return [
+    ...of('service', registeredServiceNames()),
+    ...of('storage disk', definedStorage()?.diskNames ?? []),
+    // A catalog declaration carries no name of its own: the count is what a module adds to.
+    ...of(
+      'catalog declaration',
+      Array.from({ length: catalogDeclarationCount() }, (_, at) => `#${String(at + 1)}`),
+    ),
+    ...of('entity', entityNames()),
+    ...of(
+      'job',
+      registeredJobs().map((job) => job.name),
+    ),
+    ...of(
+      'task',
+      registeredTasks().map((task) => task.name),
+    ),
+    ...of(
+      'backfill',
+      registeredBackfills().map((backfill) => backfill.name),
+    ),
+    ...of('mail', registeredMailIds()),
+    ...of('mail layout', registeredLayouts()),
+    ...of(
+      'channel',
+      registeredChannels().map((channel) => channel.name),
+    ),
+  ];
+}
+
+const keyOf = (one: Registration): string => `${one.kind}\u0000${one.name}`;
+
+/** What `after` holds that `before` did not. */
+export function registeredSince(
+  before: readonly Registration[],
+  after: readonly Registration[],
+): readonly Registration[] {
+  const had = new Set(before.map(keyOf));
+  return after.filter((one) => !had.has(keyOf(one)));
+}
+
+/** The import the API index is missing, as it would be written there. */
+function specifierFor(module: string): string {
+  const from = relative(dirname(API_INDEX), module).replace(/\.[jt]sx?$/, '');
+  return from.startsWith('.') ? from : `./${from}`;
+}
+
+export function roleLoadFinding(missing: MissingRegistration): Finding {
+  return {
+    code: 'X_ROLE_LOAD_INCOMPLETE',
+    cause: `${missing.kind} ${JSON.stringify(missing.name)} is registered by importing ${missing.module}, which reaches a component or a stylesheet and which ${API_INDEX} does not import — so a worker and a scheduler, which import no document, run without it`,
+    fix: `edit ${API_INDEX}: add import '${specifierFor(missing.module)}'; — or move the ${missing.kind} out of ${missing.module} into a module that imports no .tsx and no stylesheet`,
+    docs: ERROR_DOCS_URL,
+    at: missing.module,
+  };
+}
+
+/** The line the probe prints its answer on; everything else it writes is a module's own output. */
+export const PROBE_MARKER = 'x-role-load-probe:';
+
+const PROBE = join(import.meta.dir, 'verify-role-load-probe.ts');
+
+const isMissing = (value: unknown): value is MissingRegistration => {
+  if (typeof value !== 'object' || value === null) return false;
+  const one = value as Record<string, unknown>;
+  return (
+    typeof one['kind'] === 'string' &&
+    typeof one['name'] === 'string' &&
+    typeof one['module'] === 'string'
+  );
+};
+
+/** The probe's answer off its stdout — `undefined` when it printed none. */
+export function parseProbe(stdout: string): readonly MissingRegistration[] | undefined {
+  const line = stdout
+    .split('\n')
+    .reverse()
+    .find((one) => one.startsWith(PROBE_MARKER));
+  if (line === undefined) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(line.slice(PROBE_MARKER.length));
+    return Array.isArray(parsed) && parsed.every(isMissing) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * One child, because the comparison needs a process whose registries hold ONLY what the background
+ * load put there — this one has already imported the whole app. The child imports what a worker
+ * imports, then the rest module by module, and answers what each of those added.
+ */
+export async function roleLoadFindings(root: string, runner: Runner): Promise<readonly Finding[]> {
+  const result = await runner(['bun', PROBE, root], { cwd: root });
+  const missing = parseProbe(result.stdout);
+  if (missing !== undefined) return missing.map(roleLoadFinding);
+  // No answer is not a pass: the load a worker performs did not complete in a clean process.
+  const said = singleLine(result.stderr.trim().split('\n').at(-1) ?? '');
+  return [
+    {
+      code: 'X_ROLE_LOAD_INCOMPLETE',
+      cause: `the worker's load of this app did not complete in a process of its own (exit ${String(result.code)}${said === '' ? '' : `: ${said}`}), so what a worker registers could not be compared with the whole app`,
+      fix: `bun ${quoteArg(PROBE)} ${quoteArg(root)}`,
+      docs: ERROR_DOCS_URL,
+      at: API_INDEX,
+    },
+  ];
+}