spine-rigc 1.9.3 → 2.0.0

package/src/assertions/emitted/index.ts

@@ -0,0 +1,119 @@
+/**
+ * The round trip's rules, restated over the text rigc emitted (issue #1060,
+ * step 4e of #380) — the half of the gate the entry that links none of
+ * spine-core runs beside the model side (`../model/index.ts`).
+ *
+ * ⭐ **Every one of the 49 is accounted for, by name.** The model side runs
+ * the moved assertions (`MOVED_ASSERTIONS`) over the document. What is left —
+ * the complement, read off `ASSERTION_KIND` rather than listed — is the
+ * round trip's own: A00, A01, A02, A05, A07, A16, A18, A31, A35 at the time of
+ * writing. Each of those but one reads the raw text, not what spine-core
+ * loaded: the atlas's line layout (A07), the skeleton JSON's draw-order
+ * offsets, deform runs, version label, legacy arrays, legacy bone key and
+ * curve arrays (A31, A35, A16, A01, A02, A05), and A18's second compile. So
+ * each is restated here over the same text, by a body under `../bodies/` that
+ * is the round trip's clause word for word, and prints the round trip's line
+ * (`RC28` holds the two on every recipe and on each assertion's mutants).
+ * The one that cannot be is **A00**: it is spine-core's parser loading the
+ * pair, and there is no second reader of the format to stand in for it. It
+ * SKIPs, naming spine-core and where the round trip does run — never a PASS
+ * on nothing. A code the complement grows by that this file does not know is
+ * an internal error, so a new round-trip rule cannot go unrun here in silence.
+ *
+ * Links nothing from the runtime.
+ */
+import { ASSERTION_KIND, type AssertionProfile } from '../kinds.ts';
+import { verdictHarness, type VerdictLists } from '../harness.ts';
+import { MOVED_ASSERTIONS } from '../model/index.ts';
+import type { Verdicts } from '../harness.ts';
+import type { Json } from '../values.ts';
+import { a01NoLegacyToplevelConstraintArrays } from '../bodies/a01.ts';
+import { a02NoBoneTransformKey } from '../bodies/a02.ts';
+import { a05CurveArrayLength } from '../bodies/a05.ts';
+import { a07AtlasTextShape } from '../bodies/a07.ts';
+import { a16SkeletonVersion43 } from '../bodies/a16.ts';
+import { a18DeterministicEmit } from '../bodies/a18.ts';
+import { a31DrawOrderOffsetsResolve } from '../bodies/a31.ts';
+import { a35DeformKeysFitTheAttachment } from '../bodies/a35.ts';
+
+/** What the restated rules read: the emitted texts, the document written beside them, and a second compile's three. */
+export interface EmittedTextInput {
+  skeletonText: string;
+  atlasText: string;
+  /** The document `build` writes — A18 compares it with the second compile's. */
+  modelText: string;
+  /** A second, independent compile's texts; absent, A18 SKIPs as the round trip's does on a re-gate. */
+  reEmit?: { skeletonText: string; atlasText: string; modelText: string };
+  profile: AssertionProfile;
+}
+
+/** The emitted texts as the bodies read them: the skeleton JSON parsed, or `null` where it does not parse. */
+interface EmittedTexts {
+  raw: Json | null;
+  input: EmittedTextInput;
+}
+
+/** A00's SKIP here: what did not run, and where it does. */
+export const SKIP_NO_ROUND_TRIP =
+  "spine-core's parser is the subject of this rule and this entry links none of it — `bun cli.ts build` and `rigc validate` run the round trip, and the selftest and CI run it on every corpus build";
+
+/** The code this file SKIPs rather than restates. */
+const A00 = 'A00_ROUNDTRIP_PARSE';
+
+/**
+ * The restated rules, in `validate()`'s report order — A00's place among them
+ * (after A35, before A16) is the round trip's, so the report reads in the order
+ * the round trip's does.
+ */
+export const EMITTED_TEXT_RULES: ReadonlyArray<{ code: string; run: (v: Verdicts, texts: EmittedTexts) => void }> = [
+  { code: 'A07_ATLAS_TEXT_SHAPE', run: (v, t) => a07AtlasTextShape(v, t.input.atlasText) },
+  { code: 'A31_DRAW_ORDER_OFFSETS_RESOLVE', run: (v, t) => a31DrawOrderOffsetsResolve(v, t.raw) },
+  { code: 'A35_DEFORM_KEYS_FIT_THE_ATTACHMENT', run: (v, t) => a35DeformKeysFitTheAttachment(v, t.raw) },
+  { code: A00, run: (v) => v.skip(A00, SKIP_NO_ROUND_TRIP) },
+  { code: 'A16_SKELETON_VERSION_4_3', run: (v, t) => a16SkeletonVersion43(v, t.raw) },
+  { code: 'A01_NO_LEGACY_TOPLEVEL_CONSTRAINT_ARRAYS', run: (v, t) => a01NoLegacyToplevelConstraintArrays(v, t.raw) },
+  { code: 'A02_NO_BONE_TRANSFORM_KEY', run: (v, t) => a02NoBoneTransformKey(v, t.raw) },
+  { code: 'A05_CURVE_ARRAY_LENGTH', run: (v, t) => a05CurveArrayLength(v, t.raw) },
+  {
+    code: 'A18_DETERMINISTIC_EMIT',
+    run: (v, { input }) => {
+      const again = input.reEmit;
+      const encoding =
+        again === undefined
+          ? []
+          : [
+              ...(again.skeletonText !== input.skeletonText ? ['recompiling produced a different skeleton.json'] : []),
+              ...(again.atlasText !== input.atlasText ? ['recompiling produced a different skeleton.atlas'] : []),
+            ];
+      a18DeterministicEmit(v, { again: again !== undefined, encoding, first: input.modelText, second: again?.modelText ?? '' });
+    },
+  },
+];
+
+/** Every code the model side does not run, read off the registry — what this file must account for. */
+export function roundTripOnlyCodes(): string[] {
+  const moved = new Set(MOVED_ASSERTIONS.map((m) => m.code));
+  return Object.keys(ASSERTION_KIND).filter((code) => !moved.has(code));
+}
+
+/** The restated rules over one build's emitted texts, in `validate()`'s report shape. */
+export function validateEmittedText(input: EmittedTextInput): VerdictLists & { profile: AssertionProfile } {
+  const known = new Set(EMITTED_TEXT_RULES.map((r) => r.code));
+  const unrun = roundTripOnlyCodes().filter((code) => !known.has(code));
+  if (unrun.length > 0) {
+    throw new Error(`internal: ${unrun.join(', ')} runs on neither side here — the model side does not run it and src/assertions/emitted/index.ts neither restates nor SKIPs it`);
+  }
+  const h = verdictHarness(input.profile, ASSERTION_KIND, 'the emitted text');
+  let raw: Json | null = null;
+  try {
+    raw = JSON.parse(input.skeletonText) as Json;
+  } catch (err) {
+    h.fail(A00, `skeleton JSON is not parseable: ${(err as Error).message}`);
+  }
+  for (const rule of EMITTED_TEXT_RULES) {
+    if (rule.code === A00 && raw === null) continue;
+    h.check(rule.code, () => rule.run(h.verdicts, { raw, input }));
+  }
+  const { failures, passed, skipped, profileSkipped, stats } = h;
+  return { failures, passed, skipped, profileSkipped, stats, profile: input.profile };
+}

package/src/assertions/report.ts

@@ -0,0 +1,64 @@
+/**
+ * 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.
+  const failed = new Set(report.failures.map((f) => f.assertion));
+  const measured = report.passed.length + failed.size;
+  const total = measured + report.skipped.length + report.profileSkipped.length;
+  lines.push(
+    `  ..    ${total} assertions: ${measured} measured (${report.passed.length} passed, ${failed.size} failed), ` +
+      `${report.skipped.length} skipped, ${report.profileSkipped.length} not in profile "${report.profile}"`,
+  );
+  return lines;
+}

package/src/cli/core_commands.ts

@@ -3,7 +3,9 @@
  * `ingest`, `diff`, `check`, `render`, `pose`, `chainfit` and `skills` —
  * moved here unchanged from `cli.ts` (issue #1052, step 4e of #380), with the
  * helpers only they call. Both entries register them (`CORE_COMMAND_RUNS`):
- * `cli.ts` beside the runtime's, `cli_core.ts` alone.
+ * `cli.ts` beside the runtime's, `cli_core.ts` alone. And the body
+ * `cli_core.ts` runs as `build` (`CORE_ENTRY_RUNS`, issue #1060): `runBuild`
+ * with a gate that links none of the runtime.
  *
  * Which commands these are is not a list kept here: it is `COMMANDS`'s
  * `runtime` field (`./shared.ts`), which `RC26` in `selftest.ts` holds to the
@@ -12,6 +14,9 @@
  * absent, which `RC24` runs.
  */
 import { parseAtlasText } from '../atlas.ts';
+import { validateEmittedText } from '../assertions/emitted/index.ts';
+import { validateModel } from '../assertions/model/index.ts';
+import { reportLines } from '../assertions/report.ts';
 import { chainFitLines, type ChainFitOptions, estimateChainFit } from '../chainfit.ts';
 import { checkLines, CheckPlates } from '../check.ts';
 import { writeCheckPictures } from '../checkpics.ts';
@@ -29,7 +34,7 @@ import { estimatePose, poseLines, type PoseOptions } from '../pose.ts';
 import { BACKGROUND, contactSheet, type Frame, FRAMES_SIDECAR, FRAMES_SPEC, type FrameSet, type FramesSidecar, framingViewport, GEOMETRY_FILE, geometryFileOf, geometryText, loadCandidate, POSER_NAMES, type PoserName, PROTOCOL_FPS, refuseUnchosen, renderFrame, sampleAll, sampleAnimation, SETUP_POSE_DIR, SHEET_FILE, SHEET_TILE, sidecarViewport, type SkeletonFacts, type SlotSubset, SlotSubsetError, throughPoser } from '../render_shared.ts';
 import { type CompileResult } from '../types.ts';
 import { attachmentRegionJoins } from '../region_joins.ts';
-import { ATLAS_ABSENT, COMMANDS, type CommandRun, PACKAGE_ROOT, DEFAULT_CHAINFIT_OUT, DEFAULT_POSE_OUT, DEFAULT_SKILLS_DIR, ExplainError, meshBudget, meshDepthNote, meshFit, meshInfluenceNote, PAGE_GRID_UNLOCATED, readAnimationFlag, readJsonFile, readPoserFlag, readSkeletonText, readVersion, resolveCut, resolveDrawable, runCheck, SkillsInstallError, STAGELESS_FRAMING, UsageError, writeJson } from './shared.ts';
+import { ATLAS_ABSENT, COMMANDS, type CommandRun, resolveBuild, type BuildGate, runBuild, PACKAGE_ROOT, DEFAULT_CHAINFIT_OUT, DEFAULT_POSE_OUT, DEFAULT_SKILLS_DIR, ExplainError, meshBudget, meshDepthNote, meshFit, meshInfluenceNote, PAGE_GRID_UNLOCATED, readAnimationFlag, readJsonFile, readPoserFlag, readSkeletonText, readVersion, resolveCut, resolveDrawable, runCheck, SkillsInstallError, STAGELESS_FRAMING, UsageError, writeJson } from './shared.ts';
 import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 
@@ -321,11 +326,17 @@ function readAnimationPairs(values: string[], candidate: unknown, reference: unk
 export 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);
-  const referencePath = resolve(reference);
-  for (const path of [candidatePath, referencePath]) {
-    if (!existsSync(path)) throw new UsageError(`nothing at ${path}`);
-  }
+  // A file is read as the JSON it is; a directory is a build, and its skeleton is what is compared — through the one
+  // statement of a build (issue #1046), which refuses a directory holding none. A directory used to reach the JSON
+  // reader and die on an EISDIR and a stack.
+  const skeletonAt = (path: string): string => {
+    const at = resolve(path);
+    if (existsSync(at) && statSync(at).isDirectory()) return resolveBuild(at, undefined).skeletonPath;
+    if (!existsSync(at)) throw new UsageError(`nothing at ${at}`);
+    return at;
+  };
+  const candidatePath = skeletonAt(candidate);
+  const referencePath = skeletonAt(reference);
   const candidateJson = readJsonFile(candidatePath);
   const referenceJson = readJsonFile(referencePath);
   const animationPairs = readAnimationPairs(lists.as ?? [], candidateJson, referenceJson);
@@ -696,6 +707,9 @@ export function cmdChainFit(flags: Record<string, string>): void {
         'skeleton is all it needs of the candidate. Drop --atlas',
     );
   }
+  // The candidate through the one statement of a build (issue #1046): a path, or a directory holding no skeleton.json,
+  // is refused here as by every command that takes a build, rather than by `src/chainfit.ts`'s own reader in its own words.
+  resolveBuild(flags.candidate, undefined);
   const options: ChainFitOptions = {
     candidatePath: flags.candidate,
     imagesDir: flags.images,
@@ -1515,6 +1529,67 @@ export function cmdSkills(flags: Record<string, string>, positional: string[]):
   );
 }
 
+// ---------------------------------------------------------------------------
+// build — the second entry's gate (issue #1060, step 4e of #380)
+// ---------------------------------------------------------------------------
+
+/**
+ * The gate `cli_core.ts build` runs (`BuildGate`), where `cli.ts build` runs
+ * the round trip: the model side over the document (`validateModel`), and the
+ * round trip's own rules restated over the text the emitter wrote
+ * (`validateEmittedText`) — A18 among them, comparing a second, independent
+ * compile's skeleton, atlas and document byte for byte — with A00, spine-core's
+ * parse, a SKIP naming it. One report, printed by the printer `cli.ts build`
+ * prints with, and a line saying which rules ran here and which did not.
+ *
+ * ⚠️ The document the model side reads is the one this gate judges: spelled
+ * from the atlas text the gate is handed, so under `--copy-images` it names
+ * the pages where the compile measured them — the files the round trip's own
+ * A17 reads on `cli.ts` — and A18 compares the documents as written, the
+ * copies' names in them. Under `--pack` the two are one text.
+ */
+const MODEL_AND_TEXT_GATE: BuildGate = {
+  heading: (profile) =>
+    `  ..    validate (the model side over the document + the round trip's rules restated over the emitted text, profile ${profile}; this entry links no spine-core, so the round trip does not run)`,
+  run: ({ result, atlasText, atlasDir, modelText, reEmit, profile }) => {
+    const model = validateModel({ modelText: modelDocument(result.model, result.skeletonText, atlasText), atlasDir, profile });
+    const text = validateEmittedText({ skeletonText: result.skeletonText, atlasText, modelText, reEmit, profile });
+    const report = {
+      failures: [...model.failures, ...text.failures],
+      passed: [...model.passed, ...text.passed],
+      skipped: [...model.skipped, ...text.skipped],
+      profileSkipped: [...model.profileSkipped, ...text.profileSkipped],
+      stats: { ...model.stats, ...text.stats },
+      profile,
+    };
+    for (const line of reportLines(report)) console.log(line);
+    console.log(
+      `  ..    ${Object.entries(report.stats)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(' ')}`,
+    );
+    const ran = (r: { passed: string[]; failures: Array<{ assertion: string }>; skipped: Array<{ assertion: string }>; profileSkipped: Array<{ assertion: string }> }): number =>
+      new Set([...r.passed, ...r.failures.map((f) => f.assertion), ...r.skipped.map((x) => x.assertion), ...r.profileSkipped.map((x) => x.assertion)]).size;
+    const notRun = text.skipped.filter((x) => x.assertion === 'A00_ROUNDTRIP_PARSE').map((x) => x.assertion);
+    console.log(
+      `  ..    here: ${ran(model)} rule(s) on the model side over the document, ${ran(text) - notRun.length} of the round trip's own restated over the emitted text; ` +
+        `not run: ${notRun.join(', ') || 'none'} — spine-core's parse, which only \`bun cli.ts build\` and \`rigc validate\` run`,
+    );
+    return report.failures.length;
+  },
+  look: (outDir) => `rigc: look at it: rigc render --candidate ${outDir}`,
+};
+
+/**
+ * The bodies the second entry runs under a name whose full-entry body is the
+ * runtime's (`runtime.core` in `COMMANDS`, issue #1060) — registered by
+ * `cli_core.ts` alone, beside `CORE_COMMAND_RUNS`. `build` is `runBuild` with
+ * this entry's gate: it writes what `cli.ts build` writes.
+ */
+export const CORE_ENTRY_RUNS: Readonly<Record<string, CommandRun>> = {
+  build: ({ flags }) => runBuild(flags, MODEL_AND_TEXT_GATE),
+};
+
 /**
  * The bodies of every command whose `runtime` is `false` (`COMMANDS`), by
  * name — what both entries register. Nothing this module imports links