spine-rigc 0.25.4 → 0.25.5

package/README.md

@@ -146,15 +146,17 @@ because they are written from a clone of this repository (`bun install`, then ru
 the CLI in place); the two are interchangeable — `rigc build …` is
 `bun cli.ts build …`.
 
-Two commands are repository workflows rather than package ones: `bench` and
-`check` measure against Spine's official example projects — fetched, never
-committed — and against reference frames this project renders from them, which
-**are** committed, each example's own `license.txt` beside them under the
-redistribution grant those files carry; the images stay **non-commercial only**.
-The reasoning is in
+One command is a repository workflow rather than a package one: `bench` measures
+against Spine's official example projects — fetched, never committed — and against
+reference frames this project renders from them, which **are** committed, each
+example's own `license.txt` beside them under the redistribution grant those files
+carry; the images stay **non-commercial only**. The reasoning is in
 [`bench/reference/README.md`](https://github.com/firejune/rigc/blob/main/bench/reference/README.md)
-and the terms in [NOTICE.md](NOTICE.md). Both commands need a clone and `bun run
-fetch-examples`, and say so by name when the corpus is absent.
+and the terms in [NOTICE.md](NOTICE.md). It needs a clone and `bun run
+fetch-examples`, and says so by name when the corpus is absent. `check` is not one
+of them: it reads whatever frames you point it at, so it runs from the installed
+package on pictures of your own — which is what *Where to go next* below tells you
+to do with it, and it is the one instrument here that can see a wrong animation.
 
 ### Install it into your agent
 
@@ -405,6 +407,14 @@ that does not belong to it. See
   could. If you have reference pictures of the shot,
   `rigc check --candidate spine --frames <dir>` is the half of the loop that can
   see a wrong animation — AUTHORING.md §9.
+- 🧭 **No reference pictures, because the rig is your own?** Then make them:
+  `rigc render` the first build you are happy with and keep those frames. Every
+  later build is checked against them, and the first such check — the same build
+  against frames of itself — is the floor the rest are read against, because
+  `check` grades nothing and has no pass mark. It is the same instrument and the
+  same commands; what changes is that the reference is a build of yours you have
+  already looked at, so what it measures is **what your edit did**. AUTHORING.md
+  §9.2 says what that floor reads and why it is not zero.
 - [docs/LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md) is the benchmark: the same job, from a brief
   and rendered frames, scored. [docs/PILOT.md](https://github.com/firejune/rigc/blob/main/docs/PILOT.md) is how to run an
   agent through it and score what comes back.
@@ -511,19 +521,24 @@ commands take it and what its default is.
 | `pose --images <dir> --frame <png>` | reads part placements **out of** a picture |
 | `chainfit --candidate <dir> --images <dir> --frame <png>` | reads the parts `pose` refuses, through the candidate's own draw order and hierarchy: masked residuals over **visible** pixels, one hinge per child instead of four degrees of freedom, and the `rotate` key value each answer implies. A bone with two or more anchored descendants is **determined** rather than searched, and the residual that over-determination leaves is reported |
 | `diff <candidate.json> <reference.json>` | structural comparison of two skeletons, one ratio per measure and deliberately no combined score |
+| `bonedist --candidate … --reference … --bones …` | per-frame, per-bone world-transform distance against another skeleton — the ladder's stage 3, run on its own. `--bones <correspondence.json \| identity>` is required rather than defaulted: a candidate is entitled to its own bone names, so the pairing is stated |
 | `check --candidate <dir> --frames <dir>` | the candidate against reference pictures — the only instrument here that can see a *wrong animation* |
 | `bench <rung> --candidate <dir>` | one rung of the benchmark ladder |
 
-`diff`, `check` and `bench` measure against something you were given; the first two
-work on any frames you have, and `bench` is a repository workflow that needs a clone
-and `bun run fetch-examples`. The reasoning behind all three is in
+`diff`, `bonedist`, `check` and `bench` measure against something you were given; the
+first three work on any reference you have, and `bench` is a repository workflow that needs a clone
+and `bun run fetch-examples`. The reasoning behind them is in
 [the benchmark dossier](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md).
 
 `build` and `validate` both default to `--profile spine` — the 28 validity rules, which
 ask *is this valid Spine 4.3 that any runtime plays correctly?* `--profile spine-html`
 adds all 43: the other 15 are one renderer's policy and one canvas budget's, and they
-fire on perfectly correct editor-produced Spine data, so reach for that profile when
-you are shipping into *that* project rather than to be thorough. A report always names
+fire on perfectly correct editor-produced Spine data, which is why they are opt-in.
+⇒ **That reason is about foreign data and does not carry to a rig you are authoring
+yourself: author under `--profile spine-html` and read the extra 15 as findings, and
+gate the release under `--profile spine`.** A `deform` key that folds a mesh inside
+out is written out under the default and refused by name under `spine-html`, which
+is the shape of what that split buys you. A report always names
 the profile it ran and lists what that profile left out.
 
 Several cuts can also be registered in a `cuts.json` and built by name
@@ -666,6 +681,7 @@ letting `A17` blame the editor for the harness's own doing.
 | 🎓 **[the benchmark dossier](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md)** | **why you can trust the output.** The yardstick, `diff` and `check` and what neither can see, the eight-rung ladder and the spineboy graduation exam, the run viewer, the 43 named assertions with their profiles, and the selftest that has watched every one of them fire. Repository material — it is not in the npm package |
 | 📋 [LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md) · [GATE.md](https://github.com/firejune/rigc/blob/main/docs/GATE.md) · [PILOT.md](https://github.com/firejune/rigc/blob/main/docs/PILOT.md) | the live rung ledger, the clause statements a candidate is graded against, and how to run an agent through the ladder and score what comes back |
 | 🗺️ [ROADMAP.md](https://github.com/firejune/rigc/blob/main/ROADMAP.md) | where this is going, and where it has been. What 1.0 has to mean before the number is claimed — conditions rather than a feature list, because direction here comes from what users hit |
+| 📐 [CLAUDE.md](https://github.com/firejune/rigc/blob/main/CLAUDE.md) | **the doctrine** — why the validator's messages are the product, why nothing reaches disk before green, why no number is ever invented, and what a change has to keep. [CONTRIBUTING.md](https://github.com/firejune/rigc/blob/main/CONTRIBUTING.md) calls it worth ten minutes before a first patch. Repository material |
 
 ## Why you can trust the output
 

package/cli.ts

@@ -57,7 +57,7 @@ import {
   type BoneDistReport,
 } from './src/bonedist.ts';
 import { checkAgainstFrames, checkLines, CheckError, type CheckOptions, type CheckReport } from './src/check.ts';
-import { compile, CompileError, relativeImagesPath, type CompileOptions } from './src/compile.ts';
+import { compile, CompileError, droppedStateReason, relativeImagesPath, type CompileOptions } from './src/compile.ts';
 import {
   skeletonDataFromText,
   surveyDeformKeys,
@@ -67,7 +67,7 @@ import {
   type DeformSpan,
 } from './src/deformmeasure.ts';
 import { diffLines, diffSkeletons, reportedFigures, sectionFigures, type DiffReport } from './src/diff.ts';
-import { ingest, IngestError, type IngestFindingKind, type IngestStage } from './src/ingest.ts';
+import { ingest, IngestError, INGEST_GUTTERS, type IngestStage } from './src/ingest.ts';
 import { copyAtlasImages } from './src/emit.ts';
 import { DEFAULT_PADDING, DEFAULT_PAGE_SIZE, packAtlas } from './src/atlas.ts';
 import { parseJsonWithPosition } from './src/json-position.ts';
@@ -125,7 +125,7 @@ import {
 } from './src/validate.ts';
 import { parseMotionSpec } from './src/motion.ts';
 import { depthStepLevels, type FoldLimit, type TurnCeiling } from './src/depth.ts';
-import type { CompileResult } from './src/types.ts';
+import type { CompileResult, DroppedState } from './src/types.ts';
 
 /**
  * One entry of a cuts.json, every path relative to the cuts.json file.
@@ -1133,6 +1133,19 @@ function readIntFlag(flags: Record<string, string>, name: string, fallback: numb
   return Number(raw);
 }
 
+/**
+ * One `DROP` line, written once because two outcomes print it.
+ *
+ * A build that succeeds prints it in its report; a build that REFUSES prints it
+ * under the refusal (issue #671), and the two have to be the same line or the
+ * failing run would be quoting a different fact from the one the green run
+ * shows. What it names — a file or a region — is `droppedStateReason`'s, in the
+ * compiler, beside the code that decided which of the two was consulted.
+ */
+function dropLine(dropped: DroppedState): string {
+  return `  DROP  ${dropped.slot}/${dropped.state}: ${droppedStateReason(dropped)} (state not emitted)`;
+}
+
 function cmdBuild(flags: Record<string, string>): void {
   const { label, opts } = resolveCut(flags);
   const profile = readProfile(flags);
@@ -1195,9 +1208,7 @@ function cmdBuild(flags: Record<string, string>): void {
             : ` scale ${img.atlasScale} (${img.atlas.originalWidth}x${img.atlas.originalHeight} texels)`);
     console.log(`  ..      ${img.region.padEnd(24)} ${img.width}x${img.height}  <- ${where}`);
   }
-  for (const d of result.droppedStates) {
-    console.log(`  DROP  ${d.slot}/${d.state}: ${d.why ?? `no PNG at ${d.path}`} (state not emitted)`);
-  }
+  for (const d of result.droppedStates) console.log(dropLine(d));
   // "The optional slots are optional" is a claim about this code path, so this
   // code path says which ones it left out rather than being silently right.
   for (const a of result.absentParts) {
@@ -2720,8 +2731,12 @@ function cmdExplain(flags: Record<string, string>): void {
   }
 
   if (result.droppedStates.length) {
-    console.log('\ndropped states (listed in the manifest, no PNG on disk)');
-    for (const d of result.droppedStates) console.log(`  ${d.slot}/${d.state}  ${d.path}`);
+    // The heading said "no PNG on disk" and the line printed the path, on a
+    // command that takes `--atlas-in` like `build` does — so an explain of a
+    // pack build named a file it never opened. Same renderer as the other two
+    // printers now, for the same reason they share one (issue #671).
+    console.log('\ndropped states (listed in the manifest, no art behind them)');
+    for (const d of result.droppedStates) console.log(`  ${d.slot}/${d.state}  ${droppedStateReason(d)}`);
   }
 
   console.log('\nmix table (player config, not skeleton JSON)');
@@ -2829,10 +2844,13 @@ function cmdIngest(flags: Record<string, string>, positional: string[]): void {
   // Grouped by kind rather than printed in discovery order: a blocker is what
   // decides the exit code, and a reader scanning for one should not have to
   // read past a hundred DURATION lines to find it.
-  const GUTTER: Record<IngestFindingKind, string> = { blocker: 'BLOCK', judgement: 'JUDGE', lossy: 'LOSS ' };
+  // The gutter words are `INGEST_GUTTERS`, which is also the column
+  // `docs/INGEST.md` §2.0's finding-code table is keyed on (issue #675); the
+  // pad to one width is this printer's, so the codes line up.
+  const width = Math.max(...Object.values(INGEST_GUTTERS).map((gutter) => gutter.length));
   for (const kind of ['blocker', 'judgement', 'lossy'] as const) {
     for (const finding of result.findings.filter((f) => f.kind === kind)) {
-      console.log(`  ${GUTTER[kind]} ${finding.code}: ${finding.where} — ${finding.detail}`);
+      console.log(`  ${INGEST_GUTTERS[kind].padEnd(width)} ${finding.code}: ${finding.where} — ${finding.detail}`);
     }
   }
   console.log(`rigc: wrote ${join(outDir, 'rig.json')}`);
@@ -3049,6 +3067,18 @@ interface CommandDoc {
    * nine, and nothing had ever compared the two.
    */
   overrides?: Record<string, { value?: string; meaning?: string }>;
+  /**
+   * Lines printed under the flag table: what this command's own figures mean.
+   *
+   * ⚠️ Not a second place to describe a flag. It exists for what is true of the
+   * **command** and of no flag it takes — and the case that earned it is issue
+   * #678: `pose` and `chainfit` each say *"it is a reporting threshold, not a
+   * pass bar"* on the flag that carries their threshold, and `check` has no such
+   * flag, so its page said nothing at all about whether any of its figures is a
+   * bar to beat. An agent reading `slot drift worst 3.7 px` off a correct rig had
+   * no page to consult and no exit code to read it in.
+   */
+  notes?: string[];
 }
 
 const COMMANDS: CommandDoc[] = [
@@ -3126,6 +3156,19 @@ const COMMANDS: CommandDoc[] = [
           'REFUSED by name, and one that records none says so in the report rather than pretending to agree',
       },
     },
+    notes: [
+      'every figure here is a reporting threshold, not a pass bar. Nothing in this report',
+      'grades, no number has to beat anything, and the exit code says only whether the',
+      'comparison could be MADE: 0 when it ran — including the build with every easing',
+      'reversed, which is the defect this command exists for — 1 when it could not (frames',
+      'that are not there, a skin the frames do not record, a candidate that will not load),',
+      '2 on the flags.',
+      '',
+      'So read a figure against a floor you measured yourself: render the first green build',
+      'and keep its frames, then check every later build against them. The identity run of',
+      'that pair is the floor, and it is not zero — docs/AUTHORING.md §9.2 states it, what',
+      'it comes from, and which column separates a wrong curve from a moved key.',
+    ],
   },
   {
     name: 'bench',
@@ -3267,9 +3310,14 @@ function commandHelp(name: string): string {
   const meaning = (key: string): string => doc.overrides?.[key]?.meaning ?? FLAG_MEANINGS[key];
   const labels = keys.map((key) => `--${key}${value(key) ? ` ${value(key)}` : ''}`);
   const width = Math.max(...labels.map((l) => l.length)) + 2;
-  return ['usage:', ...doc.usage.map((u) => `  ${u}`), '', 'flags:', ...keys.map((key, i) => `  ${labels[i].padEnd(width)}${meaning(key)}`)].join(
-    '\n',
-  );
+  return [
+    'usage:',
+    ...doc.usage.map((u) => `  ${u}`),
+    '',
+    'flags:',
+    ...keys.map((key, i) => `  ${labels[i].padEnd(width)}${meaning(key)}`),
+    ...(doc.notes === undefined ? [] : ['', ...doc.notes]),
+  ].join('\n');
 }
 
 const USAGE = [
@@ -3410,6 +3458,13 @@ try {
   }
   if (err instanceof CompileError) {
     console.error(`rigc compile error: ${err.message}`);
+    // The drops the compile recorded before it stopped, in the same line the
+    // green build prints (issue #671). They were reported from the compile
+    // RESULT alone, so the run that failed BECAUSE a file was missing was the
+    // one run that never named the file. On stderr with the refusal rather than
+    // on stdout, so redirecting one stream does not separate a fact from the
+    // sentence it explains.
+    for (const dropped of err.droppedStates ?? []) console.error(dropLine(dropped));
     process.exit(1);
   }
   if (err instanceof CheckError) {