spine-rigc 0.26.0 → 0.28.0

package/src/validate.ts

@@ -59,6 +59,12 @@ import {
   type DeformReach,
   type DialSpan,
 } from './deformmeasure.ts';
+import {
+  LEGACY_BONE_INHERIT_KEY,
+  spineGeneration,
+  TOPLEVEL_CONSTRAINT_ARRAYS,
+  type SpineGeneration,
+} from './generation.ts';
 import { colourTypeName, readPngInfo } from './png.ts';
 import {
   CHANNELS_BY_KIND,
@@ -188,6 +194,7 @@ const ASSERTION_KIND: Record<string, 'validity' | 'renderer' | 'archetype'> = {
   A41_PHYSICS_SURVIVES_EDITOR_ROUND_TRIP: 'validity',
   A42_DRIVEN_CONSTRAINTS_UPDATE_AFTER_THEIR_DRIVER: 'validity',
   A43_TWO_COLOR_TINT_LOADS_AND_POSES_AS_WRITTEN: 'validity',
+  A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN: 'validity',
 };
 
 /**
@@ -291,6 +298,7 @@ export const SKIP_NO_ATTACHMENT_REGION_JOIN =
   'no attachment names a region and the atlas declares none, so there is no attachment-to-region join to hold';
 export const SKIP_NO_TWO_COLOR_TINT =
   'no slot declares a "dark" colour and no animation keys an "rgba2" timeline, so there is no two-colour tint to read back';
+export const SKIP_NO_LINKED_MESH = 'no attachment in this skeleton takes its geometry from another one';
 /**
  * A09's, which predates this list and joins it rather than being rewritten: it
  * is the same fact about the same subject, and a control that compares against
@@ -512,11 +520,20 @@ function float32Step(t: number): number {
 }
 
 /**
- * `4.3`, `4.3.<patch>`, or `4.3.<patch>-<suffix>` — the last of which is what the
- * Spine editor writes for a pre-release (`"4.3.75-beta"` in all twelve official
- * example exports). The major/minor pair is the load-bearing part; see A16.
+ * The generation `A16` demands, which is the whole of what that assertion is
+ * about: the MAJOR.MINOR pair.
+ *
+ * ⭐ **The reading itself moved to [`generation.ts`](generation.ts)** with issue
+ * #706 — one reader of `skeleton.spine` for the whole repository, because
+ * `ingest` has to ask the same question of a file somebody else wrote and two
+ * regexes would answer it two ways. What did NOT move is the accepted set:
+ * `4.3`, `4.3.<patch>` and `4.3.<patch>-<suffix>`, the last of which is what the
+ * editor writes for a pre-release (`"4.3.75-beta"` in all twelve official
+ * example exports, and the string the original `/^4\.3(\.\d+)?$/` rejected —
+ * blocker B2). `GN05` holds that set against the old regex, which survives in
+ * `selftest.ts` and nowhere else, for exactly that comparison.
  */
-const SPINE_4_3_VERSION = /^4\.3(\.\d+(-[0-9A-Za-z][0-9A-Za-z.+-]*)?)?$/;
+const SPINE_4_3: SpineGeneration = '4.3';
 
 type Json = Record<string, unknown>;
 
@@ -616,9 +633,54 @@ export function attachmentRegionJoins(raw: unknown): AttachmentRegionJoin[] {
   return joins;
 }
 
+/**
+ * The mesh keys the `source` branch never reaches — the geometry a linked mesh
+ * may state and nothing reads (issue #710).
+ *
+ * Derived from the branch rather than chosen. `readAttachment` returns at
+ * `SkeletonJson.js:586` as soon as `source` is truthy, and everything below that
+ * return reads `map.uvs` (twice: as the length handed to `readVertices` and as
+ * `regionUVs`), `map.triangles`, `map.edges` and `map.hull`. `vertices` is on the
+ * list because `readVertices` reads `map.vertices` and nothing else (`:654`), so
+ * it goes unread with the call that would have read it.
+ *
+ * ⚠️ `width` and `height` are NOT on this list, although `setSourceMesh`
+ * overwrites both with the source's (`MeshAttachment.js:102-103`). The branch
+ * reads them at `:569-570`, the format carries them on a link and rigc emits
+ * them (#691). A key the parser reads is not a key the parser ignores, whatever
+ * a later pass does with the value.
+ */
+const LINKED_MESH_UNREAD_KEYS = ['uvs', 'triangles', 'vertices', 'hull', 'edges'] as const;
+
+/** One linked mesh as the FILE spells it, before the loader has resolved anything. */
+interface RawLinkedMesh {
+  /** The placeholder of the mesh whose geometry this attachment draws. */
+  source: string;
+  /**
+   * The `skin` the entry states, or `undefined` for the parser's default — which
+   * is the DEFAULT skin and never the skin the link is written in (`:429`).
+   */
+  skin?: string;
+  /** The `slot` the entry states, or `undefined` for the parser's default: this attachment's own slot (`:573-579`). */
+  slot?: string;
+  /** Which of `LINKED_MESH_UNREAD_KEYS` this entry states, in that order. */
+  geometry: string[];
+  /**
+   * How big a mesh those keys describe — `uvs.length / 2` and
+   * `triangles.length / 3` — when the entry states them as arrays.
+   *
+   * Read so that the failure can put the shape the author wrote beside the shape
+   * the runtime draws. `undefined` where the file states the key as something
+   * other than an array, which is a file this rule refuses for the key rather
+   * than for its length.
+   */
+  statedVertices?: number;
+  statedTriangles?: number;
+}
+
 /**
  * `"<skin>\0<slot>\0<placeholder>" -> source` for every linked mesh the raw
- * skeleton declares (issue #691).
+ * skeleton declares, with what the file says about each one (issues #691, #710).
  *
  * 🔑 The test is the parser's own and it is not `type`: `type: "mesh"` and
  * `type: "linkedmesh"` share one branch and a truthy `source` is what decides
@@ -626,8 +688,8 @@ export function attachmentRegionJoins(raw: unknown): AttachmentRegionJoin[] {
  * there, so it is not a link here either — that map is read as an ordinary mesh,
  * which is exactly what the runtime does with it.
  */
-function rawLinkedMeshSources(raw: unknown): Map<string, string> {
-  const links = new Map<string, string>();
+function rawLinkedMeshes(raw: unknown): Map<string, RawLinkedMesh> {
+  const links = new Map<string, RawLinkedMesh>();
   if (!isObj(raw) || !Array.isArray(raw.skins)) return links;
   for (const skin of raw.skins as unknown[]) {
     if (!isObj(skin) || !isObj(skin.attachments)) continue;
@@ -640,7 +702,14 @@ function rawLinkedMeshSources(raw: unknown): Map<string, string> {
         if (type !== 'mesh' && type !== 'linkedmesh') continue;
         const source = entry.source;
         if (typeof source !== 'string' || source.length === 0) continue;
-        links.set(`${skinName}\u0000${slot}\u0000${placeholder}`, source);
+        links.set(`${skinName}\u0000${slot}\u0000${placeholder}`, {
+          source,
+          skin: typeof entry.skin === 'string' ? entry.skin : undefined,
+          slot: typeof entry.slot === 'string' ? entry.slot : undefined,
+          geometry: LINKED_MESH_UNREAD_KEYS.filter((key) => entry[key] !== undefined),
+          statedVertices: Array.isArray(entry.uvs) ? entry.uvs.length / 2 : undefined,
+          statedTriangles: Array.isArray(entry.triangles) ? entry.triangles.length / 3 : undefined,
+        });
       }
     }
   }
@@ -1585,7 +1654,7 @@ export function validate(input: ValidateInput): ValidateReport {
   // stay rejected.
   check('A16_SKELETON_VERSION_4_3', () => {
     const declared = isObj(raw?.skeleton) ? (raw.skeleton as Json).spine : undefined;
-    if (typeof declared !== 'string' || !SPINE_4_3_VERSION.test(declared)) {
+    if (typeof declared !== 'string' || spineGeneration(declared) !== SPINE_4_3) {
       fail(
         'A16_SKELETON_VERSION_4_3',
         `skeleton.spine is ${JSON.stringify(declared)}, expected 4.3, 4.3.<patch> or 4.3.<patch>-<suffix>`,
@@ -1596,9 +1665,11 @@ export function validate(input: ValidateInput): ValidateReport {
   // --- A01: no legacy top-level constraint arrays ---------------------------
   // 4.3 folds every constraint into one `constraints` array with a `type`.
   // A 4.1/4.2-shaped `physics` array loads clean and the constraint just
-  // vanishes.
+  // vanishes. ⭐ The list is `generation.ts`'s since #706, because `ingest` has
+  // to count the same arrays in a file it did not emit, and two copies of five
+  // names is how one of them comes to be four.
   check('A01_NO_LEGACY_TOPLEVEL_CONSTRAINT_ARRAYS', () => {
-    for (const key of ['ik', 'transform', 'path', 'physics', 'slider']) {
+    for (const key of TOPLEVEL_CONSTRAINT_ARRAYS) {
       if (raw && key in raw) {
         fail(
           'A01_NO_LEGACY_TOPLEVEL_CONSTRAINT_ARRAYS',
@@ -1610,11 +1681,12 @@ export function validate(input: ValidateInput): ValidateReport {
 
   // --- A02: no bone.transform key ------------------------------------------
   // 4.3 renamed it to `inherit`; the old key loads and silently falls back to
-  // Normal inheritance (case 6b).
+  // Normal inheritance (case 6b). The key itself is `generation.ts`'s, for
+  // A01's reason.
   check('A02_NO_BONE_TRANSFORM_KEY', () => {
     const bones = Array.isArray(raw?.bones) ? (raw.bones as unknown[]) : [];
     for (const bone of bones) {
-      if (isObj(bone) && 'transform' in bone) {
+      if (isObj(bone) && LEGACY_BONE_INHERIT_KEY in bone) {
         fail('A02_NO_BONE_TRANSFORM_KEY', `bone "${String(bone.name)}" uses 4.2's "transform"; 4.3 wants "inherit"`);
       }
     }
@@ -1689,8 +1761,8 @@ export function validate(input: ValidateInput): ValidateReport {
   let clippingCount = 0;
   const meshSlots = new Set<number>();
   /**
-   * The loaded mesh of every attachment the FILE spells as a link, to the
-   * `source` it names (issue #691).
+   * The loaded mesh of every attachment the FILE spells as a link, to what the
+   * file says about it (issues #691, #710).
    *
    * 🔑 Read off the raw JSON and joined by (skin, slot, placeholder) rather than
    * asked of the loaded object, because `MeshAttachment.sourceMesh` is **private
@@ -1703,11 +1775,23 @@ export function validate(input: ValidateInput): ValidateReport {
    * placeholder is unique only within one skin's slot and several skins fill
    * one — and every assertion downstream holds the attachment, not its address.
    */
-  const linkedMeshes = new Map<MeshAttachment, string>();
+  const linkedMeshes = new Map<MeshAttachment, RawLinkedMesh>();
+  /**
+   * The same pairing the other way round — join key -> the attachment the loader
+   * produced for it — which is what `A44` needs and `kindOf` does not.
+   *
+   * 🔑 Two maps rather than one because the two questions are different. Every
+   * rule that asks "is THIS attachment a link" holds the object and wants the
+   * file's word about it; `A44` walks the FILE's links and asks what the runtime
+   * made of each, including the answer "nothing" — a link whose region is
+   * missing loads as `null` and is in no skin at all (`A08` names that), so its
+   * join key is absent here while the file still declares it.
+   */
+  const loadedLinks = new Map<string, MeshAttachment>();
 
   if (skeletonData) {
     const data = skeletonData as NonNullable<typeof skeletonData>;
-    const rawLinks = rawLinkedMeshSources(raw);
+    const rawLinks = rawLinkedMeshes(raw);
     for (const skin of data.skins) {
       for (const entry of skin.getAttachments()) {
         const att = entry.attachment;
@@ -1715,8 +1799,12 @@ export function validate(input: ValidateInput): ValidateReport {
         else if (att instanceof MeshAttachment) {
           meshAttachments.push(att);
           meshSlots.add(entry.slotIndex);
-          const source = rawLinks.get(`${skin.name}\u0000${data.slots[entry.slotIndex].name}\u0000${entry.placeholder}`);
-          if (source !== undefined) linkedMeshes.set(att, source);
+          const join = `${skin.name}\u0000${data.slots[entry.slotIndex].name}\u0000${entry.placeholder}`;
+          const link = rawLinks.get(join);
+          if (link !== undefined) {
+            linkedMeshes.set(att, link);
+            loadedLinks.set(join, att);
+          }
         } else if (att instanceof ClippingAttachment) clippingCount++;
       }
     }
@@ -2097,7 +2185,7 @@ export function validate(input: ValidateInput): ValidateReport {
       list
         .filter((m) => kindOf(m) === 'authored')
         .map((m) => {
-          const source = linkedMeshes.get(m);
+          const source = linkedMeshes.get(m)?.source;
           return source === undefined ? `"${m.name}"` : `"${m.name}" (linked to "${source}")`;
         });
 
@@ -3859,6 +3947,70 @@ export function validate(input: ValidateInput): ValidateReport {
         }
       }
     });
+
+    // --- A44: a linked mesh states no geometry of its own ------------------
+    //
+    // 🚨 The one shape the parser reads in SILENCE. `readAttachment` returns from
+    // the `source` branch at `SkeletonJson.js:586`, before `map.uvs` is touched
+    // at all, so `uvs`, `triangles`, `vertices`, `hull` and `edges` written on a
+    // link are read by nothing — and `setSourceMesh` then fills the attachment
+    // with the SOURCE's arrays. The file says one mesh and every runtime draws
+    // another, which is why this is `validity` and not one renderer's policy.
+    //
+    // ⭐ **It is a separate assertion rather than a clause on A04, and the reason
+    // is measurable both ways.** A04 reads the LOADED attachment —
+    // `mesh.triangles`, `mesh.worldVerticesLength`, `mesh.vertices` — which on a
+    // link are the source's after `setSourceMesh`: measured on a forged link
+    // declaring 5 uvs and 3 triangles beside a 4-vertex source, A04 PASSED
+    // having read 8 and 2, the source's own. The keys this rule is about are not
+    // in the data A04 holds, so the clause would have had to reach for the raw
+    // file, and a verdict line reading A04's name would then be naming a
+    // measurement of the loaded geometry while deciding about file keys nothing
+    // read. The SKIP is the sharper half: A04's subject is mesh attachments, so
+    // on a rig with meshes and no link its subject is PRESENT and it passes —
+    // there is no verdict left for "this rig has no link to measure", and a
+    // clause that cannot report SKIP reports a pass for an absent subject, which
+    // this repository already has a judgment about.
+    //
+    // ⚠️ The subject is the FILE's links and not the loaded ones. A link whose
+    // region is missing loads as `null` and is in no skin (`A08` names it), so
+    // walking the loaded attachments would let the whole rule vanish on exactly
+    // the file that is already wrong.
+    check('A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN', () => {
+      if (rawLinks.size === 0) return skip('A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN', SKIP_NO_LINKED_MESH);
+      for (const [join, link] of rawLinks) {
+        if (link.geometry.length === 0) continue;
+        const [skinName, slotName, placeholder] = join.split('\u0000');
+        const at = `skin ${JSON.stringify(skinName)} slot ${JSON.stringify(slotName)} placeholder ${JSON.stringify(placeholder)}`;
+        const keys = link.geometry.map((key) => JSON.stringify(key)).join(', ');
+        // Where the parser looks for `source`, with the two defaults spelled out:
+        // an omitted `skin` is the DEFAULT skin rather than this attachment's own
+        // (`:429`), and an omitted `slot` IS this attachment's own (`:573-579`).
+        const where =
+          `skin ${JSON.stringify(link.skin ?? 'default')}${link.skin === undefined ? ' (the default skin, because no "skin" was stated — never the skin this attachment is written in)' : ''} ` +
+          `slot ${JSON.stringify(link.slot ?? slotName)}${link.slot === undefined ? ' (this attachment\'s own, because no "slot" was stated)' : ''}`;
+        // What the author's own keys describe, printed only when both are
+        // readable — the shape the file states, beside the shape it draws.
+        const states =
+          link.statedVertices === undefined || link.statedTriangles === undefined
+            ? ''
+            : ` (${link.statedVertices} vertices and ${link.statedTriangles} triangles)`;
+        const drawn = loadedLinks.get(join);
+        const loaded =
+          drawn === undefined
+            ? 'what it loaded is not shown here because the round trip produced no attachment for it (A00 owns that)'
+            : `it loaded ${drawn.worldVerticesLength / 2} vertices and ${drawn.triangles.length / 3} triangles`;
+        fail(
+          'A44_LINKED_MESH_STATES_NO_GEOMETRY_OF_ITS_OWN',
+          `${at} links to ${JSON.stringify(link.source)} and states ${keys}${states}, and a linked mesh has no geometry of ` +
+            'its own. The parser returns from the `source` branch before `readVertices` ' +
+            `(\`SkeletonJson.ts:582-586\`), so ${link.geometry.length === 1 ? 'that key is' : 'those keys are'} read by ` +
+            `nothing at all: what this attachment draws is the geometry of ${JSON.stringify(link.source)} in ${where}, and ` +
+            `${loaded}. Remove ${link.geometry.length === 1 ? 'it' : 'them'}, or remove "source" and author this as a ` +
+            'mesh of its own.',
+        );
+      }
+    });
   }
 
   // --- A06 / A17 / A19: the atlas against the PNGs on disk ------------------
@@ -4114,14 +4266,39 @@ export function validate(input: ValidateInput): ValidateReport {
         // `rotate: 270` and red at 0, 90 and 180 — this assertion's own verdict,
         // flipped by the rotation it does not judge (issue #579). The footprint
         // is `pageFootprint`'s, which every other reader of it now calls.
+        // 🚨 **The scan counts what it READ, and zero texels read is not a
+        // verdict** (issue #705). The `continue` above walks past every
+        // coordinate that is not on the page, so a rectangle none of whose
+        // texels are on it came out of this loop with `transparent` still
+        // false — indistinguishable from a solid drawing — and the sentence
+        // below then stated opacity over texels nobody had opened. Measured on
+        // a pack shaped like #707's: `part "block" is opaque in every one of
+        // its 12x8 texels`, over **0 of 96**, on art carrying 36 clear texels
+        // where it was packed. That is the message-as-UI defect in one line —
+        // the reader is sent to re-export a part whose alpha was never the
+        // problem, and the rectangle that is the problem belongs to A06.
+        //
+        // ⚠️ It is a FAIL rather than a SKIP, and the report's own shape
+        // decides that rather than taste. `skip()` is per ASSERTION, so
+        // skipping here would delete the verdicts on every other part of the
+        // page — on that same pack the second part is genuinely opaque and is
+        // named — and adding a skip BESIDE those failures puts A19 in two of
+        // the four buckets `reportLines` adds up, which prints `45 assertions`
+        // where the registry holds 44. What is left is a failure that says
+        // what was not measured, which is also what "green means measured"
+        // requires: a part this rule could not read must not be certified by
+        // it.
         const plate = readPlate(abs);
         for (const region of on) {
           if (baseRegions.has(region.name)) continue;
           const { width, height } = pageFootprint(region);
+          const declared = width * height;
+          let read = 0;
           let transparent = false;
           for (let y = region.y; y < region.y + height && !transparent; y++) {
             for (let x = region.x; x < region.x + width; x++) {
               if (x < 0 || y < 0 || x >= plate.width || y >= plate.height) continue;
+              read++;
               if (plate.get(x, y)[3] < 255) {
                 transparent = true;
                 break;
@@ -4129,12 +4306,37 @@ export function validate(input: ValidateInput): ValidateReport {
             }
           }
           if (transparent) continue;
+          // The page's size here is the DECODED image's and not the `size:`
+          // line's, because it is the bound this scan actually clipped
+          // against; where the two disagree A06 says so in its own sentence.
+          if (read === 0) {
+            fail(
+              'A19_OVERLAY_PNGS_HAVE_ALPHA',
+              `part "${region.name}" is not measured: this rule read 0 of the ${declared} texels of its ` +
+                `${width}x${height} rectangle at ${region.x},${region.y} on page "${page.name}", whose image is ` +
+                `${plate.width}x${plate.height}, so it states nothing about whether "${region.name}" can draw a ` +
+                "transparent pixel. A region's rectangle is A06_ATLAS_PAGE_SIZE_MATCHES_PNG's to judge, and one " +
+                'that runs off its page is refused there by name. This is renderer policy, and it belongs to ' +
+                '--profile spine-html: the default --profile spine does not run this check.',
+            );
+            continue;
+          }
+          // A rectangle partly on the page states the verdict over the texels
+          // it read and says how many of the declared ones that was. A whole
+          // rectangle prints the sentence it has always printed, to the byte.
+          const over =
+            read === declared
+              ? `every one of its ${width}x${height} texels on shared page "${page.name}"`
+              : `every one of the ${read} texels of its ${width}x${height} rectangle at ${region.x},${region.y} ` +
+                `that are on shared page "${page.name}", whose image is ${plate.width}x${plate.height} — the ` +
+                `other ${declared - read} of the ${declared} it declares are not on the page and are not ` +
+                'measured here';
           fail(
             'A19_OVERLAY_PNGS_HAVE_ALPHA',
-            `part "${region.name}" is opaque in every one of its ${width}x${height} texels on shared page ` +
-              `"${page.name}", so it would paint a solid rectangle over whatever is drawn behind it. Re-export ` +
-              `the part with transparency and pack again. ${exemption} This is renderer policy, and it belongs ` +
-              'to --profile spine-html: the default --profile spine does not run this check.',
+            `part "${region.name}" is opaque in ${over}, so it would paint a solid rectangle over whatever is ` +
+              `drawn behind it. Re-export the part with transparency and pack again. ${exemption} This is ` +
+              'renderer policy, and it belongs to --profile spine-html: the default --profile spine does not run ' +
+              'this check.',
           );
         }
         continue;