spine-rigc 0.25.5 → 0.26.0

package/README.md

@@ -413,8 +413,11 @@ that does not belong to it. See
   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.
+  already looked at, so what it measures is **what your edit did**. Every drift
+  the report prints carries the bound its own match gives it on the line under
+  it, so a figure is read against that rather than against a number from a page;
+  AUTHORING.md §9.2 says what the two halves of that bound are and why the floor
+  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.
@@ -530,9 +533,9 @@ first three work on any reference you have, and `bench` is a repository workflow
 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
+`build` and `validate` both default to `--profile spine` — the 29 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
+adds all 44: the other 15 are one renderer's policy and one canvas budget's, and they
 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
@@ -584,7 +587,7 @@ what each is worth.
 **What it reads is skeleton JSON and nothing else** — no `.spine` project, no binary
 `.skel`, no atlas, no art. So it never invents, and the things it cannot get out of
 the file are **findings** with codes rather than plausible values: a construct the
-spec format cannot hold (`linkedmesh`, `point`, a `sequence` block, an unknown field
+spec format cannot hold (`point`, a `sequence` block, an unknown field
 on a bone, slot or constraint) is a blocker, the command exits non-zero, and both
 specs are still written — a spec plus a list of what is missing from it beats no spec.
 One thing it drops on purpose and says so: a path attachment's `lengths`, which is
@@ -678,7 +681,7 @@ letting `A17` blame the editor for the harness's own doing.
 | 📥 **[docs/INGEST.md](docs/INGEST.md)** | **working with a skeleton you did not author.** What every command can and cannot do with a foreign `skeleton.json`, reading it with the toolchain, transcription as the route that makes it yours, what each validator complaint means on an export, and the re-pivot/rename/extend recipes. Ships in the package too |
 | 🤖 **[docs/PROMPTING.md](docs/PROMPTING.md)** | **handing the authoring to an AI agent** — the prompt clauses a measured pilot run paid for, and what you can leave unsaid. Ships in the package too |
 | 🔬 **[docs/SPEC_COVERAGE.md](docs/SPEC_COVERAGE.md)** | Spine 4.3's full export surface against what rigc emits and what the official examples measurably use, with the ordered gap list |
-| 🎓 **[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 |
+| 🎓 **[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 44 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 |
@@ -735,7 +738,7 @@ quality."* All six, with their verdicts, are in
 [docs/LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md).
 
 The whole dossier — the yardstick, `diff` and `check` and what neither of them can
-see, every rung, the run viewer, the 43 assertions and the selftest behind them — is
+see, every rung, the run viewer, the 44 assertions and the selftest behind them — is
 [docs/BENCHMARK.md](https://github.com/firejune/rigc/blob/main/docs/BENCHMARK.md).
 Live rung status is
 [docs/LADDER.md](https://github.com/firejune/rigc/blob/main/docs/LADDER.md).

package/cli.ts

@@ -67,9 +67,9 @@ import {
   type DeformSpan,
 } from './src/deformmeasure.ts';
 import { diffLines, diffSkeletons, reportedFigures, sectionFigures, type DiffReport } from './src/diff.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 { ingest, IngestError, IngestSpecRefused, INGEST_GUTTERS, type IngestFinding, type IngestStage } from './src/ingest.ts';
+import { copyAtlasPages } from './src/emit.ts';
+import { DEFAULT_PADDING, DEFAULT_PAGE_SIZE, packAtlas, parseAtlasText } from './src/atlas.ts';
 import { parseJsonWithPosition } from './src/json-position.ts';
 import { KEY_TIME_EPSILON } from './src/timelines.ts';
 import { findRung, RUNG_IDS, type RungSkeleton } from './src/ladder.ts';
@@ -117,6 +117,7 @@ import {
 } from './src/render.ts';
 import {
   assertionCountForProfile,
+  attachmentRegionJoins,
   CLI_DEFAULT_PROFILE,
   reportLines,
   validate,
@@ -148,6 +149,14 @@ export type CutTable = Record<string, CutEntry>;
 
 class UsageError extends Error {}
 
+/**
+ * `explain` refusing a pair it cannot pose — a usage error in kind, printed
+ * without the usage block for `PoseError`'s and `IngestError`'s reason: the
+ * message names an attachment, a region and two flags, and reprinting every
+ * command's usage under it buries the one line that says what to change.
+ */
+class ExplainError extends Error {}
+
 // ---------------------------------------------------------------------------
 // package metadata — the installed version and repository, for `--version`
 // and for naming a remedy `bench` can only give from a repo checkout.
@@ -1242,14 +1251,21 @@ function cmdBuild(flags: Record<string, string>): void {
   // correct for a build sitting beside the project it came from and breaks the
   // moment the directory is zipped, committed or moved on its own (issue #217).
   // Opt-in only: the default stays exactly what it has always been.
+  //
+  // What is copied is what the ATLAS names, not what the image list holds: under
+  // `--atlas-in` the two are different lists, and rebuilding the text from the
+  // second wrote a file the pack never contained — zero bytes for a rig that
+  // declares no parts, one fabricated page per part for a rig that does, both of
+  // them green here because the gate above had already read the compile's own
+  // text (issue #693, `src/emit.ts`).
   let atlasText = result.atlasText;
   if (flags['copy-images'] !== undefined) {
-    const copied = copyAtlasImages(result.images, opts.outDir);
+    const copied = copyAtlasPages(atlasText, opts.outDir);
     atlasText = copied.atlasText;
     console.log(`  ..    copy-images: ${copied.pages.length} page(s) copied into ${opts.outDir}`);
     for (const p of copied.pages) {
-      const note = p.to === basename(p.from) ? '' : `  (renamed from ${basename(p.from)} — basename collision)`;
-      console.log(`  ..      ${p.region.padEnd(24)} <- ${p.to}${note}`);
+      const note = p.to === basename(p.from) ? '' : '  (renamed — basename collision)';
+      console.log(`  ..      ${p.to.padEnd(24)} <- ${p.from}  (${p.regions} region(s))${note}`);
     }
   }
 
@@ -2434,6 +2450,81 @@ function cmdBoneDist(flags: Record<string, string>): void {
   if (flags.json !== undefined) writeJson(flags.json, report);
 }
 
+/**
+ * Refuse a compiled pair whose art `explain` cannot pose through, by name.
+ *
+ * 🚨 `explain` poses the rig — `deformReportLines` loads the emitted pair through
+ * `spine-core` to measure what each deform key did — and a pose resolves EVERY
+ * attachment against the atlas, whether or not anything deforms it. On the specs
+ * `ingest --art none` writes there is nothing to resolve against: the entries
+ * state a size and name no `image`, so the compile atlases nothing, and the load
+ * threw the runtime's own `Region not found in atlas: rear-upper-arm (attachment:
+ * rear-upper-arm)` with a spine-core stack trace under it and exit 1 (measured on
+ * `examples/spineboy/export/spineboy-ess.json`, issue #697). That is the tool
+ * telling an agent about its own internals instead of about the rig, on the one
+ * input `docs/INGEST.md` §2.0 documents as the route through a foreign skeleton.
+ *
+ * ⭐ Both halves of the join are rigc's own readers rather than a second opinion
+ * on somebody else's format: the walk is `attachmentRegionJoins`, which `PS127`
+ * measures against the loader's own `findRegion` calls, and the region names come
+ * from `parseAtlasText`, which is what `--atlas-in` already resolves against.
+ * Names are compared EXACTLY — as `A08` compares them and as `findRegion`
+ * matches them — so a padded region name is a miss on both sides.
+ *
+ * ⚠️ What it deliberately does not do is catch the pose. A blanket `try` around
+ * `skeletonDataFromText` would convert any exception the runtime raises into a
+ * sentence claiming the cause is missing art, and a rigc defect reported under
+ * somebody else's name is the doctrine's second bullet inverted. This refuses
+ * the case it can NAME, before a line of the report is printed, and leaves
+ * anything else to arrive as itself.
+ */
+function refuseUnposableArt(result: CompileResult, opts: CompileOptions): void {
+  const regionNames = parseAtlasText(result.atlasText).pages.flatMap((page) => page.regions.map((region) => region.name));
+  const have = new Set(regionNames);
+  const misses: Array<{ at: string; attachment: string; lookup: string }> = [];
+  let lookups = 0;
+  for (const join of attachmentRegionJoins(JSON.parse(result.skeletonText))) {
+    // A `sequence` this walk will not guess at names no region it can check, and
+    // `A08` passes over it for the same reason.
+    if (join.lookups === null) continue;
+    for (const lookup of join.lookups) {
+      lookups++;
+      if (!have.has(lookup)) {
+        misses.push({
+          at: `skin "${join.skin}" slot "${join.slot}" placeholder "${join.placeholder}"`,
+          attachment: join.name,
+          lookup,
+        });
+      }
+    }
+  }
+  if (misses.length === 0) return;
+  const first = misses[0];
+  // Reported because it was measured, and absent where there is none — `A08`'s
+  // own near-miss clause, in `A08`'s own words.
+  const near = regionNames.find((region) => region.trim().toLowerCase() === first.lookup.toLowerCase());
+  const has =
+    regionNames.length === 0
+      ? 'it declares no region at all'
+      : `it declares ${regionNames.length} region(s) and none of them is that${
+          near === undefined ? '' : `, though it does have ${JSON.stringify(near)}`
+        }`;
+  const remedy =
+    opts.atlasInPath === undefined
+      ? 'Art reaches a compile two ways and this run took neither: `--atlas-in <pack.atlas>` resolves the parts ' +
+        'against a pack somebody already made, and an "image" per attachment resolves them as loose PNGs under ' +
+        '`--images <dir>` — a spec that states a size and names no image is what `ingest --art none` writes, and ' +
+        '`--atlas-in` is what reads it'
+      : `Either the spec's region name or ${opts.atlasInPath} is the one that moved: fix the name, or point ` +
+        '`--atlas-in` at the pack that has it';
+  throw new ExplainError(
+    `${first.at}: attachment ${JSON.stringify(first.attachment)} wants region ${JSON.stringify(first.lookup)}, ` +
+      `which this build's atlas does not have (${has}). \`explain\` poses the rig to measure its deform keys and a ` +
+      `pose resolves every attachment against the atlas, so there is nothing to pose it against. ${remedy}. ` +
+      `${misses.length} of ${lookups} attachment lookup(s) here resolve to no region.`,
+  );
+}
+
 function cmdExplain(flags: Record<string, string>): void {
   const { label, opts } = resolveCut(flags);
   console.log(`rigc explain ${label}`);
@@ -2442,6 +2533,13 @@ function cmdExplain(flags: Record<string, string>): void {
   console.log(`  ..    rig    ${opts.rigPath}`);
   console.log(`  ..    motion ${opts.motionPath}`);
   const result = compile(opts);
+  // Before a line of the report, rather than at the pose two hundred lines in:
+  // the blocks that need the art — DEFORM, meshes, dropped states — all sit
+  // BELOW the pose, so a run that printed the bone and timeline dump and then
+  // refused would be a report missing everything the missing art decides, with
+  // the sentence saying so scrolled off the top. It is the invocation that has
+  // to change, so it is refused before the report it cannot finish (issue #697).
+  refuseUnposableArt(result, opts);
   // `compile` has already parsed this file, so the read below cannot fail — but
   // it goes through the same parser rather than a cast, because the cast was the
   // last one in the repository and issue #307 was about exactly that.
@@ -2825,14 +2923,30 @@ function cmdIngest(flags: Record<string, string>, positional: string[]): void {
   console.log(`  ..    art  ${art}`);
   if (specImages !== undefined) console.log(`  ..    images ${specImages}  (the rig spec's own, from ${outDir})`);
 
-  const result = ingest(readJsonFile(skeletonPath), {
-    name: flags.name ?? basename(skeletonPath, '.json'),
-    art,
-    images: specImages,
-    stage,
-    source: basename(skeletonPath),
-    version: readVersion(),
-  });
+  /**
+   * What the run has to report, however the parse went.
+   *
+   * 🔒 A spec the tree's own parser refuses is a **finding**, not an escape
+   * (issue #692): the three files are written, the coded `BLOCK` line is
+   * printed, and the exit code comes off the findings like every other run's.
+   * The two specs are read as `unknown` because that is all this function does
+   * with them — `JSON.stringify` — and a cast to `RigSpec` here would be this
+   * file claiming a parse that did not happen.
+   */
+  let result: { rig: unknown; motion: unknown; findings: IngestFinding[] };
+  try {
+    result = ingest(readJsonFile(skeletonPath), {
+      name: flags.name ?? basename(skeletonPath, '.json'),
+      art,
+      images: specImages,
+      stage,
+      source: basename(skeletonPath),
+      version: readVersion(),
+    });
+  } catch (err) {
+    if (!(err instanceof IngestSpecRefused)) throw err;
+    result = { rig: err.rig, motion: err.motion, findings: err.findings };
+  }
 
   mkdirSync(outDir, { recursive: true });
   // Indent 2, which is what `compile` writes the skeleton with. One emitter
@@ -3108,8 +3222,20 @@ const COMMANDS: CommandDoc[] = [
   },
   {
     name: 'explain',
-    usage: ['rigc explain  (same arguments as build, minus --profile — it never gates)'],
-    flags: ['rig', 'motion', 'out', 'manifest', 'images', 'cut', 'cuts'],
+    usage: [
+      'rigc explain --rig <path> --motion <path> --out <dir> [--manifest <path>] [--images <dir>]   (it never gates, and writes nothing)',
+      'rigc explain … --atlas-in <skeleton.atlas>                  (resolve the parts against a pack somebody already made, as build does)',
+      'rigc explain --cut <name> --cuts <cuts.json>',
+    ],
+    flags: ['rig', 'motion', 'out', 'manifest', 'images', 'atlas-in', 'cut', 'cuts'],
+    notes: [
+      'this line said "the same arguments as build, minus --profile" and was false in both',
+      'directions (issue #697): --atlas-in was not listed here, so the one flag that lets this',
+      'command read what `ingest --art none` writes was reachable and undocumented, while',
+      '--pack, --page-size, --padding and --copy-images are build\'s and do nothing here —',
+      'they decide what is WRITTEN, and this command writes nothing. What it takes is listed',
+      'above, and that is now the whole of it.',
+    ],
   },
   {
     name: 'validate',
@@ -3482,6 +3608,13 @@ try {
     console.error(`rigc pose: ${err.message}`);
     process.exit(2);
   }
+  // A refusal of the invocation, like the two below it, and exit 2 for the same
+  // reason: nothing was posed and nothing was written, so it is the command line
+  // that has to change (issue #697).
+  if (err instanceof ExplainError) {
+    console.error(`rigc explain: ${err.message}`);
+    process.exit(2);
+  }
   // Same kind as a PoseError, and printed the same way for the same reason: the
   // messages name a path, a bone or an attachment, and reprinting the whole
   // usage under them buries the one line that says what to change.