@ultimat3/cli 8.0.0 → 10.0.0

package/src/verify-floor.ts

@@ -7,7 +7,7 @@
 // all, and `join` builds the host-separator path to it.
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { docsFor } from './error-codes';
+import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
 import type { Finding } from './output';
 import { VERIFY_STEP_NAMES } from './verify-step';
 
@@ -43,8 +43,10 @@ export function parseVerifyFloor(
   try {
     payload = JSON.parse(text);
   } catch (error) {
-    const reason = error instanceof Error ? error.message : String(error);
-    return { steps: [], problems: [`it does not parse as JSON (${reason})`] };
+    // `renderThrowable`, never `error instanceof Error ? error.message : String(error)`: both halves
+    // 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 (`metrics-endpoint.ts` states the same rule over `stringField`).
+    return { steps: [], problems: [`it does not parse as JSON (${renderThrowable(error)})`] };
   }
   const steps = asRecord(payload)?.['steps'];
   if (!Array.isArray(steps)) {
@@ -92,7 +94,7 @@ export const vanishedSuiteFinding = (step: string): Finding => ({
   code: 'X_VERIFY_SUITE_VANISHED',
   cause: `${VERIFY_FLOOR_FILE} requires the ${step} step and this run found nothing for it to check`,
   fix: `x verify --json   # restore the ${step} suite, or drop "${step}" from ${VERIFY_FLOOR_FILE} in the commit that says why`,
-  docs: docsFor('X_VERIFY_SUITE_VANISHED'),
+  docs: ERROR_DOCS_URL,
   at: VERIFY_FLOOR_FILE,
 });
 
@@ -111,7 +113,7 @@ export const skippedSuiteFinding = (step: string, skipped: number): Finding => (
   code: 'X_VERIFY_SUITE_VANISHED',
   cause: `${VERIFY_FLOOR_FILE} requires the ${step} step and all ${skipped} test(s) it found skipped themselves, so nothing ran`,
   fix: `x test ${step} --json   # then set what the suite skips without, or drop "${step}" from ${VERIFY_FLOOR_FILE} in the commit that says why`,
-  docs: docsFor('X_VERIFY_SUITE_VANISHED'),
+  docs: ERROR_DOCS_URL,
   at: VERIFY_FLOOR_FILE,
 });
 
@@ -128,6 +130,6 @@ export const floorProblemFindings = (floor: VerifyFloor | undefined): readonly F
     code: 'X_CONFIG_INVALID',
     cause: `${VERIFY_FLOOR_FILE} is not a suite floor: ${problem}`,
     fix: `x verify --json   # then write ${VERIFY_FLOOR_FILE} as {"steps":["unit","contract"]}, naming only steps it ran`,
-    docs: docsFor('X_CONFIG_INVALID'),
+    docs: ERROR_DOCS_URL,
     at: VERIFY_FLOOR_FILE,
   }));

package/src/verify-run.ts

@@ -2,7 +2,7 @@
 // `cmd-verify.ts` because `x build` and the MCP host run the gate without going through the
 // command: what a run means — never bail early, count what actually ran — belongs to neither.
 
-import { renderThrowable } from '@ultimat3/core';
+import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
 import { msg } from './messages';
 import type { CommandResult, Finding, StepResult } from './output';
 import {
@@ -139,6 +139,6 @@ function findingOf(error: unknown, step: string): Finding {
     code: 'X_VERIFY_FAILED',
     cause: `step "${step}" threw: ${cause}`,
     fix: 'x verify --json',
-    docs: 'https://ultimate.dev/errors/X_VERIFY_FAILED',
+    docs: ERROR_DOCS_URL,
   };
 }

package/src/verify-step.ts

@@ -2,6 +2,7 @@
 // repo feeds it findings it could not produce on its own. Split from the step list so a step
 // implementation can live beside the code it checks without importing the list.
 
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { ExecResult, Runner } from './exec';
 import { execOutput } from './exec';
 import type { Finding } from './output';
@@ -106,7 +107,7 @@ export function fromExec(result: ExecResult, finding: Omit<Finding, 'docs'>): St
   if (result.ok) return { ok: true, findings: [], output: execOutput(result) };
   return {
     ok: false,
-    findings: [{ ...finding, docs: `https://ultimate.dev/errors/${finding.code}` }],
+    findings: [{ ...finding, docs: ERROR_DOCS_URL }],
     output: execOutput(result),
   };
 }

package/src/verify-test-run.ts

@@ -3,7 +3,7 @@
 // happens to them once selected — a wrong file list is never a race, and a race is never a
 // selection bug.
 
-import { docsFor } from './error-codes';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Runner } from './exec';
 import { execOutput } from './exec';
 import type { Finding } from './output';
@@ -51,7 +51,7 @@ export async function runParallel(options: ParallelRunOptions): Promise<StepOutc
       // The reproduction has to name every input to the split, or it reruns a different file set:
       // `reproduceFor` is the one place that rule lives, shared with `x test`.
       fix: reproduceFor(shard, { workers: shards.length, type: options.type }),
-      docs: docsFor('X_TEST_SHARD_FAILED'),
+      docs: ERROR_DOCS_URL,
     });
   }
   // Only the failing shards' output: a green 8-way split would otherwise print eight summaries,

package/src/workspace-checks.ts

@@ -5,7 +5,7 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { renderCauseValue } from '@ultimat3/core';
+import { ERROR_DOCS_URL, renderCauseValue } from '@ultimat3/core';
 import type { Finding } from './output';
 import { eachSourceFile, isGenerated } from './source-files';
 import { checkRootReferences } from './tsconfig-references';
@@ -14,13 +14,11 @@ export const LINE_CEILING = 500;
 
 export const PACKAGE_FILES = ['README.md', 'CLAUDE.md', 'tsconfig.json', 'src/index.ts'] as const;
 
-const docs = (code: string): string => `https://ultimate.dev/errors/${code}`;
-
 export const tooLongFinding = (path: string, lines: number): Finding => ({
   code: 'X_FILE_TOO_LONG',
   cause: `${path} is ${lines} lines, over the ${LINE_CEILING} line ceiling`,
   fix: `split ${path}: one file, one responsibility`,
-  docs: docs('X_FILE_TOO_LONG'),
+  docs: ERROR_DOCS_URL,
   at: path,
 });
 
@@ -49,7 +47,7 @@ export const missingFileFinding = (dir: string, file: string, scaffolder: boolea
   fix: scaffolder
     ? `bun run scripts/new-package.ts ${dir} --only ${file}`
     : `add packages/${dir}/${file}, shaped like the one in a sibling package`,
-  docs: docs('X_PACKAGE_SHAPE'),
+  docs: ERROR_DOCS_URL,
   at: `packages/${dir}/${file}`,
 });
 
@@ -68,7 +66,7 @@ export const badVersionFinding = (dir: string, found: unknown): Finding => ({
   // this finding with a TypeError from inside the gate.
   cause: `packages/${dir}/package.json has no semver "version" (found ${renderCauseValue(found)})`,
   fix: `set a semver "version" in packages/${dir}/package.json, then: bun run verify`,
-  docs: docs('X_PACKAGE_SHAPE'),
+  docs: ERROR_DOCS_URL,
   at: `packages/${dir}/package.json`,
 });
 
@@ -103,7 +101,7 @@ export const versionSkewFinding = (dir: string, found: string, expected: string)
   code: 'X_RELEASE_VERSION_SKEW',
   cause: `packages/${dir} is at ${found}, not the lockstep version ${expected}`,
   fix: `bun run scripts/release.ts --version ${expected}`,
-  docs: docs('X_RELEASE_VERSION_SKEW'),
+  docs: ERROR_DOCS_URL,
   at: `packages/${dir}/package.json`,
 });
 
@@ -116,7 +114,7 @@ export const pinSkewFinding = (
   code: 'X_RELEASE_VERSION_SKEW',
   cause: `packages/${dir} pins ${dep} at ${range}, not the lockstep version ${expected}`,
   fix: `bun run scripts/release.ts --version ${expected}`,
-  docs: docs('X_RELEASE_VERSION_SKEW'),
+  docs: ERROR_DOCS_URL,
   at: `packages/${dir}/package.json`,
 });
 
@@ -167,7 +165,7 @@ export const missingPublishedFileFinding = (dir: string, entry: string): Finding
   code: 'X_PACKAGE_SHAPE',
   cause: `packages/${dir}/package.json ships "${entry}" in "files", but packages/${dir}/${entry} does not exist`,
   fix: `add packages/${dir}/${entry}, or drop "${entry}" from "files" in packages/${dir}/package.json`,
-  docs: docs('X_PACKAGE_SHAPE'),
+  docs: ERROR_DOCS_URL,
   at: `packages/${dir}/package.json`,
 });
 
@@ -175,7 +173,7 @@ export const publishesTestsFinding = (dir: string): Finding => ({
   code: 'X_PACKAGE_SHAPE',
   cause: `packages/${dir}/package.json does not exclude ${TEST_EXCLUSION} from "files"`,
   fix: `add "${TEST_EXCLUSION}" to "files" in packages/${dir}/package.json, after "src"`,
-  docs: docs('X_PACKAGE_SHAPE'),
+  docs: ERROR_DOCS_URL,
   at: `packages/${dir}/package.json`,
 });
 
@@ -196,7 +194,7 @@ export const buildArtifactsFinding = (dir: string, count: number): Finding => ({
   code: 'X_PACKAGE_SHAPE',
   cause: `packages/${dir}/src/ contains ${count} build artifacts (.d.ts, .js, .map files)`,
   fix: `find packages/${dir}/src ${SWEEP_PREDICATE} -delete`,
-  docs: docs('X_PACKAGE_SHAPE'),
+  docs: ERROR_DOCS_URL,
   at: `packages/${dir}/src/`,
 });
 
@@ -209,7 +207,7 @@ export const noFilesAllowlistFinding = (dir: string): Finding => ({
   code: 'X_PACKAGE_SHAPE',
   cause: `packages/${dir}/package.json publishes with no "files" allowlist, so the tarball carries whatever is in the directory`,
   fix: `add "files": ["src", "${TEST_EXCLUSION}", "README.md", "LICENSE"] to packages/${dir}/package.json`,
-  docs: docs('X_PACKAGE_SHAPE'),
+  docs: ERROR_DOCS_URL,
   at: `packages/${dir}/package.json`,
 });
 

package/src/workspace-graph.ts

@@ -4,6 +4,7 @@
 // for `tsc` and is invisible to bun, to `--filter` ordering and to any change-detection tool.
 
 import { join } from 'node:path';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Finding } from './output';
 import { eachSourceFile, isGenerated, isTest, isVendored } from './source-files';
 import { maskLiterals } from './ts-scan';
@@ -184,7 +185,7 @@ export const unreadableWorkspaceFinding = (path: string): Finding => ({
   code: 'X_APP_PACKAGE_INVALID',
   cause: `${path} is claimed by the root "workspaces" globs and supplies no readable "name"`,
   fix: `repair the JSON and the "name" in ${path}, or drop its directory from "workspaces" in package.json`,
-  docs: 'https://ultimate.dev/errors/X_APP_PACKAGE_INVALID',
+  docs: ERROR_DOCS_URL,
   at: path,
 });
 
@@ -198,7 +199,7 @@ export const undeclaredWorkspaceDepFinding = (
   // The exact line to paste, at the version the target really carries: a `workspace:*` range would
   // resolve and then fail `checkLockstep`, which compares a sibling pin against the version.
   fix: `add "${to.name}": "${to.version ?? '0.0.0'}" to "dependencies" in ${from.dir}/package.json`,
-  docs: 'https://ultimate.dev/errors/X_WORKSPACE_DEP_UNDECLARED',
+  docs: ERROR_DOCS_URL,
   at: `${from.dir}/package.json`,
 });
 

package/src/write-line.ts

@@ -5,6 +5,9 @@
 
 // `node:fs`, and unavoidable: Bun has no synchronous stdout write of its own.
 import { writeSync } from 'node:fs';
+// The one import beyond `node:fs`, and it costs nothing here: `create-ultimate` reaches this
+// module through `@ultimat3/cli`'s barrel, which has already evaluated core.
+import { stringField } from '@ultimat3/core';
 
 /**
  * Write to stdout and be certain it arrived, even if the next statement exits the process.
@@ -29,7 +32,10 @@ function writeTo(fd: 1 | 2, line: string): void {
     try {
       written += writeSync(fd, buffer, written, buffer.length - written);
     } catch (cause) {
-      if ((cause as NodeJS.ErrnoException).code !== 'EAGAIN') throw cause;
+      // `stringField`, never a cast plus a property read — the rule `metrics-endpoint.ts` states
+      // and `caught-value-reads.test.ts` enforces. Here it is also the difference between
+      // rethrowing and an infinite loop: a `code` that cannot be read must not read as `EAGAIN`.
+      if (stringField(cause, 'code') !== 'EAGAIN') throw cause;
     }
   }
 }