rig-c 0.0.0-stage → 2.20.4

package/src/assertions/bodies/a13.ts

@@ -0,0 +1,51 @@
+/**
+ * A13, the body (issue #1025, step 4c of #380): the mesh slots and each mesh's
+ * triangles stay within the budget the rig declares.
+ *
+ * Moved out of `src/validate.ts` unchanged but for what it reads: the meshes
+ * are a fact (`../facts/mesh_attachments.ts`) rather than the lists `validate()`'s
+ * prelude filled from spine-core's loaded skins, and the rig info is the
+ * caller's. Why the two budgets come from the rig and never from here stays
+ * above the `check` call in `validate()`.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { MeshFacts } from '../facts/mesh_attachments.ts';
+import { SKIP_NO_MESH_ATTACHMENT } from '../reasons.ts';
+import type { RigInfo } from '../../types.ts';
+
+export function a13MeshBudget({ fail, skip }: Verdicts, { meshes }: Pick<MeshFacts, 'meshes'>, input: { rig?: RigInfo }): void {
+  const meshAttachments = meshes;
+  const meshSlots = new Set(meshes.map((mesh) => mesh.slot));
+  const slotBudget = input.rig?.meshSlotBudget ?? null;
+  const triangleBudget = input.rig?.meshTriangleBudget ?? null;
+  if (slotBudget === null && triangleBudget === null) {
+    return skip(
+      'A13_MESH_BUDGET',
+      input.rig
+        ? `the rig "${input.rig.archetype}" declares no \`invariants.meshSlots\` or \`invariants.meshTriangles\` budget`
+        : 'no rig info (validating a bare directory), so no budget is declared',
+    );
+  }
+  // Two clauses and only one of them has a subject that can vanish (#580).
+  // A slot budget is a ceiling on a COUNT, and zero is a count — "this rig
+  // uses 0 of its 3 mesh slots" is a measurement — so that half holds on a
+  // skeleton with no mesh. A triangle budget is a ceiling on each mesh, so a
+  // rig that declares only that one and carries no mesh has measured
+  // nothing at all.
+  if (slotBudget === null && meshAttachments.length === 0) {
+    return skip(
+      'A13_MESH_BUDGET',
+      `the rig "${input.rig?.archetype}" budgets mesh triangles and nothing else, and ${SKIP_NO_MESH_ATTACHMENT}`,
+    );
+  }
+  if (slotBudget !== null && meshSlots.size > slotBudget) {
+    fail('A13_MESH_BUDGET', `${meshSlots.size} mesh slots, the rig budgets ${slotBudget}`);
+  }
+  if (triangleBudget === null) return;
+  for (const mesh of meshAttachments) {
+    const tris = (mesh.triangles?.length ?? 0) / 3;
+    if (tris > triangleBudget) {
+      fail('A13_MESH_BUDGET', `mesh "${mesh.name}" has ${tris} triangles, the rig budgets ${triangleBudget}`);
+    }
+  }
+}

package/src/assertions/bodies/a14.ts

@@ -0,0 +1,35 @@
+/**
+ * A14, the body (issue #1025, step 4c of #380): no mesh spans the whole
+ * stage.
+ *
+ * Moved out of `src/validate.ts` unchanged but for what it reads: the meshes
+ * and the stage are facts (`../facts/mesh_attachments.ts`, `../facts/stage.ts`)
+ * rather than spine-core's loaded skins and skeleton header. The `check` call
+ * stays in `validate()`.
+ */
+import type { Verdicts } from '../harness.ts';
+import type { MeshFacts } from '../facts/mesh_attachments.ts';
+import type { StageFacts } from '../facts/stage.ts';
+
+export function a14NoFullFrameMesh({ fail, skip }: Verdicts, { meshes }: Pick<MeshFacts, 'meshes'>, stage: StageFacts): void {
+  const meshAttachments = meshes;
+  const stageW = stage.width || 0;
+  const stageH = stage.height || 0;
+  // ⚠️ A stage-less skeleton has nothing for a mesh to span, and this rule
+  // used to report that as a PASS — the `stageW && stageH` guard below reads
+  // as a measurement of a 0x0 stage that no mesh can reach. It was only ever
+  // reachable from a foreign file until a rig spec could *declare* no stage
+  // (issue #578), and a pass certifying an unmeasured rig is the exact
+  // failure mode `A21_MESH_RIM_PINNED`'s `|| 'ring'` default was (#44).
+  if (!stageW || !stageH) {
+    return skip(
+      'A14_NO_FULL_FRAME_MESH',
+      'the skeleton declares no stage size, so there is no full frame for a mesh to span',
+    );
+  }
+  for (const mesh of meshAttachments) {
+    if (mesh.width >= stageW && mesh.height >= stageH) {
+      fail('A14_NO_FULL_FRAME_MESH', `mesh "${mesh.name}" spans the whole ${stageW}x${stageH} stage`);
+    }
+  }
+}

package/src/assertions/bodies/a15.ts

@@ -0,0 +1,97 @@
+/**
+ * A15, the body (issue #1025, step 4c of #380): `idle` keys no bone that
+ * drives a mesh, unless the rig declares that its idle deforms them.
+ *
+ * Moved out of `src/validate.ts` unchanged but for what it reads: the meshes
+ * and the bones that drive them are a fact (`../facts/mesh_attachments.ts`, the bones derived from the weights by `weightBonesOf`) rather
+ * than spine-core's loaded skins and the weight run decoded here, the bones
+ * `idle` keys are a fact (`../facts/animated_bones.ts`) rather than the raw
+ * JSON, and the rig info is the caller's. Why the rule assumes meshes are
+ * mostly static, and why a painting rig may say otherwise, stays above the
+ * `check` call in `validate()`.
+ */
+import type { Verdicts } from '../harness.ts';
+import { weightBonesOf, type MeshEntry, type MeshFacts } from '../facts/mesh_attachments.ts';
+import type { AnimatedBoneFacts } from '../facts/animated_bones.ts';
+import type { RigInfo } from '../../types.ts';
+
+export function a15IdleNoMeshBoneKeys({ fail, skip }: Verdicts, facts: MeshFacts, animated: AnimatedBoneFacts, input: { rig?: RigInfo }): void {
+  const A15 = 'A15_IDLE_NO_MESH_BONE_KEYS';
+  /**
+   * Every mesh attachment, loaded, with the bones that drive it — its slot's
+   * bone, and, once weights exist, every bone its weights name. A ring mesh
+   * is driven by its CONTROL bone, a different bone from the slot's, and
+   * checking only the slot bone would let `idle` key the one bone that
+   * actually dirties the canvas every frame.
+   */
+  const meshDrivers: Array<{ mesh: MeshEntry; bones: Set<string> }> = [];
+  for (const mesh of facts.meshes) {
+    const bones = new Set<string>([mesh.slotBone]);
+    for (const bone of weightBonesOf(facts, mesh)) bones.add(bone);
+    meshDrivers.push({ mesh, bones });
+  }
+  const meshBoneNames = new Set<string>();
+  for (const { bones } of meshDrivers) for (const name of bones) meshBoneNames.add(name);
+  const declared = input.rig?.idleDrivesMeshes ?? null;
+  /**
+   * A declaration that switches off nothing is refused rather than skipped,
+   * the standard `consumerDrivenMix` is held to: an opt-out that exempts
+   * nothing reads exactly like one that worked, and the next reader cannot
+   * tell the rig that needs it from the rig it was copied onto.
+   */
+  const stale = (why: string): void => {
+    fail(
+      A15,
+      `the rig "${input.rig?.archetype}" declares invariants.idleDrivesMeshes ("${declared}"), but ${why}, so the ` +
+        'declaration switches off nothing — remove it',
+    );
+  };
+  // The same shape as A06's and A17's guards, found by auditing for it
+  // (#568): a rig with no `idle` at all has nothing here to be wrong, and a
+  // rule that reports "held" over a subject that does not exist is the
+  // vacuous pass this file's own doctrine refuses. The two states get their
+  // own sentences because they are different absences — no such animation,
+  // versus one that keys no bone.
+  const idleBones = animated.bonesKeyedBy('idle');
+  if (idleBones === undefined) {
+    if (declared !== null) return stale('the skeleton declares no "idle" animation');
+    return skip(A15, 'the skeleton declares no "idle" animation, so nothing here can key a mesh-driving bone');
+  }
+  if (idleBones === null) {
+    if (declared !== null) return stale('"idle" carries no bone timeline at all');
+    return skip(A15, '"idle" carries no bone timeline at all, so there is no key to hold against the mesh-driving bones');
+  }
+  const keyed = idleBones.filter((name) => meshBoneNames.has(name));
+  if (declared !== null) {
+    if (keyed.length === 0) return stale('"idle" keys no bone that drives a mesh');
+    const keyedSet = new Set(keyed);
+    const moved = meshDrivers.filter(({ bones }) => [...bones].some((name) => keyedSet.has(name)));
+    // `worldVerticesLength` is two numbers per vertex whatever the encoding,
+    // which is the count the runtime recomputes; reading `vertices.length`
+    // would count a weighted mesh's bone entries instead.
+    const vertices = moved.reduce((sum, { mesh }) => sum + mesh.worldVerticesLength / 2, 0);
+    const SHOWN = 8;
+    const names =
+      keyed.slice(0, SHOWN).map((name) => `"${name}"`).join(', ') + (keyed.length > SHOWN ? ` +${keyed.length - SHOWN}` : '');
+    return skip(
+      A15,
+      `declared by the rig ("${declared}"): idle keys ${keyed.length} bone(s) that drive ${moved.length} mesh ` +
+        `attachment(s) totalling ${vertices} vertices — ${names} — and each of those meshes is recomputed on every ` +
+        'frame it is shown',
+    );
+  }
+  for (const [i, boneName] of keyed.entries()) {
+    // The case is named once, on the first line an agent reads, rather than
+    // after every bone: the first painting rig this met printed 42 of these,
+    // and 42 identical sentences read as 42 separate mistakes. It rides the
+    // first finding rather than being a finding of its own, so the count of
+    // FAIL lines is still the count of bones.
+    const hint =
+      i > 0
+        ? ''
+        : `. ${keyed.length} bone(s) keyed by idle drive meshes; if this idle is meant to deform them (a painting ` +
+          'rig), declare invariants.idleDrivesMeshes: { "why": … } in the rig spec — or, where the motion belongs to ' +
+          'a pivot above the mesh, key that pivot one link up (FACE.md §3)';
+    fail(A15, `idle keys bone "${boneName}", which drives a mesh — meshes never idle-skip${hint}`);
+  }
+}

package/src/assertions/bodies/a16.ts

@@ -0,0 +1,24 @@
+/**
+ * A16, 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 { spineGeneration, type SpineGeneration } from '../../generation.ts';
+import { isObj, type Json } from '../values.ts';
+
+const SPINE_4_3: SpineGeneration = '4.3';
+
+export function a16SkeletonVersion43({ fail }: Verdicts, raw: Json | null): void {
+  const declared = isObj(raw?.skeleton) ? (raw.skeleton as Json).spine : undefined;
+  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>`,
+    );
+  }
+}

package/src/assertions/bodies/a17.ts

@@ -0,0 +1,26 @@
+/**
+ * A17, the body (issue #1025, step 4c of #380): every page the atlas names is
+ * a file on disk, resolved against the directory the atlas sits in.
+ *
+ * Moved out of `src/validate.ts` unchanged but for what it reads: the pages are
+ * a fact (`../facts/atlas_pages.ts`), and the directory is the caller's. Why
+ * the guard is a SKIP and never a bare `return` (issues #568, #608) is argued
+ * above the `check` call in `validate()`, which stays there with A06 and A19.
+ */
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { Verdicts } from '../harness.ts';
+import type { AtlasPageFacts } from '../facts/atlas_pages.ts';
+import { SKIP_NO_ATLAS, SKIP_NO_ATLAS_PAGE } from '../reasons.ts';
+
+export function a17AtlasPageFilesExist({ fail, skip }: Verdicts, { atlas }: AtlasPageFacts, input: { atlasDir: string }): void {
+  if (!atlas) return skip('A17_ATLAS_PAGE_FILES_EXIST', SKIP_NO_ATLAS);
+  // The other absence, one ring in (#580): the atlas LOADED and declares no
+  // page, so there is no file to find missing. `!atlas` and "zero pages" print
+  // different reasons because they are different facts about the artifact.
+  if (atlas.pages.length === 0) return skip('A17_ATLAS_PAGE_FILES_EXIST', SKIP_NO_ATLAS_PAGE);
+  for (const page of atlas.pages) {
+    const abs = resolve(input.atlasDir, page.name);
+    if (!existsSync(abs)) fail('A17_ATLAS_PAGE_FILES_EXIST', `page "${page.name}" is not on disk at ${abs}`);
+  }
+}

package/src/assertions/bodies/a18.ts

@@ -0,0 +1,62 @@
+/**
+ * A18, the body (issue #1060, step 4e of #380): a second, independent compile
+ * writes the same model document, byte for byte.
+ *
+ * One body, two suppliers, as every moved assertion is — but split. The
+ * runtime's side (`validate()` in `src/validate.ts`) compares the second
+ * compile's Spine pair as well, `skeleton.json` and `skeleton.atlas`, and
+ * hands those findings over as `encoding`, in the order it always printed
+ * them; the model side (`../model/index.ts`) compares the document alone,
+ * which is all a build with no Spine pair writes (`cli_core.ts build`). So
+ * the model's clause is written once, here, and the two sides cannot spell it
+ * apart. When neither side was handed a second compile — a re-gate of files on
+ * disk — there is nothing determinate about a comparison that never ran, and
+ * it SKIPs with the reason the round trip always gave (the vacuous-pass trap
+ * `A09` is guarded against too).
+ *
+ * Moved out of `src/validate.ts` unchanged but for the seam; `firstDifferingLine`
+ * moved with it, the one reader of it.
+ */
+import type { Verdicts } from '../harness.ts';
+
+const A18 = 'A18_DETERMINISTIC_EMIT';
+
+/** What A18 reads: whether a second compile was handed over, the encoding's findings, and the two documents. */
+export interface DeterminismFacts {
+  /** Whether a second, independent compile was handed over — without one the assertion has nothing to compare. */
+  again: boolean;
+  /** The findings of the clauses only one side compares (the Spine pair, on the runtime's), each a detail, in the order they print. */
+  encoding: readonly string[];
+  /** The first compile's model document — `undefined` where the caller handed a second compile and no first document. */
+  first: string | undefined;
+  /** The second compile's model document; read only where `again`. */
+  second: string;
+}
+
+/**
+ * Where two texts first differ, as A18 names it: the 1-based line and each
+ * side's line, trimmed and cut to 120 characters.
+ */
+export function firstDifferingLine(first: string, second: string): string {
+  const a = first.split('\n');
+  const b = second.split('\n');
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i]) i += 1;
+  const cut = (line: string | undefined): string => (line === undefined ? '(end of text)' : JSON.stringify(line.trim().slice(0, 120)));
+  return `${i + 1}: ${cut(a[i])} first, ${cut(b[i])} second`;
+}
+
+export function a18DeterministicEmit({ fail, skip }: Verdicts, facts: DeterminismFacts): void {
+  if (!facts.again) return skip(A18, 'no second compile to compare against (re-gating artifacts on disk)');
+  for (const detail of facts.encoding) fail(A18, detail);
+  // The model document is compared like the Spine pair (issue #922): it is
+  // written beside them, and a map iterated in an order nothing fixed would
+  // reach it before it reached either of them — the document writes every
+  // `Map` of the model as an array in the map's order. On a build with no
+  // Spine pair it is the only artifact there is to compare.
+  if (facts.first === undefined) {
+    fail(A18, 'a second compile was handed over with no first model document to compare its skeleton.model.json against');
+  } else if (facts.second !== facts.first) {
+    fail(A18, `recompiling produced a different skeleton.model.json (first differing line ${firstDifferingLine(facts.first, facts.second)})`);
+  }
+}