rig-c 0.0.0-stage → 2.20.4

package/src/assertions/reasons.ts

@@ -0,0 +1,129 @@
+/**
+ * What a SKIP says, by what the assertion was denied (issues #568, #580, #608).
+ *
+ * Moved here from `src/validate.ts` by issue #1025 (step 4c of #380), words
+ * unchanged: an assertion body now lives in a module that links nothing from
+ * the runtime (`./bodies/`), and the bodies print these sentences on both
+ * sides — over what spine-core loaded and over the model document. A sentence
+ * kept in the file that links spine-core could not be read by the second.
+ * `src/validate.ts` re-exports every one, so nothing that imported them from
+ * there moves.
+ */
+
+/**
+ * What a SKIP says when `A00_ROUNDTRIP_PARSE` handed an assertion nothing to
+ * look at.
+ *
+ * Two of them rather than one, because what an assertion was denied is the whole
+ * content of its SKIP: `A20` wanted the loaded skeleton and `A06` wanted the
+ * loaded atlas, and a reader who is told which can tell a rule that is waiting
+ * on the parse from one that is waiting on the art. Both point at A00 instead of
+ * restating its detail, which the FAIL row prints in full.
+ *
+ * Exported so a control compares against them rather than quoting them — the
+ * same reason `ASSERTION_NAMES` is exported.
+ */
+export const SKIP_NO_SKELETON = 'the round trip did not produce a skeleton to measure (A00 owns that failure)';
+export const SKIP_NO_ATLAS = 'the round trip did not produce an atlas to measure (A00 owns that failure)';
+/**
+ * The third of them, and it is NOT waiting on A00 (issue #608): the atlas parsed
+ * and it has no pages, which is what a compile that measured no art writes. The
+ * four rules whose only subject is a page — A06, A17, A19, A27 — have nothing to
+ * look at, and an empty loop walking out of `check()` is reported as a PASS.
+ */
+/*
+ * **An empty subject list: SKIP or PASS, and which one is derived (issue #580).**
+ *
+ * `check()` records a pass when a body runs to its end without a `fail()` or a
+ * `skip()`, so a body whose main construct is a loop over a list that is EMPTY
+ * passes having measured nothing — the vacuous green one ring out from the bare
+ * `return` guards issue #568 converted. Two different things can be true of such
+ * a loop, and the criterion decides between them by reading the rule's own name
+ * and its `fail()` sentences rather than by preference:
+ *
+ *   * A name of the form ⟨subject⟩_⟨property⟩ — `REGION_WIDTH_HEIGHT_FINITE`,
+ *     `MESH_TRIANGLES_AND_ENCODING`, `PHYSICS_CONSTRAINT_EFFECTIVE`,
+ *     `ATLAS_PAGE_SIZE_MATCHES_PNG` — quantifies over the subject it names, and
+ *     its `fail()` names a member of that subject, the value found and the value
+ *     required. With no member, nothing was measured: it **SKIPs**, and the
+ *     reason names the subject that was absent.
+ *   * A name of the form NO_⟨construct⟩ — `NO_LEGACY_TOPLEVEL_CONSTRAINT_ARRAYS`,
+ *     `NO_BONE_TRANSFORM_KEY`, `NO_CLIPPING_ATTACHMENTS`, `NO_DARK_COLOR`,
+ *     `NO_FULL_FRAME_MESH` — quantifies over occurrences of something a correct
+ *     artifact has NONE of, and its `fail()` reports that the construct is
+ *     present rather than measuring a value on it. Zero occurrences IS the
+ *     measurement, so it **PASSes**: the loop is a search of the artifact, and
+ *     the artifact is what it measured.
+ *   * A name carrying both halves takes each at its word.
+ *     `A15_IDLE_NO_MESH_BONE_KEYS` is the pattern and already reads this way: no
+ *     `idle` animation, or an `idle` with no bone timeline, is the named subject
+ *     absent and SKIPs; no mesh-driving bone among the bones `idle` does key is
+ *     the construct absent and passes. `A10_NO_NAN_AFTER_STEPPING` was the same
+ *     shape until issue #902, and is the next bullet's now: #882 gave it a
+ *     setup-pose clause whose subject is the bones, beside the stepping clause
+ *     whose subject is the animations.
+ *   * An assertion with more than one clause SKIPs only when EVERY clause had
+ *     nothing to measure, which is the shape `A09`, `A33` and `A38` already
+ *     carry (`polygons.length === 0 && endsChecked === 0`), and `A10` since #902.
+ *     `A13_MESH_BUDGET` is why the clause is stated: a declared slot budget is
+ *     measured against a count of mesh slots, and zero is a count, so that half
+ *     passes on a rig with no mesh — while a rig that declares only a TRIANGLE
+ *     budget has nothing left to measure and skips.
+ *
+ * ⚠️ What the criterion is not allowed to become is a table of assertions with
+ * their verdicts written beside them. Every row above is decided by reading the
+ * name and the sentences the assertion already prints, so a rule added tomorrow
+ * is decided by the same reading and nobody re-opens this question.
+ */
+
+/**
+ * What a SKIP says when the artifact carries no member of the subject a rule
+ * quantifies over (issue #580), by subject.
+ *
+ * One constant per SUBJECT rather than one per assertion, for the reason the two
+ * above are two: what the rule was denied is the whole content of its SKIP, and
+ * three rules denied the same thing should say so in the same words. Exported so
+ * a control compares against them rather than quoting them.
+ */
+export const SKIP_NO_REGION_ATTACHMENT = 'the skeleton carries no region attachment';
+export const SKIP_NO_MESH_ATTACHMENT = 'the skeleton carries no mesh attachment';
+export const SKIP_NO_ANIMATION = 'the skeleton carries no animation';
+/**
+ * A10's (issue #902): its setup clause reads the bones and its stepping clause
+ * the animations, so it skips only when the skeleton carries neither — and the
+ * sentence is `SKIP_NO_ANIMATION`'s with the second subject added, so the two
+ * cannot drift into different words for the same absence.
+ */
+export const SKIP_NO_POSE = `${SKIP_NO_ANIMATION} and no bone, so there is no setup pose to read and nothing to step`;
+export const SKIP_NO_TIMELINE = 'no animation here carries a timeline';
+export const SKIP_NO_PHYSICS_CONSTRAINT = 'the skeleton declares no physics constraint';
+export const SKIP_NO_ATLAS_PAGE = 'the atlas declares no page';
+export const SKIP_NO_ATLAS_REGION = 'the atlas declares no region';
+/** A49's (issue #1099): the subject is a pair of regions on one page, and an atlas of one-region pages carries none. */
+export const SKIP_NO_ATLAS_REGION_PAIR = 'no page of the atlas carries two regions, so there is no pair of footprints to hold apart';
+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" or "rgb2" timeline, so there is no two-colour tint to read back';
+export const SKIP_NO_SEPARABLE_COLOR =
+  'no animation keys an "rgb" or "alpha" timeline, so there is no separable slot colour to read back';
+export const SKIP_NO_LINKED_MESH = 'no attachment in this skeleton takes its geometry from another one';
+export const SKIP_NO_SEQUENCE =
+  'no attachment carries a "sequence" block and no animation keys a "sequence" timeline, so there is no numbered series to read back';
+/**
+ * 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
+ * eight constants and quotes the ninth is a control with a hand-kept exception
+ * in it.
+ */
+export const SKIP_NO_DECLARED_DURATION =
+  'the motion spec declares no animations and the skeleton has none — a static rig has no duration to compare';
+
+/**
+ * The model side's `SKIP_NO_SKELETON` (issue #1025): the reader refused the
+ * document, or the document names a region its pages lack, so a body that
+ * reads the model has nothing to read. It names the two model-side parse
+ * rules rather than A00, because on this side there is no round trip — the
+ * reader and the region rule are what stand in its place (`./model/parse.ts`).
+ */
+export const SKIP_NO_MODEL = 'the model side read no document to measure (A00_MODEL_READ or A00_MODEL_REGIONS_ON_PAGES owns that failure)';

package/src/assertions/region_lookups.ts

@@ -0,0 +1,61 @@
+/**
+ * The region names one skin entry will make a loader look up (issue #1025,
+ * step 4c of #380) — moved here from `src/validate.ts` unchanged, because A08's
+ * body now runs on both sides and the model side links nothing from the
+ * runtime. `src/validate.ts` re-exports both names, so nothing that imported
+ * them from there moves.
+ */
+import { frameRegionName } from '../core/uvs.ts';
+import { isObj } from './values.ts';
+
+/**
+ * The atlas region names one raw skin entry will make the loader look up — or
+ * `null` when the file states a sequence this walk cannot predict.
+ *
+ * ⚠️ Measured against the loader rather than reasoned out, because a join that
+ * merely looks right is the thing A08 exists to refuse. `readSequence`
+ * (`dist/SkeletonJson.js:641-649`) turns an absent or null `sequence` into
+ * `new Sequence(1, false)` — one lookup, at the bare path — and a present one
+ * into `new Sequence(count ?? 0, true)`, so a sequence map with no `count`
+ * looks up nothing at all. Each frame's name is the core's `frameRegionName`
+ * (`src/core/uvs.ts`): `start + i`, left-padded with zeros to `digits`, after
+ * the path (issue #1015). `PS127` records what the loader asks for and compares,
+ * and the core suite holds the frame names to `Sequence.getPath` over 7,680
+ * cases.
+ *
+ * Nothing in `examples/` carries a `sequence` (measured: 0 occurrences across
+ * all twelve editor exports), so without this the assertion would have read a
+ * sequence's base path as a region name and refused correct foreign data —
+ * `A21_MESH_RIM_PINNED`'s old `|| 'ring'` default, one file over.
+ */
+export function attachmentRegionLookups(sequence: unknown, path: string): string[] | null {
+  if (sequence === undefined || sequence === null) return [path];
+  if (!isObj(sequence)) return null;
+  const whole = (value: unknown, fallback: number): number | null => {
+    if (value === undefined) return fallback;
+    return typeof value === 'number' && Number.isInteger(value) ? value : null;
+  };
+  const count = whole(sequence.count, 0);
+  const start = whole(sequence.start, 1);
+  const digits = whole(sequence.digits, 0);
+  if (count === null || start === null || digits === null || count < 0) return null;
+  const series = { count, start, digits, setup: 0 };
+  const lookups: string[] = [];
+  for (let i = 0; i < count; i++) lookups.push(frameRegionName(path, series, i));
+  return lookups;
+}
+
+/** One skin entry's join onto the atlas, as the loader will perform it. */
+export interface AttachmentRegionJoin {
+  skin: string;
+  slot: string;
+  placeholder: string;
+  /** The attachment's own name — the entry's `name` when it states one, else the placeholder. */
+  name: string;
+  /**
+   * Every atlas region name the loader will ask this atlas for, in the order it
+   * asks. Empty for a `sequence` with no `count`, and `null` for a sequence map
+   * this walk will not guess at.
+   */
+  lookups: string[] | null;
+}

package/src/assertions/report.ts

@@ -0,0 +1,189 @@
+/**
+ * The profiles a gate judges under, the one the CLI uses when `--profile` is
+ * absent, and the printer of a gate's report — moved here unchanged from
+ * `src/validate.ts` (issue #1060), which re-exports all three: the entry that
+ * links none of spine-core gates a build on the model side
+ * (`./model/index.ts`) and prints its report with the same printer, and
+ * `src/validate.ts` links the runtime. Nothing here links it.
+ */
+import type { AssertionProfile } from './kinds.ts';
+import type { VerdictLists } from './harness.ts';
+
+export const VALIDATE_PROFILES: readonly AssertionProfile[] = ['spine', 'spine-html'];
+
+/**
+ * What the CLI uses when `--profile` is absent — and ONLY the CLI. This is not
+ * `validate()`'s default; that function has none (`ValidateProfile` in
+ * `src/validate.ts` says why).
+ *
+ * `spine` since issue #221. The published package's pitch is "the output imports
+ * into the Spine editor", which is exactly the question `spine` asks, and a
+ * stranger's first build was being judged instead against one renderer's policy
+ * and one project's canvas budget — 14 rules they have no stake in, with the
+ * escape hatch documented only in prose. Defaults beat prose. `spine-html` is
+ * still one flag away, and every report names the profile that judged it.
+ */
+export const CLI_DEFAULT_PROFILE: AssertionProfile = 'spine';
+
+export function reportLines(report: VerdictLists & { profile: AssertionProfile }): string[] {
+  const lines: string[] = [];
+  // The profile goes FIRST and names what it left out. A report that says
+  // "green" without saying which rulebook produced it is the one thing this
+  // switch could make worse than no switch: `--profile spine` green means
+  // "valid Spine", never "passes the renderer policy".
+  const renderer = report.profileSkipped.filter((p) => p.kind === 'renderer').length;
+  const archetype = report.profileSkipped.filter((p) => p.kind === 'archetype').length;
+  lines.push(
+    report.profileSkipped.length === 0
+      ? `  ..    profile ${report.profile} — every assertion applies`
+      : `  ..    profile ${report.profile} — ${renderer} renderer-policy and ${archetype} archetype assertion(s) do not apply`,
+  );
+  for (const name of report.passed) lines.push(`  PASS  ${name}`);
+  for (const s of report.skipped) lines.push(`  SKIP  ${s.assertion}: ${s.reason}`);
+  for (const p of report.profileSkipped) lines.push(`  PROF  ${p.assertion}: ${p.kind} rule, not in profile "${report.profile}"`);
+  for (const f of report.failures) lines.push(`  FAIL  ${f.assertion}: ${f.detail}`);
+  // How many of them MEASURED anything, which is the figure the rows above do
+  // not hand a reader (issue #568). Counting `PASS` lines answers a different
+  // question — before the sweep that closed #568 a run could print seven of
+  // them over a candidate on which five rules had not executed at all.
+  //
+  // ⚠️ Every figure here is a count of ASSERTIONS and not of rows, which is why
+  // the failed side is a Set: `fail()` is called once per finding, so one
+  // assertion can print six `FAIL` lines, and a line-count would report 47 of
+  // 42. The four buckets partition `ASSERTION_NAMES`, so the total is derived
+  // by adding them rather than stated — a `42` written here would be the one
+  // number in the report that no run could contradict.
+  //
+  // The figures are `gateSummary`'s, the one computation the line and the
+  // `--report` document (`buildReportGate`) both spell (issue #1213).
+  const s = gateSummary(report);
+  lines.push(
+    `  ..    ${s.assertions} assertions: ${s.measured} measured (${s.passed} passed, ${s.failed} failed), ` +
+      `${s.skipped} skipped, ${s.notInProfile} not in profile "${s.profile}"`,
+  );
+  return lines;
+}
+
+/**
+ * The figures the summary line states, as values: what `reportLines` prints
+ * as its last line and what the `--report` document carries as a gate's
+ * `summary` — one computation, so the two cannot disagree. Every figure counts
+ * assertions, not rows (the comment in `reportLines` says why `failed` is a
+ * set), and `assertions` is the sum of the four buckets, never a constant.
+ */
+export interface GateSummary {
+  assertions: number;
+  measured: number;
+  passed: number;
+  failed: number;
+  skipped: number;
+  notInProfile: number;
+  profile: AssertionProfile;
+}
+
+export function gateSummary(report: VerdictLists & { profile: AssertionProfile }): GateSummary {
+  const failed = new Set(report.failures.map((f) => f.assertion)).size;
+  const measured = report.passed.length + failed;
+  return {
+    assertions: measured + report.skipped.length + report.profileSkipped.length,
+    measured,
+    passed: report.passed.length,
+    failed,
+    skipped: report.skipped.length,
+    notInProfile: report.profileSkipped.length,
+    profile: report.profile,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// the build report document (`--report <file>`, issue #1213)
+// ---------------------------------------------------------------------------
+
+/**
+ * The `spec` of the document `build --report` and `repack --report` write.
+ * Versioned and additive: a field is added under the same spec, and one that
+ * changes meaning or goes away moves the spec — a dependant that read `/1`
+ * keeps reading what `/1` promised.
+ */
+export const BUILD_REPORT_SPEC = 'build-report/1';
+
+/** Which supplier judged the gates: the round trip through spine-core (`cli.ts`) or the model side and the rules restated over the emitted text (`cli_core.ts`). */
+export type BuildReportSupplier = 'round-trip' | 'model';
+
+/**
+ * The core entry's `here:` line as values: how many rules ran on the model
+ * side over the document, how many of the round trip's own were restated over
+ * the emitted text, and the codes that did not run. `null` on the round trip,
+ * which prints no such line.
+ */
+export interface GateHere {
+  modelSide: number;
+  restated: number;
+  notRun: string[];
+}
+
+/**
+ * What one gate's report states, as values: the rows a reader takes off the
+ * `PASS`, `SKIP` and `FAIL` lines (the rule names, the SKIP reasons, the FAIL
+ * details, each in the order printed), the summary line's figures, the stats
+ * line's keys and values, and the core entry's `here:` line. A `PROF` row is
+ * counted in `summary.notInProfile` and not listed: nothing reads its row.
+ */
+export interface BuildReportGate {
+  /** `compiled` for the gate over the compile, `packed` for `--pack`'s second gate over the pages on disk. */
+  atlas: 'compiled' | 'packed';
+  passed: string[];
+  skipped: Array<{ code: string; reason: string }>;
+  failures: Array<{ code: string; detail: string }>;
+  summary: GateSummary;
+  stats: Record<string, number | string>;
+  here: GateHere | null;
+}
+
+/**
+ * One `pack:` line as values. `coveredPct` is the figure the line prints, at
+ * its one decimal; `pageEdges` is the `--page-edges` the build packed under,
+ * which the line states as `, page edges free` or by its absence.
+ */
+export interface PackPageFigures {
+  page: string;
+  width: number;
+  height: number;
+  regions: number;
+  coveredPct: number;
+  padding: number;
+  pageEdges: 'pot' | 'free';
+  packShape: 'rect' | 'polygon';
+}
+
+/** The document, keys in the order written. Nothing in it is a time, a path or a machine's: two reports of one build are byte-identical. */
+export interface BuildReportDocument {
+  spec: typeof BUILD_REPORT_SPEC;
+  command: 'build' | 'repack';
+  supplier: BuildReportSupplier;
+  gates: BuildReportGate[];
+  /** Every `pack:` line, in the order printed; `null` for a build that did not pack. */
+  pack: PackPageFigures[] | null;
+}
+
+/** One gate's report as the document carries it — read off the lists `reportLines` prints, so a row is in the document exactly when its line is printed. */
+export function buildReportGate(
+  atlas: BuildReportGate['atlas'],
+  report: VerdictLists & { profile: AssertionProfile },
+  here: GateHere | null,
+): BuildReportGate {
+  return {
+    atlas,
+    passed: [...report.passed],
+    skipped: report.skipped.map((s) => ({ code: s.assertion, reason: s.reason })),
+    failures: report.failures.map((f) => ({ code: f.assertion, detail: f.detail })),
+    summary: gateSummary(report),
+    stats: { ...report.stats },
+    here,
+  };
+}
+
+/** The document's text: two-space JSON and a final newline, keys in the order `BuildReportDocument` states them. */
+export function buildReportText(doc: BuildReportDocument): string {
+  return `${JSON.stringify(doc, null, 2)}\n`;
+}

package/src/assertions/values.ts

@@ -0,0 +1,39 @@
+/**
+ * How an assertion body reads a value — the helpers the bodies under
+ * `./bodies/` share with the ones still in `src/validate.ts` (issue #1025,
+ * step 4c of #380), moved here unchanged so both read a value one way. Links
+ * nothing from the runtime.
+ */
+
+/** A JSON object as `JSON.parse` returns it. */
+export type Json = Record<string, unknown>;
+
+/** A JSON object, and not an array or `null`. */
+export function isObj(v: unknown): v is Json {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * The time to pose a key at so that the runtime is AT it: the later of the
+ * file's number and that number as spine-core stores it (issue #771).
+ *
+ * 🚨 Every timeline keeps its key times in a `Float32Array`
+ * (`Utils.newFloatArray`), and a key time the float cannot hold exactly is
+ * stored at the nearest one — for `0.2`, `0.20000000298…`, which is LATER than
+ * the double `0.2`. Stepped to the file's own number, a timeline is then just
+ * BEFORE its key: before a first key it writes the setup value (`time <
+ * frames[0]`), and past a stepped key it still holds the one before
+ * (`frames[i] > time`). That is a pose one float step from the key, not the
+ * key's — measured on the selftest's own `ingest_probe`, whose `alpha` key at
+ * 0.2 posed the setup 1.0 and was refused as `the key states value 0.4`.
+ *
+ * ⚠️ The later of the two rather than `Math.fround` alone: where the float
+ * rounds DOWN, the file's number is already past the stored key, and a runtime
+ * built without typed arrays stores the double itself — in both, the file's
+ * number is the one at or after the key. What a key time rounds to is the
+ * runtime's storage and not the file's statement, so a rule judging what a KEY
+ * states poses at the key; the rounding itself is nothing an author can repair.
+ */
+export function atStoredKey(time: number): number {
+  return Math.max(time, Math.fround(time));
+}