spine-rigc 0.23.0 → 0.25.0

package/README.md

@@ -503,7 +503,7 @@ commands take it and what its default is.
 | `build … --pack` | the same build with every part arranged onto **shared** atlas pages, written into `--out` — losslessly, and gated a second time as the pair that ships. `--page-size` and `--padding` tune it |
 | `build … --atlas-in <file.atlas>` | the same build with every part resolved to a **region of an existing pack** instead of a loose PNG; a name the atlas lacks, a size the spec disagrees with or a rectangle off its page is refused by name |
 | `validate <dir>` | re-gates artifacts already on disk |
-| `ingest <skeleton.json> --out <dir>` | `build` run backwards: reads a Spine 4.3 skeleton and writes the rig spec and motion spec that **rebuild it**, plus a findings report naming everything it could not carry. `--stage x,y,w,h` supplies the one value a skeleton does not hold |
+| `ingest <skeleton.json> --out <dir>` | `build` run backwards: reads a Spine 4.3 skeleton and writes the rig spec and motion spec that **rebuild it**, plus a findings report naming everything it could not carry. `--stage x,y,w,h` supplies the stage for a skeleton that declares none, and `--images <dir>` writes the spec's own images directory — the opposite direction from `build --images`, which overrides it — so the rebuild carries no flag at all |
 | `explain --rig … --motion …` | the compiled rig as a table — every bone with its resolved parent, the slots in draw order, every timeline key by key. Writes nothing. What to reach for when a rig compiles and still looks wrong |
 | `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/` |
 | `preview --candidate <dir>` | one self-contained `.html` that plays it |
@@ -539,11 +539,16 @@ rebuild it. It is the only command that runs against `build`'s direction, and th
 only one whose contract is an equality rather than a rulebook:
 
 ```bash
-rigc ingest hero.json --out specs/ --stage 0,0,1024,768
-rigc build --rig specs/rig.json --motion specs/motion.json --images parts/ --out build/
+rigc ingest hero.json --out specs/ --stage 0,0,1024,768 --images parts/
+rigc build --rig specs/rig.json --motion specs/motion.json --out build/
 rigc diff build/skeleton.json hero.json
 ```
 
+`--images parts/` is what makes the second line carry no flag: it writes the spec's
+own `images` directory, spelled from `--out`, so the specs are self-contained from
+there on. Leave it off and the `image` names resolve against `specs/` itself, which
+holds no art — every rebuild then has to repeat `build --images parts/`.
+
 **`build(ingest(x))` is `x`.** Over the eleven rigs this repository builds — the seven
 gallery examples, the three generated probes and a coverage probe written for the
 purpose — the rebuilt `skeleton.json` is byte for byte the file the decompiler read,
@@ -552,6 +557,15 @@ claim on purpose, and the weakening is measured rather than assumed: it comes ba
 equal as a **multiset of region blocks**, because the order the pages are collected in
 is in no field of the skeleton.
 
+**And over twelve skeletons nobody here wrote.** The same run ingests every editor
+export in the fetched example corpus, rebuilds it through the pack beside it and
+`diff`s the result against the source: **12 of 12, no blockers, 1.000 on every measure
+the report carries.** Byte identity is not the claim there and the reason is the input
+rather than the round trip — an editor header carries `hash` and `audio`, which the rig
+spec has no field for — so the contract is the structural one `diff` measures.
+[INGEST.md §2.3](docs/INGEST.md) has the three kinds of difference that remain, with
+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
@@ -563,11 +577,13 @@ One thing it drops on purpose and says so: a path attachment's `lengths`, which
 
 ⚠️ **Two values are not in a skeleton at all.**
 
-- **The stage.** `skeleton.width`/`height`: rigc always writes one and an editor
-  export carries none, so without `--stage x,y,w,h` the missing box is refused by
-  name. It is not derivable — posing the rig gives the *animated* extent, which is a
-  different number from the setup box — and it is the value that costs nothing to get
-  wrong, because no measure `diff` reports reads the skeleton header at all.
+- **The stage.** `skeleton.width`/`height`: rigc always writes one, and a skeleton that
+  carries none is refused by name unless `--stage x,y,w,h` supplies it. It is not
+  derivable — posing the rig gives the *animated* extent, which is a different number
+  from the setup box. ⚠️ This said *"an editor export carries none"* until #594 measured
+  it: **all twelve exports in the example corpus carry a stage** and none of them needs
+  the flag. It is still the value that costs least to get wrong, because `diff` reports
+  the box and gates nothing on it.
 - **An animation's duration.** The format has no such field. The largest key time is
   the only derivable answer and it is what a runtime plays to; it is wrong for an
   animation that holds its last pose past its last key, so it is recorded as a finding
@@ -597,7 +613,12 @@ export, every `diff` measure that moved, `check`'s mean MAE and worst drift per
 animation **for each skin the build declares** — one render-and-check block per
 skin, with a per-skin roll-up under them, because a rig's contested art lives in
 its named skins and a single un-skinned check draws none of it — and a
-field-by-field list of what the editor rewrote. On its first
+field-by-field list of what the editor rewrote. Every step quotes what its child
+said when that child did not do what it was for, the renderers included; a skin
+**neither** side can draw — a hit-box rig, say — is a **SKIP** naming that, not a
+red, because `check` had nothing to compare and `diff` and `validate` have
+already measured the rig. One side drawing where the other does not is the
+divergence the trip exists to find and stays a failure. On its first
 run it found three emitter defects — [#368](https://github.com/firejune/rigc/issues/368),
 [#369](https://github.com/firejune/rigc/issues/369),
 [#370](https://github.com/firejune/rigc/issues/370) — and then showed that a

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, type CompileOptions } from './src/compile.ts';
+import { compile, CompileError, relativeImagesPath, type CompileOptions } from './src/compile.ts';
 import {
   skeletonDataFromText,
   surveyDeformKeys,
@@ -2776,13 +2776,44 @@ function cmdIngest(flags: Record<string, string>, positional: string[]): void {
     stage = { x: parts[0], y: parts[1], width: parts[2], height: parts[3] };
   }
   const outDir = resolve(flags.out);
+  /**
+   * The rig spec's own `images`, spelled from `--out` the way `build` spells
+   * `skeleton.images` from its own output directory — the SAME function, so the
+   * two conventions cannot drift (issue #595). Without it the field is left out,
+   * an `image` name resolves against the spec's own directory, and every rebuild
+   * of the spec has to carry `build --images <dir>`.
+   */
+  let specImages: string | undefined;
+  if (flags.images !== undefined) {
+    // Refused rather than ignored, for the reason `chainfit` refuses `--atlas`:
+    // a flag that silently does nothing is worse than one that says why it
+    // cannot. Measured — an `--art none` spec rebuilt with `--images` naming a
+    // directory that does not exist is byte-identical to one rebuilt without
+    // it, because no attachment carries an `image` for that directory to be the
+    // base of.
+    if (art === 'none') {
+      throw new UsageError(
+        '--images <dir> and --art none contradict: `none` writes width/height and no `image` at all, so the rig ' +
+          "spec's `images` directory would be the base of nothing and no rebuild would read it. Use --art loose to " +
+          'name an image per attachment, or drop --images — an `--art none` spec rebuilds with `build --atlas-in ' +
+          '<pack.atlas>`',
+      );
+    }
+    // Not checked for existence, deliberately: `ingest` reads the skeleton and
+    // nothing else, so the parts may well be extracted AFTER the specs are
+    // written, and refusing a directory this command never opens would refuse a
+    // legitimate order of work. `build` is where a missing PNG is named.
+    specImages = relativeImagesPath(outDir, resolve(flags.images));
+  }
   console.log(`rigc ingest ${skeletonPath}`);
   console.log(`  ..    out  ${outDir}`);
   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(),
@@ -2807,9 +2838,13 @@ function cmdIngest(flags: Record<string, string>, positional: string[]): void {
   console.log(`rigc: wrote ${join(outDir, 'rig.json')}`);
   console.log(`rigc: wrote ${join(outDir, 'motion.json')}`);
   console.log(`rigc: wrote ${join(outDir, 'findings.json')}`);
+  // The hint is the command the caller will actually run, so it drops `--images`
+  // exactly when the spec now carries the directory itself — a hint that asks for
+  // a flag the spec made unnecessary is the defect issue #595 is about, printed.
+  const artFlag = art === 'none' ? ' --atlas-in <pack.atlas>' : specImages === undefined ? ' --images <dir>' : '';
   console.log(
-    `rigc: build it with  rigc build --rig ${join(outDir, 'rig.json')} --motion ${join(outDir, 'motion.json')} ` +
-      `${art === 'loose' ? '--images <dir>' : '--atlas-in <pack.atlas>'} --out <dir>`,
+    `rigc: build it with  rigc build --rig ${join(outDir, 'rig.json')} --motion ${join(outDir, 'motion.json')}` +
+      `${artFlag} --out <dir>`,
   );
 
   const blockers = result.findings.filter((f) => f.kind === 'blocker');
@@ -2922,12 +2957,15 @@ const FLAG_MEANINGS: Record<string, string> = {
   again: 'record a second vote on a ballot the ledger already has; without it, a repeat is refused rather than doubled',
   name: "the rig spec's own name, which the motion spec's archetype must match (default: the skeleton file's basename)",
   art: 'how the written spec reaches the art, which a skeleton does not encode: `loose` names an image per ' +
-    'attachment for `build --images <dir>` to measure, `none` states width/height only for `build --atlas-in ' +
-    '<pack>` to resolve (default: loose)',
+    "attachment, measured out of the rig spec's own images directory (--images writes it; without it, `build " +
+    '--images <dir>` on every rebuild), `none` states width/height only for `build --atlas-in <pack>` to ' +
+    'resolve (default: loose)',
   stage:
-    "the setup bounding box — `skeleton.x,y,width,height`. An editor export carries none and rigc refuses a " +
-    'compile without one; posing the rig gives the ANIMATED extent, which is a different number, so this is the ' +
-    "caller's value and is never derived. Without it the missing stage is reported as a blocker",
+    'the setup bounding box — `skeleton.x,y,width,height` — for a skeleton that declares none. It cannot be ' +
+    'derived: posing the rig gives the ANIMATED extent, which is a different number from the setup box, so this ' +
+    "is the caller's value, and without it the missing stage is reported as a blocker. ⚠️ An editor export MAY " +
+    'carry none; every editor export measured for this project carries one and ingest reads it straight through, ' +
+    'so the flag is for a file that really has none rather than for editor exports as a class',
   help: "show this command's flags and exit",
 };
 
@@ -2988,15 +3026,25 @@ interface CommandDoc {
    * Per-command wording for a flag whose value or meaning genuinely differs here.
    *
    * ⚠️ The default above it — one meaning per flag name, everywhere — is the rule
-   * and this is the named exception to it, not a second table. Three flags earn it:
-   * `--out` is a directory of artifacts to `build`, a directory of specs to
-   * `ingest`, a directory of pictures to
+   * and this is the named exception to it, not a second table. What earns an entry
+   * is the criterion rather than a headcount: the flag is **shared with another
+   * command**, and it means something different in this one. Examples, and not an
+   * inventory: `--out` is a directory of artifacts to `build`, a directory of specs
+   * to `ingest`, a directory of pictures to
    * `render` and one file to `preview` and `vote`; `--fps` is the rate a frame set
    * was RECORDED at to `check`, which reads it off a sidecar, and the rate to
    * SAMPLE at to `render`, which is choosing it; `--candidate` is one artifact
    * everywhere except `vote`, which is the one command that takes several and is
    * the reason there is a ballot at all. Writing any of them as one sentence
    * covering every command would leave every command's own help less true.
+   *
+   * ⛔ The other side of the criterion, which is the one that keeps this from
+   * becoming the second table it says it is not: a flag no other command takes has
+   * nothing to differ FROM, so its wording belongs in `FLAG_MEANINGS` /
+   * `FLAG_VALUES` above and an entry here for it buys only a second place to look.
+   * Both halves are read off `--help` by `CLI71` in `selftest.ts`, which is why
+   * this sentence no longer counts anything: it said *"three"* where #605 counted
+   * nine, and nothing had ever compared the two.
    */
   overrides?: Record<string, { value?: string; meaning?: string }>;
 }
@@ -3041,13 +3089,21 @@ const COMMANDS: CommandDoc[] = [
   },
   {
     name: 'ingest',
-    usage: ['rigc ingest <skeleton.json> --out <dir> [--name <n>] [--art loose|none] [--stage x,y,w,h]'],
-    flags: ['out', 'name', 'art', 'stage'],
+    usage: ['rigc ingest <skeleton.json> --out <dir> [--name <n>] [--art loose|none] [--images <dir>] [--stage x,y,w,h]'],
+    flags: ['out', 'name', 'art', 'images', 'stage'],
     overrides: {
       out: {
         value: '<dir>',
         meaning: 'directory to write rig.json, motion.json and findings.json into — the two specs that rebuild this skeleton',
       },
+      images: {
+        value: '<dir>',
+        meaning:
+          "WRITE the rig spec's own images directory, spelled relative to --out, so the rebuild is a plain `build " +
+          '--rig … --motion … --out …` with no flag. ⚠️ The opposite direction from `build --images`, which ' +
+          'OVERRIDES that field: this one fills it in. Without it the field is left out and every `image` resolves ' +
+          'against --out itself. Refused together with --art none, which writes no `image` for it to be the base of',
+      },
     },
   },
   {
@@ -3258,8 +3314,11 @@ const USAGE = [
   'The contract is an equality, not a rulebook: build(ingest(x)) is x, byte for byte.',
   'It reads the skeleton and nothing else — no .spine project, no binary .skel, no',
   'atlas — so two things are the caller\'s and are refused rather than guessed: the',
-  'setup stage (--stage; an export carries none) and how the spec reaches the art',
-  '(--art). Everything the spec format cannot hold is printed as a named finding and',
+  'setup stage (--stage, only when the skeleton itself declares none) and how the spec',
+  'reaches the art (--art). --images <dir> is the third and the only optional one: it',
+  'WRITES the rig spec\'s own images directory, relative to --out, so the rebuild needs',
+  'no flag.',
+  'Everything the spec format cannot hold is printed as a named finding and',
   'exits non-zero, with both files still written, because a spec plus a list of what',
   'is missing from it beats no spec at all.',
   '',