spine-rigc 2.16.0 → 2.17.0

package/docs/AUTHORING.md

@@ -234,6 +234,7 @@ What the flags mean:
 | `--cut` | `build`, `explain` and `validate`: look up a named cut in `--cuts <cuts.json>`, **instead of** `--rig`/`--motion`/`--out` — the two spellings are one build stated two ways and are refused together. A `cuts.json` is `{ "<name>": { "rig": …, "motion": …, "out": …, "manifest"?: … } }`, every path in it relative to the table's own file, so the table lives with the project that owns the art |
 | `--cuts` | the `cuts.json` `--cut` names. Required beside it — `--cut` alone is refused, with no guess at where the table lives |
 | `--profile` | `spine` = the 34 validity rules (**the default**) · `spine-html` = all 50, opt-in |
+| `--report` | `build` and `repack`: also write the gate's report as a JSON document (`build-report/1`) to this file — every gate's `PASS`, `SKIP` and `FAIL` rows, its summary figures and stats line, which supplier judged it, and every `pack:` line's figures. Written when the command writes `--out` and when a gate is red, before the exit; a file already at the path is removed first, so a compile error or a refused repack leaves none. Never inside `--out`, refused by name. The printed lines are byte-identical with it and without it — **§5.3** |
 | `--candidate` | `check`, `bench`, `render`, `preview`, `chainfit` and `vote` only: a **compiled** artifact — the directory `build --out` wrote, or a `skeleton.json` path. A directory holding no `skeleton.json`, or a path with nothing at it, is refused `nothing at <path>`, exit 2, nothing written, by every command that takes a build — `validate <dir>` and a directory given to `diff` included (`RC27`). `--atlas <path>` names the atlas when it does not sit beside the skeleton. On `render` and `check` a rigc build whose `skeleton.model.json` is `rigc-compiled/3` or `/2` needs no atlas at all: with no `--atlas` and no atlas beside it, it is drawn from the document's `pages`, the same frames, geometry and figures as with it, and the `atlas` line says `— not there`. An atlas that is there is still read, and held to `pages`: one that differs (edited after the build) is drawn through spine-core, and the `poser` line names the first difference. A build drawn through an atlas that is not there — a `rigc-compiled/1` document, or a build the core refuses — is refused `nothing at <the atlas>: … is drawn through its atlas (<why>)`, exit 2, nothing written; a Spine export without its atlas is refused `nothing at <the atlas>` as it always was. A directory whose files are not one build — a `skeleton.json` or a `skeleton.atlas` from another build beside this one's `skeleton.model.json` — is drawn through spine-core where the runtime can load the pair, the `poser` line naming the two digests or the atlas's first difference; where it cannot, it is refused `<skeleton> does not load against <the atlas>: spine-core draws this pair (<the poser line's why>) and could not resolve it — "<the runtime's own words>". <dir> is not one build: …`, exit 2, nothing written (`RC18`) — another build's skeleton beside this build's atlas typically ends `"Region not found in atlas: <region> (attachment: <name>)"`. Rebuild, or put the build's own three files back beside each other. A Spine export beside an atlas it was not exported with is refused in the same words, ending `The skeleton and the atlas are not one pair`. An atlas copied from another build's directory usually stops earlier, at its pages — their paths are relative to the directory it was written in — and is refused naming the first one: `nothing at <the page>: <the atlas> names it as a page, and spine-core draws this pair through that atlas (<why>). … <dir> is not one build: …`, exit 2, nothing written (`RC18`); an export whose atlas names a page that is not there is refused the same way, ending `and the page has to be there`. A build moved or copied whole away from the directory it was built in stops at the same place, on either poser, and is refused naming the page and the file that names it: `nothing at <the page>: <the skeleton.model.json> names it as a page, and the core draws this build from it. A page path is relative to the build's directory, so a build moved or copied away from the directory it was built in names pages that are not here — build it again where it is, or build it with --copy-images, which writes its pages beside it` (under `--poser spine`, `<the atlas> names it as a page, and spine-core draws this pair through that atlas (--poser spine)` with the same ending), exit 2, nothing written (`RC21`); only where the core refused the files does a page refusal say the directory is not one build. `bench --bones` and `rigc bonedist` — on its `--candidate` and on its `--reference` — refuse a pair the runtime cannot load in the words above with `spine-core poses this pair (bonedist's candidate: …)` or `(bonedist's reference: …)`, exit 2, nothing written (`RC20`); they read no page image, so a build whose pages are elsewhere is measured as it is in place. A `skeleton.json` that is not JSON is refused `rigc: cannot read <the file>: <the parser's words> (line N, column N)`, exit 2, by `render`, `check`, `bench` and `bonedist` as by every other command that reads one (`RC22`). With the atlas gone, `check` on a `rigc-compiled/3` build reads its pages' `scale:` lines off the document, so its texture note and `check.json`'s `textureFrom.candidateScales` are what they are with the atlas; on a `/2` build its texture note says whether the atlas declares a `scale:` line is not read (that document does not state one), and `candidateScales` is `null` (`RC13`). **`vote` and `preview` take it more than once**: `vote` 2–4 times, one per pane, labelled A, B, C, D in the order given; `preview` any number of times, one pane per candidate in the order given, each headed by its path and its gate line, and the same skeleton twice (a directory and its `skeleton.json` are one) is refused by name. `--atlas` goes with one candidate only. Everywhere else a repeat is a typo and is refused |
 | `--animation` | `render`, `preview` and `vote` only: which animation to show. The default is **every** one for `render`, the **first** for `preview` (each candidate's own first, with several), and for `vote` the first of candidate A. A name the skeleton does not have is refused, with the ones it does have listed — and for `vote` and a several-candidate `preview`, so is a name that only *some* candidates have, naming the one that lacks it |
 | `--geometry` | `render` only: also write a `geometry.json` into each frame directory — per frame, every bone's world transform and every slot's region or mesh vertices in world units after skinning, plus each attachment's rest geometry and topology, on the frames' own grid and viewport. Every other file is byte for byte what the render writes without it. Refused with `--slot`/`--hide`, because the geometry is the whole pose whatever is drawn — **§8.2** |
@@ -6426,6 +6427,53 @@ Fix A00 and run it again.
 `both ◑` marks a mixed assertion: its validity half always runs and its policy
 clauses are gated by profile.
 
+### 5.3 The report as a document — `--report <file>`
+
+The lines above are written for an agent to read. A program that acts on a build —
+take it or refuse it, read where the packer put the pages — should not read them with
+regular expressions: every wording change this guide tracks as the interface would
+break it, and nothing promised it the wording. `build --report <file>` and
+`repack --report <file>` write the same report as a JSON document beside the build,
+and **the printed lines do not change by a byte** with the flag (`BR03`).
+
+| key | what it is | the line it restates |
+| --- | --- | --- |
+| `spec` | `"build-report/1"` | — |
+| `command` | `"build"` or `"repack"` | the command that ran |
+| `supplier` | `"round-trip"` (the entry that links spine-core) or `"model"` (`cli_core.ts`, the model side and the rules restated over the emitted text) | the `validate (…)` heading |
+| `gates[]` | one per gate, in the order run: the compile's, then under `--pack` the packed pages' | each `profile` line opens one |
+| `gates[].atlas` | `"compiled"` or `"packed"` | `validate (packed atlas, pages on disk)` before the second |
+| `gates[].passed` | the rule names, in the order printed | the `PASS` lines |
+| `gates[].skipped[]` | `{ code, reason }`, in the order printed | the `SKIP` lines |
+| `gates[].failures[]` | `{ code, detail }`, one per line — a rule that fails twice is two entries | the `FAIL` lines |
+| `gates[].summary` | `{ assertions, measured, passed, failed, skipped, notInProfile, profile }`, every figure a count of assertions | the `N assertions: …` line |
+| `gates[].stats` | the keys and values, in order | the `pages=… regions=…` line |
+| `gates[].here` | `{ modelSide, restated, notRun }` on the core entry, `null` on the round trip | the `here:` line |
+| `pack` | `null` without `--pack`; else one `{ page, width, height, regions, coveredPct, padding, pageEdges, packShape }` per page, `coveredPct` at the line's one decimal and `pageEdges` `"pot"` or `"free"` | the `pack:` lines |
+
+A `PROF` row is counted in `summary.notInProfile` and not listed; the per-region
+placement lines under `pack:`, the `MESH`, `DROP` and `copy-images` lines and the
+`rigc: wrote` lines are not in it. That is not an oversight: the first version carries
+the fields a dependant was observed reading off the sentences and the figures the
+summary line states, and nothing else (`BR09` holds the keys to that census and names a
+key outside it). Every value is read from the lists the lines are printed from, so the
+document and the lines cannot disagree (`BR01`, `BR02`, `BR05`, `BR08`).
+
+- **When it is written.** When the command writes `--out`, after the last file; and
+  when a gate is red, before the exit — so a red build's document carries its `FAIL`
+  rows (`BR05`). A file already at the path is removed before anything is compiled, so
+  any other ending — a compile error, a usage refusal after the flag is read, a repack
+  refused by its checks — leaves **no** document, never an earlier run's (`BR07`). A
+  compile error is not in it because its message names files by absolute path; its
+  absence is what says no gate ran, and the reason is on stderr.
+- **Where.** Never inside `--out` — that directory holds the build's own files, which
+  `A18` and `emit_hashes` hold byte-identical — and refused by name when it is (`BR06`).
+- **What it never carries.** A time, an absolute path or anything of the machine: two
+  reports of one build are byte-identical, whatever `--out` they were built into
+  (`BR04`).
+- **Versioned and additive.** A field is added under `build-report/1`; a field that
+  changes meaning or goes away moves the spec. A reader checks `spec` first.
+
 ---
 
 ## 6. What rigc will refuse — do not spend a loop on these

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spine-rigc",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "description": "AI-authored Spine 2D rigging and animation, verified before it is written. rigc compiles a rig spec into Spine 4.3 skeleton data, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Output imports into the Spine editor. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/src/assertions/report.ts

@@ -53,12 +53,137 @@ export function reportLines(report: VerdictLists & { profile: AssertionProfile }
   // 42. The four buckets partition `ASSERTION_NAMES`, so the total is derived
   // by adding them rather than stated — a `42` written here would be the one
   // number in the report that no run could contradict.
-  const failed = new Set(report.failures.map((f) => f.assertion));
-  const measured = report.passed.length + failed.size;
-  const total = measured + report.skipped.length + report.profileSkipped.length;
+  //
+  // The figures are `gateSummary`'s, the one computation the line and the
+  // `--report` document (`buildReportGate`) both spell (issue #1213).
+  const s = gateSummary(report);
   lines.push(
-    `  ..    ${total} assertions: ${measured} measured (${report.passed.length} passed, ${failed.size} failed), ` +
-      `${report.skipped.length} skipped, ${report.profileSkipped.length} not in profile "${report.profile}"`,
+    `  ..    ${s.assertions} assertions: ${s.measured} measured (${s.passed} passed, ${s.failed} failed), ` +
+      `${s.skipped} skipped, ${s.notInProfile} not in profile "${s.profile}"`,
   );
   return lines;
 }
+
+/**
+ * The figures the summary line states, as values: what `reportLines` prints
+ * as its last line and what the `--report` document carries as a gate's
+ * `summary` — one computation, so the two cannot disagree. Every figure counts
+ * assertions, not rows (the comment in `reportLines` says why `failed` is a
+ * set), and `assertions` is the sum of the four buckets, never a constant.
+ */
+export interface GateSummary {
+  assertions: number;
+  measured: number;
+  passed: number;
+  failed: number;
+  skipped: number;
+  notInProfile: number;
+  profile: AssertionProfile;
+}
+
+export function gateSummary(report: VerdictLists & { profile: AssertionProfile }): GateSummary {
+  const failed = new Set(report.failures.map((f) => f.assertion)).size;
+  const measured = report.passed.length + failed;
+  return {
+    assertions: measured + report.skipped.length + report.profileSkipped.length,
+    measured,
+    passed: report.passed.length,
+    failed,
+    skipped: report.skipped.length,
+    notInProfile: report.profileSkipped.length,
+    profile: report.profile,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// the build report document (`--report <file>`, issue #1213)
+// ---------------------------------------------------------------------------
+
+/**
+ * The `spec` of the document `build --report` and `repack --report` write.
+ * Versioned and additive: a field is added under the same spec, and one that
+ * changes meaning or goes away moves the spec — a dependant that read `/1`
+ * keeps reading what `/1` promised.
+ */
+export const BUILD_REPORT_SPEC = 'build-report/1';
+
+/** Which supplier judged the gates: the round trip through spine-core (`cli.ts`) or the model side and the rules restated over the emitted text (`cli_core.ts`). */
+export type BuildReportSupplier = 'round-trip' | 'model';
+
+/**
+ * The core entry's `here:` line as values: how many rules ran on the model
+ * side over the document, how many of the round trip's own were restated over
+ * the emitted text, and the codes that did not run. `null` on the round trip,
+ * which prints no such line.
+ */
+export interface GateHere {
+  modelSide: number;
+  restated: number;
+  notRun: string[];
+}
+
+/**
+ * What one gate's report states, as values: the rows a reader takes off the
+ * `PASS`, `SKIP` and `FAIL` lines (the rule names, the SKIP reasons, the FAIL
+ * details, each in the order printed), the summary line's figures, the stats
+ * line's keys and values, and the core entry's `here:` line. A `PROF` row is
+ * counted in `summary.notInProfile` and not listed: nothing reads its row.
+ */
+export interface BuildReportGate {
+  /** `compiled` for the gate over the compile, `packed` for `--pack`'s second gate over the pages on disk. */
+  atlas: 'compiled' | 'packed';
+  passed: string[];
+  skipped: Array<{ code: string; reason: string }>;
+  failures: Array<{ code: string; detail: string }>;
+  summary: GateSummary;
+  stats: Record<string, number | string>;
+  here: GateHere | null;
+}
+
+/**
+ * One `pack:` line as values. `coveredPct` is the figure the line prints, at
+ * its one decimal; `pageEdges` is the `--page-edges` the build packed under,
+ * which the line states as `, page edges free` or by its absence.
+ */
+export interface PackPageFigures {
+  page: string;
+  width: number;
+  height: number;
+  regions: number;
+  coveredPct: number;
+  padding: number;
+  pageEdges: 'pot' | 'free';
+  packShape: 'rect' | 'polygon';
+}
+
+/** The document, keys in the order written. Nothing in it is a time, a path or a machine's: two reports of one build are byte-identical. */
+export interface BuildReportDocument {
+  spec: typeof BUILD_REPORT_SPEC;
+  command: 'build' | 'repack';
+  supplier: BuildReportSupplier;
+  gates: BuildReportGate[];
+  /** Every `pack:` line, in the order printed; `null` for a build that did not pack. */
+  pack: PackPageFigures[] | null;
+}
+
+/** One gate's report as the document carries it — read off the lists `reportLines` prints, so a row is in the document exactly when its line is printed. */
+export function buildReportGate(
+  atlas: BuildReportGate['atlas'],
+  report: VerdictLists & { profile: AssertionProfile },
+  here: GateHere | null,
+): BuildReportGate {
+  return {
+    atlas,
+    passed: [...report.passed],
+    skipped: report.skipped.map((s) => ({ code: s.assertion, reason: s.reason })),
+    failures: report.failures.map((f) => ({ code: f.assertion, detail: f.detail })),
+    summary: gateSummary(report),
+    stats: { ...report.stats },
+    here,
+  };
+}
+
+/** The document's text: two-space JSON and a final newline, keys in the order `BuildReportDocument` states them. */
+export function buildReportText(doc: BuildReportDocument): string {
+  return `${JSON.stringify(doc, null, 2)}\n`;
+}

package/src/cli/core_commands.ts

@@ -1560,6 +1560,7 @@ export function cmdSkills(flags: Record<string, string>, positional: string[]):
  * through this entry's dispatch with a hook between the lift and the build.
  */
 export const MODEL_AND_TEXT_GATE: BuildGate = {
+  supplier: 'model',
   heading: (profile) =>
     `  ..    validate (the model side over the document + the round trip's rules restated over the emitted text, profile ${profile}; this entry links no spine-core, so the round trip does not run)`,
   run: ({ result, atlasText, atlasDir, modelText, reEmit, profile }) => {
@@ -1584,12 +1585,14 @@ export const MODEL_AND_TEXT_GATE: BuildGate = {
     const ran = (r: { passed: string[]; failures: Array<{ assertion: string }>; skipped: Array<{ assertion: string }>; profileSkipped: Array<{ assertion: string }> }): number =>
       new Set([...r.passed, ...r.failures.map((f) => f.assertion), ...r.skipped.map((x) => x.assertion), ...r.profileSkipped.map((x) => x.assertion)]).size;
     const notRun = text.skipped.filter((x) => x.assertion === 'A00_ROUNDTRIP_PARSE').map((x) => x.assertion);
+    // The line is spelled from the values the `--report` document carries as the gate's `here` (issue #1213).
+    const here = { modelSide: ran(model), restated: ran(text) - notRun.length, notRun };
     console.log(
-      `  ..    here: ${ran(model)} rule(s) on the model side over the document, ${ran(text) - notRun.length} of the round trip's own restated over the emitted text; ` +
-        `not run: ${notRun.join(', ') || 'none'} — spine-core's parse, which only the entry that links spine-core runs, on build and validate: ` +
+      `  ..    here: ${here.modelSide} rule(s) on the model side over the document, ${here.restated} of the round trip's own restated over the emitted text; ` +
+        `not run: ${here.notRun.join(', ') || 'none'} — spine-core's parse, which only the entry that links spine-core runs, on build and validate: ` +
         `installed, the same \`rigc\` once @esotericsoftware/spine-core is installed beside the package; from a source checkout, \`bun cli.ts\``,
     );
-    return report.failures.length;
+    return { report, here };
   },
   look: (outDir) => `rigc: look at it: rigc render --candidate ${outDir}`,
 };

package/src/cli/repack.ts

@@ -46,6 +46,7 @@ import { MODEL_DOCUMENT_FILE } from '../model.ts';
 import { atlasRefusals, documentDisagreements, firstLineApart, type InputPage, liftAtlas, polygonOwnedTexels, regionDifferences, REPACK_WORK_PREFIX, RepackError, skeletonDifferences } from '../repack.ts';
 import {
   type BuildGate,
+  type BuildReport,
   type CommandArgs,
   documentStageBeside,
   modelTextBeside,
@@ -54,11 +55,13 @@ import {
   readPackShape,
   readPageEdges,
   readProfile,
+  readReportFlag,
   readSkeletonText,
   readVersion,
   resolveBuild,
   runBuild,
   UsageError,
+  writeBuildReport,
 } from './shared.ts';
 import { DEFAULT_PADDING, DEFAULT_PAGE_SIZE } from '../atlas.ts';
 import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
@@ -75,7 +78,7 @@ import { basename, dirname, join, resolve } from 'node:path';
  */
 export const ACCEPT_FLAG = 'accept-skeleton-differences';
 
-export const REPACK_FLAGS = ['out', 'atlas', 'page-size', 'padding', 'page-edges', 'pack-shape', 'profile', 'stage', 'stage-box', ACCEPT_FLAG] as const;
+export const REPACK_FLAGS = ['out', 'atlas', 'page-size', 'padding', 'page-edges', 'pack-shape', 'profile', 'stage', 'stage-box', ACCEPT_FLAG, 'report'] as const;
 
 /** `build`'s flags that `repack` does not take, and why — each refused by name rather than ignored. */
 const BUILD_FLAGS_REFUSED: Readonly<Record<string, string>> = {
@@ -211,7 +214,7 @@ function findingLines(findings: readonly IngestFinding[]): string[] {
  * `repack` names `--out` itself once it has written there. Every other line is
  * printed as it comes, so a gate that exits mid-way loses none.
  */
-function stagedBuild(flags: Record<string, string>, gate: BuildGate): void {
+function stagedBuild(flags: Record<string, string>, gate: BuildGate, record: BuildReport | null): void {
   const print = console.log;
   console.log = (...args: unknown[]): void => {
     const line = args.map((a) => (typeof a === 'string' ? a : String(a))).join(' ');
@@ -219,7 +222,7 @@ function stagedBuild(flags: Record<string, string>, gate: BuildGate): void {
     else if (!line.startsWith(LOOK_LINE)) print(...args);
   };
   try {
-    runBuild(flags, gate);
+    runBuild(flags, gate, record);
   } finally {
     console.log = print;
   }
@@ -258,6 +261,8 @@ export function cmdRepack({ flags, positional }: CommandArgs, gate: BuildGate, p
   };
   const stage = readStageFlag(flags.stage);
   const out = readOut(flags);
+  // `--report` (issue #1213): refused inside --out, written on a red gate by the build body and here once --out is written.
+  const record = readReportFlag(flags, 'repack', out, gate.supplier);
   const input = resolveBuild(positional[0], flags.atlas);
   if (input.atlas !== 'there') throw new UsageError(input.atlasRefusal);
   const skeletonText = readSkeletonText(input.skeletonPath);
@@ -338,7 +343,7 @@ export function cmdRepack({ flags, positional }: CommandArgs, gate: BuildGate, p
     writeFileSync(motionPath, `${JSON.stringify(result.motion, null, 2)}\n`);
 
     // (c) `build --pack` through the entry's own gate. It returns only green; a red gate exits from inside it.
-    stagedBuild({ rig: rigPath, motion: motionPath, out: buildDir, pack: 'true', ...packing }, gate);
+    stagedBuild({ rig: rigPath, motion: motionPath, out: buildDir, pack: 'true', ...packing }, gate, record);
 
     // (a) and (b), both before the first write.
     const outAtlas = readFileSync(join(buildDir, 'skeleton.atlas'), 'utf8');
@@ -400,6 +405,7 @@ export function cmdRepack({ flags, positional }: CommandArgs, gate: BuildGate, p
       copyFileSync(join(buildDir, name), join(out, name));
       console.log(`rigc: wrote ${join(out, name)}`);
     }
+    if (record !== null) writeBuildReport(record);
     console.log(gate.look(out));
   } finally {
     removeWork();

package/src/cli/shared.ts

@@ -16,7 +16,19 @@
  */
 import { type AtlasRegion, DEFAULT_PACK_SHAPE, DEFAULT_PADDING, DEFAULT_PAGE_EDGES, DEFAULT_PAGE_SIZE, PACK_SHAPES, packAtlas, type PackInput, packFootprints, type PackShape, PAGE_EDGES, type PageEdges, pageFootprint } from '../atlas.ts';
 import { copyAtlasPages, plannedPageCopies } from '../emit.ts';
-import { CLI_DEFAULT_PROFILE, VALIDATE_PROFILES } from '../assertions/report.ts';
+import {
+  BUILD_REPORT_SPEC,
+  type BuildReportDocument,
+  type BuildReportGate,
+  type BuildReportSupplier,
+  buildReportGate,
+  buildReportText,
+  CLI_DEFAULT_PROFILE,
+  type GateHere,
+  type PackPageFigures,
+  VALIDATE_PROFILES,
+} from '../assertions/report.ts';
+import type { VerdictLists } from '../assertions/harness.ts';
 import type { AssertionProfile } from '../assertions/kinds.ts';
 import { MAX_CANDIDATES, MIN_CANDIDATES } from '../ballot.ts';
 import { BONEDIST_SPEC, IDENTITY_CORRESPONDENCE } from '../correspondence.ts';
@@ -48,8 +60,8 @@ import { PoseError } from '../pose.ts';
 import { RepackError } from '../repack.ts';
 import { SpineRuntimeError, SPINE_SIDE_ABSENT } from '../spine_side.ts';
 import type { CompileResult, DroppedState } from '../types.ts';
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import { basename, dirname, join, resolve } from 'node:path';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 
 
 /**
@@ -1113,6 +1125,12 @@ const FLAG_MEANINGS: Record<string, string> = {
     'is the setup-pose bounding box, and the rebuilt spec asks for the same box rather than transcribing it. Only a ' +
     'box `build` could write back is read: anything else in that slot is refused by name, and without the flag no ' +
     'slot is read as the stage because of its name',
+  report:
+    `also write the gate's report as a JSON document (\`${BUILD_REPORT_SPEC}\`) to this file: every gate's PASS, SKIP and FAIL rows, ` +
+    'its summary figures and stats, the supplier that judged it, and every pack line\'s figures — written when the command ' +
+    'writes --out and when a gate is red, before the exit. A file already at the path is removed first, so any other ending ' +
+    '(a compile error, a repack refused) leaves none rather than an earlier run\'s. Never inside --out, refused by name. ' +
+    'The lines printed are the same with it and without it',
   help: "show this command's flags and exit",
 };
 
@@ -1168,6 +1186,7 @@ const FLAG_VALUES: Record<string, string> = {
   stage: '<x,y,w,h>',
   'stage-box': '<slot>',
   dir: '<path>',
+  report: '<file>',
 };
 
 /**
@@ -1261,7 +1280,7 @@ export const COMMANDS: CommandDoc[] = [
       for: 'the gate round-trips every build through it before anything is written',
       core: {
         usage: [
-          'rigc build --rig <path> --motion <path> --out <dir> [--manifest <path>] [--images <dir>] [--profile spine|spine-html] [--copy-images]   (the same files the round-tripped build writes; gated without spine-core — see build --help)',
+          'rigc build --rig <path> --motion <path> --out <dir> [--manifest <path>] [--images <dir>] [--profile spine|spine-html] [--copy-images] [--report <file>]   (the same files the round-tripped build writes; gated without spine-core — see build --help)',
           `rigc build … --pack [--page-size ${DEFAULT_PAGE_SIZE}] [--padding ${DEFAULT_PADDING}] [--page-edges pot|free] [--pack-shape rect|polygon]   (parts onto shared pages, written into --out)`,
           'rigc build … --atlas-in <skeleton.atlas>                    (resolve the parts against a pack somebody already made)',
           'rigc build --cut <name> --cuts <cuts.json>',
@@ -1285,7 +1304,7 @@ export const COMMANDS: CommandDoc[] = [
     },
     spineFormat: true,
     usage: [
-      'rigc build --rig <path> --motion <path> --out <dir> [--manifest <path>] [--images <dir>] [--profile spine|spine-html] [--copy-images]',
+      'rigc build --rig <path> --motion <path> --out <dir> [--manifest <path>] [--images <dir>] [--profile spine|spine-html] [--copy-images] [--report <file>]',
       `rigc build … --pack [--page-size ${DEFAULT_PAGE_SIZE}] [--padding ${DEFAULT_PADDING}] [--page-edges pot|free] [--pack-shape rect|polygon]   (parts onto shared pages, written into --out)`,
       'rigc build … --atlas-in <skeleton.atlas>                    (resolve the parts against a pack somebody already made)',
       'rigc build --cut <name> --cuts <cuts.json>',
@@ -1306,6 +1325,7 @@ export const COMMANDS: CommandDoc[] = [
       'cut',
       'cuts',
       'profile',
+      'report',
     ],
   },
   {
@@ -1314,7 +1334,7 @@ export const COMMANDS: CommandDoc[] = [
       for: 'the rebuild it writes is gated by build\'s gate, which round-trips it through spine-core',
       core: {
         usage: [
-          `rigc repack <dir | skeleton.json> --out <dir> [--atlas <path>] [--page-size ${DEFAULT_PAGE_SIZE}] [--padding ${DEFAULT_PADDING}] [--page-edges pot|free] [--pack-shape rect|polygon] [--profile spine|spine-html] [--stage x,y,w,h] [--stage-box <slot>] [--accept-skeleton-differences]   (gated without spine-core — see repack --help)`,
+          `rigc repack <dir | skeleton.json> --out <dir> [--atlas <path>] [--page-size ${DEFAULT_PAGE_SIZE}] [--padding ${DEFAULT_PADDING}] [--page-edges pot|free] [--pack-shape rect|polygon] [--profile spine|spine-html] [--stage x,y,w,h] [--stage-box <slot>] [--accept-skeleton-differences] [--report <file>]   (gated without spine-core — see repack --help)`,
         ],
         notes: [
           'a packed build repacked from its own output — skeleton.json, skeleton.atlas and the',
@@ -1335,9 +1355,9 @@ export const COMMANDS: CommandDoc[] = [
     },
     spineFormat: true,
     usage: [
-      `rigc repack <dir | skeleton.json> --out <dir> [--atlas <path>] [--page-size ${DEFAULT_PAGE_SIZE}] [--padding ${DEFAULT_PADDING}] [--page-edges pot|free] [--pack-shape rect|polygon] [--profile spine|spine-html] [--stage x,y,w,h] [--stage-box <slot>] [--accept-skeleton-differences]`,
+      `rigc repack <dir | skeleton.json> --out <dir> [--atlas <path>] [--page-size ${DEFAULT_PAGE_SIZE}] [--padding ${DEFAULT_PADDING}] [--page-edges pot|free] [--pack-shape rect|polygon] [--profile spine|spine-html] [--stage x,y,w,h] [--stage-box <slot>] [--accept-skeleton-differences] [--report <file>]`,
     ],
-    flags: ['out', 'atlas', 'page-size', 'padding', 'page-edges', 'pack-shape', 'profile', 'stage', 'stage-box', 'accept-skeleton-differences'],
+    flags: ['out', 'atlas', 'page-size', 'padding', 'page-edges', 'pack-shape', 'profile', 'stage', 'stage-box', 'accept-skeleton-differences', 'report'],
     overrides: {
       out: {
         value: '<dir>',
@@ -2134,16 +2154,20 @@ export interface BuildGateInput {
  * `runBuild`'s, written once, so the two entries write the same build.
  */
 export interface BuildGate {
+  /** Which supplier this gate is, as the `--report` document names it (issue #1213). */
+  supplier: BuildReportSupplier;
   /** The line before the first gate's report, naming what judges it. */
   heading: (profile: AssertionProfile) => string;
-  /** Run the gate, print its report, return the failure count. */
-  run: (input: BuildGateInput) => number;
+  /** Run the gate, print its report, and return the lists it printed — and, on the core entry, its `here:` line's values. */
+  run: (input: BuildGateInput) => { report: VerdictLists & { profile: AssertionProfile }; here: GateHere | null };
   /** The command a green build ends by naming, for its own `--out`. */
   look: (outDir: string) => string;
 }
 
 function runGate(
   gate: BuildGate,
+  record: BuildReport | null,
+  atlasKind: BuildReportGate['atlas'],
   result: CompileResult,
   modelText: string,
   opts: CompileOptions,
@@ -2158,7 +2182,7 @@ function runGate(
   // issue #1016): so the second document is spelled from the second compile's
   // atlas as it would be written, or from the second, independent pack.
   const again = compile(opts);
-  return gate.run({
+  const { report, here } = gate.run({
     result,
     atlasText: atlas ? atlas.text : result.atlasText,
     atlasDir: opts.outDir,
@@ -2166,6 +2190,89 @@ function runGate(
     reEmit: { skeletonText: again.skeletonText, atlasText: atlas ? atlas.again : again.atlasText, modelText: modelDocument(again.model, again.skeletonText, atlas ? atlas.again : written(again.atlasText)) },
     profile,
   });
+  record?.gates.push(buildReportGate(atlasKind, report, here));
+  return report.failures.length;
+}
+
+// ---------------------------------------------------------------------------
+// --report: the build's report as a document (issue #1213)
+// ---------------------------------------------------------------------------
+
+/**
+ * A `--report` in the making: where it goes, and what the run has stated so
+ * far — every gate's lists and every `pack:` line's figures, recorded where
+ * the line is printed and from the values it is printed from. `write` spells
+ * the document (`buildReportText`) and writes it; nothing else in it is read
+ * off the disk, the clock or the machine.
+ */
+export interface BuildReport {
+  path: string;
+  command: BuildReportDocument['command'];
+  supplier: BuildReportSupplier;
+  gates: BuildReportGate[];
+  pack: PackPageFigures[] | null;
+}
+
+/** The document a recorded run states, keys in the order the spec writes them. */
+export function buildReportDocument(record: BuildReport): BuildReportDocument {
+  return { spec: BUILD_REPORT_SPEC, command: record.command, supplier: record.supplier, gates: record.gates, pack: record.pack };
+}
+
+/** Write what the run stated to `--report`. Called when a gate has reached its verdict: before a red gate's exit, after a green build's last write. */
+export function writeBuildReport(record: BuildReport): void {
+  writeFileSync(record.path, buildReportText(buildReportDocument(record)));
+}
+
+/**
+ * `--report <file>` read for a command whose build goes into `outDir`: the
+ * file resolved against the working directory, refused by name when it is
+ * inside `outDir` or is `outDir` — the build's directory holds the files A18
+ * and `emit_hashes` hold byte-identical, and a report there would be a file of
+ * the build that is not the build — and refused when a directory stands at the
+ * path. A file already at the path is removed here, before anything is
+ * compiled, so the file at `--report` is always this run's: a run that reaches
+ * no gate (a usage refusal after this point, a compile error, a repack refused
+ * before or after its gate) leaves no document rather than an earlier run's.
+ * `null` when the flag is absent.
+ */
+export function readReportFlag(flags: Record<string, string>, command: BuildReport['command'], outDir: string, supplier: BuildReportSupplier): BuildReport | null {
+  const raw = flags.report;
+  if (raw === undefined) return null;
+  const path = resolve(raw);
+  const out = resolve(outDir);
+  const within = relative(out, path);
+  if (within === '' || (!within.startsWith('..') && !isAbsolute(within))) {
+    throw new UsageError(
+      `--report ${raw} is inside --out ${outDir}: the report is written beside a build, never into it — --out holds the build's own files, ` +
+        'which A18 and emit_hashes hold byte-identical. Name a path outside --out',
+    );
+  }
+  if (existsSync(path) && statSync(path).isDirectory()) throw new UsageError(`--report ${raw} is a directory; it takes the path of the file to write`);
+  rmSync(path, { force: true });
+  return { path, command, supplier, gates: [], pack: null };
+}
+
+/**
+ * One `pack:` line's figures (issue #1213): what the line prints, as values —
+ * `coveredPct` at the one decimal the line spells, so the document and the
+ * line state the same number.
+ */
+function packPageFigures(page: { name: string; width: number; height: number; occupancy: number }, regions: number, padding: number, pageEdges: PageEdges, packShape: PackShape): PackPageFigures {
+  return { page: page.name, width: page.width, height: page.height, regions, coveredPct: Number((page.occupancy * 100).toFixed(1)), padding, pageEdges, packShape };
+}
+
+/** The `pack:` line, spelled from its figures. */
+function packLine(f: PackPageFigures): string {
+  return (
+    `  ..    pack: ${f.page} ${f.width}x${f.height}, ` +
+    `${f.regions} region(s), ` +
+    `${f.coveredPct.toFixed(1)}% covered, padding ${f.padding}` +
+    (f.pageEdges === 'free' ? ', page edges free' : '') +
+    // Appended, never inserted: a reader that takes the line whole keeps
+    // every field it read before #1099, and the mode is named under the
+    // default too, so no reader infers it from an absent word.
+    `, shape ${f.packShape}`
+  );
 }
 
 /**
@@ -2239,8 +2346,13 @@ function printHeaderBox(result: CompileResult): void {
  * for its gate, which the entry hands in (`BuildGate`): both entries write
  * the Spine pair, the model document and the pages by this one body.
  */
-export function runBuild(flags: Record<string, string>, gate: BuildGate): void {
+export function runBuild(flags: Record<string, string>, gate: BuildGate, caller: BuildReport | null = null): void {
   const { label, opts, profile, packing } = readBuildInvocation(flags);
+  // `--report` (issue #1213): `build`'s own, written by this body on either verdict — or the caller's
+  // (`repack`'s), which this body writes on a red gate, since the exit leaves the caller no turn, and which the
+  // caller writes when it has written its own output.
+  const own = caller === null ? readReportFlag(flags, 'build', opts.outDir, gate.supplier) : null;
+  const record = caller ?? own;
   printBuildHeader(label, opts);
   const result = compile(opts);
   printCompiled(opts, result);
@@ -2258,8 +2370,9 @@ export function runBuild(flags: Record<string, string>, gate: BuildGate): void {
   const writtenAtlas = (atlasText: string): string => (copying ? plannedPageCopies(atlasText, opts.outDir).atlasText : atlasText);
   let modelText = modelDocument(result.model, result.skeletonText, writtenAtlas(result.atlasText));
   console.log(gate.heading(profile));
-  const failures = runGate(gate, result, modelText, opts, profile, writtenAtlas);
+  const failures = runGate(gate, record, 'compiled', result, modelText, opts, profile, writtenAtlas);
   if (failures > 0) {
+    if (record !== null) writeBuildReport(record);
     console.error(`rigc: ${failures} assertion(s) failed — nothing written`);
     process.exit(1);
   }
@@ -2308,18 +2421,12 @@ export function runBuild(flags: Record<string, string>, gate: BuildGate): void {
     };
     const packed = packAtlas(packInputs(result, packOpts.shape), packOpts);
     atlasText = packed.atlasText;
+    if (record !== null) record.pack = [];
     for (const page of packed.pages) {
       page.plate.writePng(join(opts.outDir, page.name));
-      console.log(
-        `  ..    pack: ${page.name} ${page.width}x${page.height}, ` +
-          `${packed.placements.filter((p) => packed.pages[p.page].name === page.name).length} region(s), ` +
-          `${(page.occupancy * 100).toFixed(1)}% covered, padding ${packed.padding}` +
-          (packOpts.pageEdges === 'free' ? ', page edges free' : '') +
-          // Appended, never inserted: a reader that takes the line whole keeps
-          // every field it read before #1099, and the mode is named under the
-          // default too, so no reader infers it from an absent word.
-          `, shape ${packed.shape}`,
-      );
+      const figures = packPageFigures(page, packed.placements.filter((p) => packed.pages[p.page].name === page.name).length, packed.padding, packOpts.pageEdges, packed.shape);
+      record?.pack?.push(figures);
+      console.log(packLine(figures));
     }
     for (const place of packed.placements) {
       console.log(
@@ -2337,8 +2444,9 @@ export function runBuild(flags: Record<string, string>, gate: BuildGate): void {
     // The document written is spelled from the packed atlas, and this gate's A18 compares it with a
     // second compile's spelled from the second, independent pack (issue #1016).
     modelText = modelDocument(result.model, result.skeletonText, atlasText);
-    const packFailures = runGate(gate, result, modelText, opts, profile, (text) => text, { text: atlasText, again: packAgain.atlasText });
+    const packFailures = runGate(gate, record, 'packed', result, modelText, opts, profile, (text) => text, { text: atlasText, again: packAgain.atlasText });
     if (packFailures > 0) {
+      if (record !== null) writeBuildReport(record);
       console.error(
         `rigc: ${packFailures} assertion(s) failed on the PACKED atlas — the pages were written to ` +
           `${opts.outDir}, the skeleton/atlas pair was not`,
@@ -2357,6 +2465,8 @@ export function runBuild(flags: Record<string, string>, gate: BuildGate): void {
   console.log(`rigc: wrote ${join(opts.outDir, 'skeleton.json')}`);
   console.log(`rigc: wrote ${join(opts.outDir, 'skeleton.atlas')}`);
   console.log(`rigc: wrote ${join(opts.outDir, MODEL_DOCUMENT_FILE)}`);
+  // Written after the build, and printed nowhere: the lines a build prints are the same with the flag and without it.
+  if (own !== null) writeBuildReport(own);
   // The next command is part of the message (issue #837). A green build is the
   // moment somebody wants to see what came out, and the one page rigc writes
   // for that is `preview` of exactly this directory — so the line names it,

package/src/cli/spine_commands.ts

@@ -41,6 +41,7 @@ function repositoryUrl(): string {
  * with the arguments it has always been handed, and the same lines.
  */
 const ROUND_TRIP_GATE: BuildGate = {
+  supplier: 'round-trip',
   heading: (profile) => `  ..    validate (spine-core round trip + machine assertions, profile ${profile})`,
   run: ({ result, atlasText, atlasDir, modelText, reEmit, profile }) => {
     const report = validate({
@@ -59,7 +60,7 @@ const ROUND_TRIP_GATE: BuildGate = {
         .map(([k, v]) => `${k}=${v}`)
         .join(' ')}`,
     );
-    return report.failures.length;
+    return { report, here: null };
   },
   look: (outDir) => `rigc: look at it: rigc preview --candidate ${outDir}`,
 };