rig-c 0.0.0-stage → 2.20.4

package/src/assertions/bodies/a35.ts

@@ -0,0 +1,160 @@
+/**
+ * A35, restated over the emitted text (issue #1060): the clause
+ * `validate()` runs in `src/validate.ts`, word for word, over the skeleton JSON — the
+ * text rigc wrote, read by rigc's own reader rather than by spine-core's. The
+ * round trip's copy is unchanged and runs in `cli.ts build`; this one runs in
+ * the gate of the entry that links none of the runtime
+ * (`../emitted/index.ts`), and the selftest's `RC28` holds the two to the
+ * same lines on every recipe and on this assertion's mutants.
+ */
+import type { Verdicts } from '../harness.ts';
+import { isObj, type Json } from '../values.ts';
+
+/**
+ * How long the array a deform key edits is, read off one raw attachment — or
+ * `null` when the file does not say.
+ *
+ * The rule is `readVertices`' own: the attachment's `vertices` is coordinates
+ * when its length equals `worldVerticesLength`, and a weight run otherwise. A
+ * deform array is therefore one `x, y` pair per **vertex** in the first case and
+ * one per **bone influence** (`vertices.length / 3`) in the second — the same
+ * count with two different meanings, which is exactly why this measures rather
+ * than assumes.
+ *
+ * `null` for the two shapes that cannot be measured from this object alone: a
+ * type with no vertices at all (nothing to deform, and the parser throws on it),
+ * and a `linkedmesh`, whose geometry belongs to another attachment.
+ */
+function deformArrayLength(att: Json): number | null {
+  const type = typeof att.type === 'string' ? att.type : 'region';
+  let worldVerticesLength: number;
+  if (type === 'mesh') {
+    if (!Array.isArray(att.uvs)) return null;
+    worldVerticesLength = att.uvs.length;
+  } else if (type === 'boundingbox' || type === 'clipping' || type === 'path') {
+    if (typeof att.vertexCount !== 'number') return null;
+    worldVerticesLength = att.vertexCount * 2;
+  } else {
+    return null;
+  }
+  if (!Array.isArray(att.vertices)) return null;
+  const vertices = att.vertices as unknown[];
+  if (vertices.length === worldVerticesLength) return worldVerticesLength;
+  // ⚠️ Weighted, and the length is the INFLUENCE COUNT — which is the sum of the
+  // per-vertex bone counts, not a division of this array's length. The file
+  // holds `boneCount` followed by `boneIndex, x, y, weight` per influence, so a
+  // one-bone vertex is FIVE numbers; `readVertices` unpacks that into three
+  // numbers per influence, which is where the parser's own `/3*2` comes from and
+  // exactly why it cannot be applied to the raw form. Applied here it measured
+  // `gallery/flex`'s 77-vertex leaf at 256.667 against its true 154 and put
+  // A35's bar two thirds too wide on every weighted mesh — the silence A35
+  // exists to break, arriving inside A35.
+  //
+  // Derived here rather than shared with `src/compile.ts`'s own walk on purpose:
+  // the gate re-derives from the emitted file so that it is not checking the
+  // compiler's assumptions with the compiler's code. Both had this wrong, which
+  // is an argument for a control on each and not for one implementation.
+  let influences = 0;
+  for (let i = 0; i < vertices.length; ) {
+    const n = vertices[i++];
+    if (typeof n !== 'number' || !Number.isInteger(n) || n < 1) return null;
+    influences += n;
+    i += n * 4;
+    if (i > vertices.length) return null;
+  }
+  return influences * 2;
+}
+
+export function a35DeformKeysFitTheAttachment({ fail, skip }: Verdicts, raw: Json | null): void {
+  if (!raw) return skip('A35_DEFORM_KEYS_FIT_THE_ATTACHMENT', 'the skeleton JSON did not parse (A00 owns that failure)');
+  if (!isObj(raw.animations)) return skip('A35_DEFORM_KEYS_FIT_THE_ATTACHMENT', 'the skeleton declares no animations');
+  /** skin name -> slot -> attachment, straight off the raw JSON. */
+  const skins = new Map<string, Json>();
+  for (const skin of Array.isArray(raw.skins) ? (raw.skins as unknown[]) : []) {
+    if (isObj(skin) && typeof skin.name === 'string' && isObj(skin.attachments)) {
+      skins.set(skin.name, skin.attachments as Json);
+    }
+  }
+  let sawATimeline = false;
+  let measured = 0;
+  for (const [animName, anim] of Object.entries(raw.animations as Json)) {
+    if (!isObj(anim) || !isObj(anim.attachments)) continue;
+    for (const [skinName, slotMap] of Object.entries(anim.attachments as Json)) {
+      if (!isObj(slotMap)) continue;
+      for (const [slotName, attMap] of Object.entries(slotMap)) {
+        if (!isObj(attMap)) continue;
+        for (const [attName, timelines] of Object.entries(attMap)) {
+          if (!isObj(timelines) || !Array.isArray(timelines.deform)) continue;
+          sawATimeline = true;
+          const at = `animation "${animName}" deform ${skinName}/${slotName}/${attName}`;
+          const attachment = isObj(skins.get(skinName)?.[slotName])
+            ? ((skins.get(skinName)![slotName] as Json)[attName] as unknown)
+            : undefined;
+          if (!isObj(attachment)) {
+            fail(
+              'A35_DEFORM_KEYS_FIT_THE_ATTACHMENT',
+              `${at}: skin "${skinName}" has no attachment "${attName}" on slot "${slotName}"; the parser throws ` +
+                '`Timeline attachment not found`',
+            );
+            continue;
+          }
+          const length = deformArrayLength(attachment);
+          if (length === null) {
+            // A linked mesh takes its geometry from another attachment, so the
+            // raw file cannot state this one's length. Saying nothing beats
+            // inventing a bound: an assertion with a default is how "nothing to
+            // measure" becomes a measurement of the wrong thing.
+            continue;
+          }
+          measured++;
+          const keys = timelines.deform as unknown[];
+          if (keys.length === 0) {
+            fail('A35_DEFORM_KEYS_FIT_THE_ATTACHMENT', `${at}: the key array is empty; the parser skips the timeline in silence`);
+            continue;
+          }
+          keys.forEach((key, k) => {
+            if (!isObj(key)) {
+              fail('A35_DEFORM_KEYS_FIT_THE_ATTACHMENT', `${at} key ${k}: not an object`);
+              return;
+            }
+            const vertices = key.vertices;
+            if (vertices === undefined || vertices === null) return; // "back to setup" — nothing to fit
+            if (!Array.isArray(vertices)) {
+              fail('A35_DEFORM_KEYS_FIT_THE_ATTACHMENT', `${at} key ${k}: vertices is ${JSON.stringify(vertices)}, not an array`);
+              return;
+            }
+            const offset = key.offset === undefined ? 0 : key.offset;
+            if (typeof offset !== 'number' || !Number.isInteger(offset) || offset < 0) {
+              fail('A35_DEFORM_KEYS_FIT_THE_ATTACHMENT', `${at} key ${k}: offset is ${JSON.stringify(key.offset)}`);
+              return;
+            }
+            // ⛔ No parity clause here, and the header says why: an odd `offset`
+            // and an odd-length run are both what a trimmed editor export looks
+            // like, and the parser has no pair arithmetic to be misaligned
+            // against (#262).
+            if (offset + vertices.length > length) {
+              fail(
+                'A35_DEFORM_KEYS_FIT_THE_ATTACHMENT',
+                `${at} key ${k}: the run covers ${offset}..${offset + vertices.length} of a ${length}-long deform ` +
+                  'array; everything past the end is copied into a Float32Array and dropped without a word',
+              );
+            }
+            for (const n of vertices as unknown[]) {
+              if (typeof n !== 'number' || !Number.isFinite(n)) {
+                fail('A35_DEFORM_KEYS_FIT_THE_ATTACHMENT', `${at} key ${k}: the run holds a non-finite value ${JSON.stringify(n)}`);
+                break;
+              }
+            }
+          });
+        }
+      }
+    }
+  }
+  if (!sawATimeline) return skip('A35_DEFORM_KEYS_FIT_THE_ATTACHMENT', 'no animation carries a deform timeline');
+  if (measured === 0) {
+    return skip(
+      'A35_DEFORM_KEYS_FIT_THE_ATTACHMENT',
+      'every deform timeline here keys an attachment whose vertex count the raw file does not state (a linked mesh)',
+    );
+  }
+}

package/src/assertions/bodies/a36.ts

@@ -0,0 +1,81 @@
+/**
+ * A36, the body (issue #1025, step 4c of #380): a path constraint that
+ * follows nothing, quietly.
+ *
+ * 🚨 The first failure here is the quietest in the whole constraint half of
+ * the format. `PathConstraint.update` opens with
+ *
+ *   const attachment = this.slot.appliedPose.attachment;
+ *   if (!(attachment instanceof PathAttachment)) return;
+ *
+ * so a path constraint aimed at a slot that never shows a path loads
+ * perfectly, reports every mix it was given, appears in the update cache —
+ * and moves nothing, forever. Nothing in the file is wrong on its face: the
+ * slot exists, the constraint resolves, the mixes are 1.
+ *
+ * The rest are the same shape as A23's: a constraint that parses and does
+ * nothing. All three mixes at 0 is only a finding when no animation keys one
+ * of them above 0 (`switchedOn` over the `mix` timelines, judged by
+ * `mixLive`), and a chain with no bones on it is one whether or not anything
+ * is keyed.
+ *
+ * Moved out of `src/validate.ts` whole: the bones, the slot and the skins'
+ * paths, the setup mixes and the keyed ones are all the rig's, and a
+ * document's records state each.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { ConstraintFacts } from '../facts/constraints.ts';
+import { mixLive, noneKeysItsMixAbove0, switchedOn } from '../constraint_words.ts';
+
+export function a36PathConstraintEffective({ fail, skip, stats }: Verdicts, facts: ConstraintFacts): void {
+  const constraints = facts.constraints.flatMap((c, index) => (c.path === undefined ? [] : [{ name: c.name, path: c.path, index }]));
+  if (!constraints.length) return skip('A36_PATH_CONSTRAINT_EFFECTIVE', 'the skeleton declares no path constraint');
+  /**
+   * Which path constraints an animation switches ON — `switchedOn` over their
+   * `mix` timelines, judged by `mixLive`, the predicate their setup pose is
+   * judged by below.
+   *
+   * ⭐ The reason this is needed: a constraint whose mixes are all 0 at setup
+   * is **the idiom**, not a defect — spineboy's aim rig is exactly that, and
+   * issue #88 landed the timelines that turn one on. So "muted" is only a
+   * finding when nothing turns it on, and that question lives in the
+   * animations rather than in the constraint.
+   *
+   * 🔑 "Turns it on" is a VALUE question, and until issue #752 this asked a
+   * weaker one than `A23` — whether a `mix` key array was non-empty — so a
+   * timeline keying 0 only was a rescue for a constraint it leaves exactly as
+   * muted as no timeline does. Now a path constraint is switched on by a key
+   * posing any of its three mixes above 0, which is the runtime's own
+   * condition: `PathConstraint.update` returns when `mixRotate`, `mixX` and
+   * `mixY` are all 0 (`PathConstraint.js:73-75`).
+   */
+  const pathSwitchedOn = switchedOn(facts, (timeline) => timeline.kind === 'path' && timeline.word === 'mix', 3, (_timeline, value) => mixLive(value));
+  /** The slots some skin gives a path attachment. */
+  const pathsBySlot = new Set(facts.pathSlots);
+  for (const { name, path: constraint, index } of constraints) {
+    const where = `path constraint "${name}"`;
+    if (!constraint.bones.length) {
+      fail('A36_PATH_CONSTRAINT_EFFECTIVE', `${where} constrains no bone; it parses and does nothing`);
+    }
+    const slot = constraint.slot;
+    if (!pathsBySlot.has(slot)) {
+      fail(
+        'A36_PATH_CONSTRAINT_EFFECTIVE',
+        `${where} follows slot "${slot}", and no skin gives that slot a path attachment — ` +
+          "PathConstraint.update returns immediately unless the slot's attachment is a path, so this " +
+          'constraint reports its mixes and moves nothing',
+      );
+    }
+    const pose = constraint.setup;
+    const muted = ![pose.mixRotate, pose.mixX, pose.mixY].some(mixLive);
+    if (muted && !pathSwitchedOn.has(index)) {
+      fail(
+        'A36_PATH_CONSTRAINT_EFFECTIVE',
+        `${where} has mixRotate ${pose.mixRotate}, mixX ${pose.mixX} and mixY ${pose.mixY} at setup and ` +
+          `${noneKeysItsMixAbove0(facts.animations)}; update() returns on all-zero mixes, so nothing ever ` +
+          'puts a bone on the path — rest one of the three above 0, or key its mix above 0 in an animation',
+      );
+    }
+  }
+  stats.pathConstraints = constraints.length;
+}

package/src/assertions/bodies/a37.ts

@@ -0,0 +1,77 @@
+/**
+ * A37, the body (issue #1025, step 4c of #380): a slider that applies
+ * nothing, quietly.
+ *
+ * A slider is the only constraint that applies an ANIMATION, so its failure
+ * modes are about that animation rather than about a transform:
+ *
+ *   1. **An animation with no timelines.** `animation.apply` walks an empty
+ *      array. The slider is in the update cache, its time moves, and the
+ *      skeleton never changes.
+ *   2. **`loop` on a zero-length animation.** `Slider.update` computes
+ *      `animation.duration + (p.time % animation.duration)` when looping, so
+ *      a duration of 0 makes the time **NaN** — and it then applies the
+ *      animation at NaN, which is a pose nobody can predict and no error.
+ *      Only reachable with a bone, because that is the branch the loop
+ *      arithmetic lives in.
+ *   3. **`scale` 0 with a bone.** `time = offset + (value - offset) * 0`, so
+ *      the dial turns and the slider holds one frame.
+ *   4. **`mix` 0** with nothing keying it — the same rule as A36's.
+ *
+ * Moved out of `src/validate.ts` whole: the animation it applies (its
+ * timeline count and duration), its dial, `loop`, `scale` and mix, and the
+ * keys that raise its mix are the rig's, and a document's records state each.
+ * ⚠️ `scale` is read behind `bone` only, and that is where the one known
+ * disagreement between the suppliers lives: on a bone-less slider spine-core
+ * leaves `scale` at 0 and the document states 1 (#1027). Clause 3 never reads
+ * a bone-less slider's scale, so no line can differ on it.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { ConstraintFacts } from '../facts/constraints.ts';
+import { mixLive, noneKeysItsMixAbove0, REST_OR_KEY_ITS_MIX, switchedOn } from '../constraint_words.ts';
+
+export function a37SliderConstraintEffective({ fail, skip, stats }: Verdicts, facts: ConstraintFacts): void {
+  const sliders = facts.constraints.flatMap((c, index) => (c.slider === undefined ? [] : [{ name: c.name, slider: c.slider, index }]));
+  if (!sliders.length) return skip('A37_SLIDER_CONSTRAINT_EFFECTIVE', 'the skeleton declares no slider constraint');
+  /** Which sliders an animation switches ON — `switchedOn` over their `mix` timelines, judged by `mixLive` (A36's ⭐ and 🔑; `Slider.update` returns when `mix` is 0, `Slider.js:53-54`). */
+  const sliderSwitchedOn = switchedOn(facts, (timeline) => timeline.kind === 'slider' && timeline.word === 'mix', 1, (_timeline, value) => mixLive(value));
+  for (const { name, slider, index } of sliders) {
+    const where = `slider "${name}"`;
+    const animation = slider.animation;
+    if (!animation) {
+      // The parser's second pass throws on a miss, so this is only reachable
+      // on an artifact that never went through it.
+      fail('A37_SLIDER_CONSTRAINT_EFFECTIVE', `${where} applies no animation`);
+      continue;
+    }
+    if (animation.timelines === 0) {
+      fail(
+        'A37_SLIDER_CONSTRAINT_EFFECTIVE',
+        `${where} applies animation "${animation.name}", which carries no timeline at all; the slider runs and ` +
+          'the skeleton never changes',
+      );
+    }
+    if (slider.bone && slider.loop && !(animation.duration > 0)) {
+      fail(
+        'A37_SLIDER_CONSTRAINT_EFFECTIVE',
+        `${where} loops animation "${animation.name}", whose duration is ${animation.duration} — ` +
+          'Slider.update computes `duration + (time % duration)` when looping, so the applied time is NaN',
+      );
+    }
+    if (slider.bone && slider.scale === 0) {
+      fail(
+        'A37_SLIDER_CONSTRAINT_EFFECTIVE',
+        `${where} drives off bone "${slider.bone}" with scale 0, so the property cannot move the slider's time`,
+      );
+    }
+    const mix = slider.mix;
+    if (!mixLive(mix) && !sliderSwitchedOn.has(index)) {
+      fail(
+        'A37_SLIDER_CONSTRAINT_EFFECTIVE',
+        `${where} has mix ${mix} at setup and ${noneKeysItsMixAbove0(facts.animations)}; update() returns ` +
+          `on mix 0 — ${REST_OR_KEY_ITS_MIX}`,
+      );
+    }
+  }
+  stats.sliderConstraints = sliders.length;
+}

package/src/assertions/bodies/a38.ts

@@ -0,0 +1,73 @@
+/**
+ * A38, the body (issue #1025, step 4c of #380): a skin's member list and its
+ * members' `skin: true` flag agree.
+ *
+ * Moved out of `src/validate.ts` unchanged but for what it reads: the bones,
+ * the constraints and the skins' lists are a fact (`../facts/skin_members.ts`)
+ * — which spine-core's loaded `SkeletonData` satisfies as it stands. Why both
+ * halves of the switch are dead data alone stays above the `check` call in
+ * `validate()`.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { MemberBone, SkinMemberFacts } from '../facts/skin_members.ts';
+
+export function a38SkinMembersAreSkinRequired({ fail, skip, stats }: Verdicts, data: SkinMemberFacts): void {
+  /** Every bone a skin can switch on, including the ancestors it drags in. */
+  const activatable = new Set<string>();
+  // The constraint OBJECTS a skin lists, never their names: a name is not a
+  // constraint in this format, and two constraints of one name under two
+  // kinds are two objects a skin may list separately (issue #692). Keyed by
+  // name, a `transform` `leg` that no skin lists read as listed because an
+  // `ik` `leg` was — a skinRequired constraint that never runs, reported
+  // green by the one assertion that looks for exactly that.
+  const listedConstraints = new Set(data.skins.flatMap((skin) => skin.constraints));
+  let listed = 0;
+  for (const skin of data.skins) {
+    for (const bone of skin.bones) {
+      listed++;
+      for (let cursor: MemberBone | null = bone; cursor; cursor = cursor.parent) activatable.add(cursor.name);
+      if (!bone.skinRequired) {
+        fail(
+          'A38_SKIN_MEMBERS_ARE_SKIN_REQUIRED',
+          `skin "${skin.name}" activates bone "${bone.name}", which is not skinRequired — updateCache starts it ` +
+            'active anyway, so it poses under every skin and this list changes nothing',
+        );
+      }
+    }
+    for (const constraint of skin.constraints) {
+      listed++;
+      if (!constraint.skinRequired) {
+        fail(
+          'A38_SKIN_MEMBERS_ARE_SKIN_REQUIRED',
+          `skin "${skin.name}" activates constraint "${constraint.name}", which is not skinRequired — it runs ` +
+            'under every skin, so this list changes nothing',
+        );
+      }
+    }
+  }
+  const required = data.bones.filter((b) => b.skinRequired).length + data.constraints.filter((c) => c.skinRequired).length;
+  if (listed === 0 && required === 0) {
+    return skip(
+      'A38_SKIN_MEMBERS_ARE_SKIN_REQUIRED',
+      'no skin activates a bone or a constraint, and nothing declares itself skinRequired',
+    );
+  }
+  for (const bone of data.bones) {
+    if (bone.skinRequired && !activatable.has(bone.name)) {
+      fail(
+        'A38_SKIN_MEMBERS_ARE_SKIN_REQUIRED',
+        `bone "${bone.name}" is skinRequired and no skin's bones list reaches it, so it is never active — ` +
+          'it and its subtree hold the setup pose under every skin',
+      );
+    }
+  }
+  for (const constraint of data.constraints) {
+    if (constraint.skinRequired && !listedConstraints.has(constraint)) {
+      fail(
+        'A38_SKIN_MEMBERS_ARE_SKIN_REQUIRED',
+        `constraint "${constraint.name}" is skinRequired and no skin lists it, so it never runs`,
+      );
+    }
+  }
+  stats.skinMembers = listed;
+}