spine-rigc 0.27.0 → 0.29.0

package/cli.ts

@@ -66,10 +66,24 @@ import {
   type DeformKeyMeasure,
   type DeformSpan,
 } from './src/deformmeasure.ts';
-import { diffLines, diffSkeletons, reportedFigures, sectionFigures, type DiffReport } from './src/diff.ts';
+import {
+  diffLines,
+  diffSkeletons,
+  reportedFigures,
+  sectionFigures,
+  type DiffAnimationPair,
+  type DiffReport,
+} from './src/diff.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 {
+  DEFAULT_PADDING,
+  DEFAULT_PAGE_SIZE,
+  packAtlas,
+  pageFootprint,
+  parseAtlasText,
+  type AtlasRegion,
+} 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';
@@ -218,13 +232,16 @@ const BOOLEAN_FLAGS = new Set(['all-frames', 'all-bones', 'help', 'copy-images',
 /**
  * The flags a command is allowed to spell more than once.
  *
- * Only `vote --candidate` is, because a ballot is *by definition* several
- * candidates. Everywhere else a repeat is a mistake and is refused: `check
+ * `vote --candidate` is, because a ballot is *by definition* several
+ * candidates, and `diff --as` is, because a skeleton has as many shots as it
+ * has and one pairing per flag is the only spelling that keeps each pair a pair
+ * (issue #720). Everywhere else a repeat is a mistake and is refused: `check
  * --candidate a --candidate b` used to take `b` silently, which is a report
  * about a rig the caller did not think they were asking about.
  */
 const REPEATABLE_FLAGS: Record<string, ReadonlySet<string>> = {
   vote: new Set(['candidate']),
+  diff: new Set(['as']),
 };
 
 /**
@@ -1155,6 +1172,45 @@ function dropLine(dropped: DroppedState): string {
   return `  DROP  ${dropped.slot}/${dropped.state}: ${droppedStateReason(dropped)} (state not emitted)`;
 }
 
+/**
+ * The rectangle a region occupies **on its page**, for a line that has already
+ * said where the region is — and the empty string where the page rectangle is
+ * the one `bounds:` already states.
+ *
+ * ## The fact no surface an author reads carried (issue #718)
+ *
+ * The atlas line beside this clause prints the DRAWING's size, because that is
+ * what an attachment's width and height mean. A packer that turned the drawing a
+ * quarter to fit it wrote `bounds:` in the drawing's orientation too. So an
+ * author holding the pack and the build report had neither end of the rectangle
+ * they have to cut out of the page to measure a part against a rendered frame —
+ * and the one place rigc printed it was `A06`'s overlap text, reachable only
+ * under `--profile spine-html`. The knowledge was in the tree the whole time:
+ * `pageFootprint` has derived this rectangle for every reader of it since issue
+ * #579, and nothing an author reads said it.
+ *
+ * ⚠️ **The condition is `pageFootprint`'s own answer, not a second reading of
+ * `degrees`.** Re-spelling that predicate here is the exact duplication #579 was
+ * filed on — four readers derived this rectangle and two derived it wrongly — so
+ * the clause asks the function whether its answer differs from the `bounds:`
+ * line, and prints only then.
+ *
+ * 🔸 A consequence worth stating rather than leaving to be discovered: a region
+ * whose KEPT rectangle is square is silent here, because a quarter turn leaves
+ * its footprint the same two numbers and there is nothing the pack does not
+ * already say. The general rule — `bounds` is the unturned size, the footprint
+ * is its transpose at `rotate: 90` and `rotate: 270`, and which way to turn the
+ * rectangle to recover the drawing — belongs to an author's own reading and is
+ * stated in `docs/AUTHORING.md` §0.2, which holds for every region including
+ * that one.
+ */
+function pageRectangle(region: AtlasRegion): string {
+  const foot = pageFootprint(region);
+  return foot.width === region.width && foot.height === region.height
+    ? ''
+    : `, occupies ${foot.width}x${foot.height}`;
+}
+
 function cmdBuild(flags: Record<string, string>): void {
   const { label, opts } = resolveCut(flags);
   const profile = readProfile(flags);
@@ -1208,13 +1264,23 @@ function cmdBuild(flags: Record<string, string>): void {
     // that declares a `scale:` also says so and shows the texels it was read
     // from: the size on the left is the DRAWING's and the rectangle is the
     // pack's, and issue #267 is the report that printed the second as the first.
+    //
+    // `pageRectangle` closes the line's last silence (issue #718), and it is
+    // placed LAST rather than beside the turn it follows from, which is where
+    // the card put it. The two clauses collide nowhere else, and the collision
+    // is real: `scale 0.5 (373x106 texels)` is itself a size, so
+    // `rotate 90, occupies 106x373 scale 0.5 (…)` reads as though the footprint
+    // were the scaled quantity. As a trailing clause of the whole location
+    // phrase it is unambiguous with a `scale:` line and identical to the card's
+    // wording without one, which is every pack that has no `scale:` to state.
     const where =
       img.atlas === undefined
         ? img.page
         : `${img.page} @ ${img.atlas.x},${img.atlas.y}${img.atlas.degrees ? ` rotate ${img.atlas.degrees}` : ''}` +
           (img.atlasScale === undefined
             ? ''
-            : ` scale ${img.atlasScale} (${img.atlas.originalWidth}x${img.atlas.originalHeight} texels)`);
+            : ` scale ${img.atlasScale} (${img.atlas.originalWidth}x${img.atlas.originalHeight} texels)`) +
+          pageRectangle(img.atlas);
     console.log(`  ..      ${img.region.padEnd(24)} ${img.width}x${img.height}  <- ${where}`);
   }
   for (const d of result.droppedStates) console.log(dropLine(d));
@@ -1403,7 +1469,69 @@ function cmdValidate(flags: Record<string, string>, positional: string[]): void
   console.log('rigc: green');
 }
 
-function cmdDiff(flags: Record<string, string>, positional: string[]): void {
+/**
+ * `--as <candidate>=<reference>`, one pair per occurrence.
+ *
+ * ⚠️ Spelled with a pair where `check --as <name>` takes one name, and the
+ * difference is in what the two commands have on the other side. `check`
+ * measures against a rendered frame SET, which already carries the reference
+ * animation's name in its own directory, so one name closes the gap. `diff` has
+ * two skeletons and either may have its own vocabulary, so one name says which
+ * shot on which side and leaves the other unanswered. The direction — candidate
+ * first — is the one `bonedist`'s correspondence file already writes its
+ * `animations` map in.
+ *
+ * Every refusal here is a UsageError because every one of them is about the
+ * flag's own value, and each names what it read: a value with no `=`, an empty
+ * side, a name repeated on either side, and a name no animation on that side
+ * answers to. ⛔ The last of those is a refusal rather than a dropped pair for
+ * the reason a miss is refused by name everywhere else in this tool — a typo
+ * that quietly measured less would be a report about a pairing the caller did
+ * not ask for.
+ */
+function readAnimationPairs(values: string[], candidate: unknown, reference: unknown): DiffAnimationPair[] {
+  const animationsOf = (root: unknown): string[] => {
+    const anims = (root as { animations?: unknown } | null)?.animations;
+    return typeof anims === 'object' && anims !== null && !Array.isArray(anims) ? Object.keys(anims) : [];
+  };
+  const have = { candidate: animationsOf(candidate), reference: animationsOf(reference) };
+  const pairs: DiffAnimationPair[] = [];
+  for (const value of values) {
+    const at = value.indexOf('=');
+    if (at < 0) {
+      throw new UsageError(
+        `--as ${JSON.stringify(value)} is not a pair. It takes <candidate>=<reference> — two animation names joined ` +
+          'by `=`, because diff compares two skeletons and either may have its own name for the shot. The candidate ' +
+          `has [${have.candidate.join(', ') || 'none'}] and the reference has [${have.reference.join(', ') || 'none'}].`,
+      );
+    }
+    const pair = { candidate: value.slice(0, at), reference: value.slice(at + 1) };
+    if (pair.candidate === '' || pair.reference === '') {
+      throw new UsageError(
+        `--as ${JSON.stringify(value)} leaves the ${pair.candidate === '' ? 'candidate' : 'reference'} side empty; ` +
+          'it takes <candidate>=<reference>, a name on each side',
+      );
+    }
+    for (const side of ['candidate', 'reference'] as const) {
+      if (!have[side].includes(pair[side])) {
+        throw new UsageError(
+          `--as ${JSON.stringify(value)} names no ${side} animation: the ${side} has ` +
+            `[${have[side].join(', ') || 'none'}] and not ${JSON.stringify(pair[side])}`,
+        );
+      }
+      if (pairs.some((p) => p[side] === pair[side])) {
+        throw new UsageError(
+          `--as pairs the ${side} animation ${JSON.stringify(pair[side])} twice; each animation may be in one pair, ` +
+            'or the block would compare one shot against two',
+        );
+      }
+    }
+    pairs.push(pair);
+  }
+  return pairs;
+}
+
+function cmdDiff(flags: Record<string, string>, lists: Record<string, string[]>, positional: string[]): void {
   const [candidate, reference] = positional;
   if (!candidate || !reference) throw new UsageError('diff takes two paths: <candidate.json> <reference.json>');
   const candidatePath = resolve(candidate);
@@ -1411,7 +1539,10 @@ function cmdDiff(flags: Record<string, string>, positional: string[]): void {
   for (const path of [candidatePath, referencePath]) {
     if (!existsSync(path)) throw new UsageError(`nothing at ${path}`);
   }
-  const report = diffSkeletons(readJsonFile(candidatePath), readJsonFile(referencePath));
+  const candidateJson = readJsonFile(candidatePath);
+  const referenceJson = readJsonFile(referencePath);
+  const animationPairs = readAnimationPairs(lists.as ?? [], candidateJson, referenceJson);
+  const report = diffSkeletons(candidateJson, referenceJson, { animationPairs });
   console.log('rigc diff');
   for (const line of diffLines(report, { candidate: candidatePath, reference: referencePath })) console.log(line);
   if (flags.json !== undefined) {
@@ -3266,8 +3397,26 @@ const COMMANDS: CommandDoc[] = [
   },
   {
     name: 'diff',
-    usage: ['rigc diff <candidate.json> <reference.json> [--json <out>]'],
-    flags: ['json'],
+    usage: ['rigc diff <candidate.json> <reference.json> [--as <candidate>=<reference>]… [--json <out>]'],
+    flags: ['as', 'json'],
+    overrides: {
+      as: {
+        value: '<candidate>=<reference>',
+        meaning:
+          'pair a candidate animation with a reference one, so the name-agnostic `animations` block can be ' +
+          'measured over shots the two files call different things. Repeatable, one pair each. An INPUT and never ' +
+          'derived: two skeletons cannot say which of their shots are the same shot. Without it the block appears ' +
+          'only when each side has exactly one animation, which pairs by position, and is otherwise absent rather ' +
+          'than guessed',
+      },
+    },
+    notes: [
+      'the `animations` block reads two figures once something has paired the shots, exactly as',
+      '`bones` and `slots` do: name-matched, where `names` lives, and name-agnostic over the pair.',
+      'A candidate that followed a brief withholding the animation name reads `count` 1/1 and 0.000',
+      'on every other name-matched measure — including `duration` and `key_counts` it may have got',
+      'exactly right — so read the pair and not the section mean.',
+    ],
   },
   {
     name: 'check',
@@ -3562,7 +3711,7 @@ try {
   else if (command === 'ingest') cmdIngest(flags, positional);
   else if (command === 'validate') cmdValidate(flags, positional);
   else if (command === 'explain') cmdExplain(flags);
-  else if (command === 'diff') cmdDiff(flags, positional);
+  else if (command === 'diff') cmdDiff(flags, lists, positional);
   else if (command === 'check') cmdCheck(flags);
   else if (command === 'bench') cmdBench(flags, positional);
   else if (command === 'bonedist') cmdBoneDist(flags);