@developerz.ai/ts23d 0.0.0-stage → 0.1.0

package/src/testing/assert.ts

@@ -0,0 +1,115 @@
+// Assertions for a recipe's own `bun test` (or any runner): each compiles the asset, checks one
+// property, and throws a Ts23dError with the findings and a fix — no test framework imported.
+//   it('passes QA', () => assertQaPass(tiger_1));
+//   it('has its pivots', () => assertParts(tiger_1, ['turret', 'gun', 'wheel_l_*']));
+
+import type { Asset, Lod, Measure } from '../core/index.ts';
+import {
+  clashes,
+  DEFAULT_GATES,
+  DEFAULT_LOD_GATES,
+  type Gate,
+  glob,
+  type LodGate,
+  measure,
+  runLodQa,
+  runQa,
+} from '../qa/index.ts';
+import { compileLods, failOn, type LodOptions } from './compiled.ts';
+
+export interface QaOptions extends LodOptions {
+  /** Per-LOD gates. Default the build's DEFAULT_GATES. */
+  readonly gates?: readonly Gate[];
+  /** Chain gates over all compiled LODs. Default DEFAULT_LOD_GATES. */
+  readonly lodGates?: readonly LodGate[];
+}
+
+/** The same gate `t3d build` runs: every LOD passes QA, plus the LOD-chain gates. */
+export function assertQaPass(asset: Asset, o: QaOptions = {}): void {
+  const lods = compileLods(asset, o);
+  const found = lods.flatMap((a) =>
+    runQa(a, o.gates ?? DEFAULT_GATES).map((finding) => ({ finding, lod: a.lod })),
+  );
+  const chain = lods.length > 1 ? runLodQa(lods, o.lodGates ?? DEFAULT_LOD_GATES) : [];
+  failOn(`${asset.name} QA`, [...found, ...chain.map((finding) => ({ finding }))]);
+}
+
+/** Triangles per LOD at or under `caps` (default: the asset's own budget). */
+export function assertBudget(
+  asset: Asset,
+  caps: readonly [number, number, number] = asset.budget.triangles,
+  o: LodOptions = {},
+): void {
+  failOn(
+    `${asset.name} budget`,
+    compileLods(asset, o).flatMap((a) => {
+      const tris = a.parts.reduce((s, p) => s + (p.mesh ? p.mesh.indices.length / 3 : 0), 0);
+      const cap = caps[a.lod];
+      return tris > cap
+        ? [
+            {
+              lod: a.lod,
+              finding: {
+                gate: 'budget',
+                message: `${tris} triangles > ${cap}`,
+                fix: 'drop detail at this LOD (ctx.lod / ctx.pick) — never raise a cap to make a test pass',
+              },
+            },
+          ]
+        : [];
+    }),
+  );
+}
+
+/** Each selector (name or glob) matches at least one part at every LOD checked. */
+export function assertParts(asset: Asset, selectors: readonly string[], o: LodOptions = {}): void {
+  failOn(
+    `${asset.name} parts`,
+    compileLods(asset, o).flatMap((a) =>
+      selectors
+        .filter((s) => !a.parts.some((p) => glob(s).test(p.name)))
+        .map((s) => ({
+          lod: a.lod,
+          finding: {
+            gate: 'parts',
+            message: `no part matches '${s}'`,
+            fix: 'engines bind to these names: add the part/group at this LOD (gate its geometry, not its pivot)',
+          },
+        })),
+    ),
+  );
+}
+
+/** One spec dimension at LOD0, the way the `measures` gate checks `real.measures`. */
+export function assertMeasure(asset: Asset, m: Measure, o: { lod?: Lod } = {}): number {
+  const [a] = compileLods(asset, { lods: [o.lod ?? 0] });
+  const got = a ? measure(a, m) : null;
+  const tol = m.tolerance ?? 0.02;
+  const bad = got === null || Math.abs(got - m.value) / m.value > tol;
+  failOn(
+    `${asset.name} measure`,
+    bad
+      ? [
+          {
+            finding: {
+              gate: 'measure',
+              message:
+                got === null
+                  ? `'${m.label}': no part matches ${JSON.stringify(m.parts ?? m.between)}`
+                  : `${m.label}: ${got.toFixed(3)} m on ${m.axis.toUpperCase()}, want ${m.value} m (±${tol * 100}%)`,
+              fix: 'rebuild the part from the spec number; never edit the spec to match the model',
+            },
+          },
+        ]
+      : [],
+  );
+  return got ?? Number.NaN;
+}
+
+/** Every moving part sweeps clear of everything else (the `clashes` gate), at every LOD. */
+export function assertMotionClear(asset: Asset, o: LodOptions = {}): void {
+  failOn(
+    `${asset.name} motion`,
+    compileLods(asset, o).flatMap((a) => clashes(a).map((finding) => ({ finding, lod: a.lod }))),
+  );
+}

package/src/testing/compiled.ts

@@ -0,0 +1,31 @@
+// Shared plumbing for the assertions: compile an asset at the LODs asked for, and turn QA
+// findings into one thrown Ts23dError an agent can act on (code, every finding, the first fix).
+
+import { type Asset, type CompiledAsset, compile, type Lod, Ts23dError } from '../core/index.ts';
+import type { Finding } from '../qa/index.ts';
+
+export interface LodOptions {
+  /** LODs to check. Default all three. */
+  readonly lods?: readonly Lod[];
+  readonly seed?: number;
+}
+
+export const ALL_LODS: readonly Lod[] = [0, 1, 2];
+
+export const compileLods = (asset: Asset, o: LodOptions = {}): CompiledAsset[] =>
+  (o.lods ?? ALL_LODS).map((lod) =>
+    compile(asset, { lod, ...(o.seed !== undefined ? { seed: o.seed } : {}) }),
+  );
+
+export const describeFinding = (f: Finding, lod?: Lod): string =>
+  `${lod !== undefined ? `LOD${lod} ` : ''}${f.gate}${f.part ? ` [${f.part}]` : ''}: ${f.message}`;
+
+/** Throw T3D_QA_FAILED listing every finding; no-op when there are none. */
+export function failOn(what: string, found: ReadonlyArray<{ finding: Finding; lod?: Lod }>): void {
+  if (found.length === 0) return;
+  const lines = found.map(({ finding, lod }) => `  - ${describeFinding(finding, lod)}`);
+  throw new Ts23dError('T3D_QA_FAILED', {
+    cause: `${what}: ${found.length} finding(s)\n${lines.join('\n')}`,
+    fix: found[0]?.finding.fix ?? 'read the findings above',
+  });
+}

package/src/testing/hash.ts

@@ -0,0 +1,14 @@
+// A stable content hash for snapshot tests: 64-bit FNV-1a (two 32-bit lanes), pure JS, so the
+// same bytes give the same hex string on Bun, Node and the browser — no runtime hash API needed.
+
+export function hashBytes(bytes: Uint8Array): string {
+  let h1 = 0x811c9dc5;
+  let h2 = 0xcbf29ce4;
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i] ?? 0;
+    h1 = Math.imul(h1 ^ b, 0x01000193);
+    h2 = Math.imul(h2 ^ b ^ (h1 >>> 24), 0x01000193);
+  }
+  const hex = (n: number): string => (n >>> 0).toString(16).padStart(8, '0');
+  return `${hex(h2)}${hex(h1)}`;
+}

package/src/testing/index.ts

@@ -0,0 +1,14 @@
+// Public API of /testing: assertions for users' own recipe tests (`bun test`, vitest, node:test —
+// framework-agnostic: each throws a Ts23dError with findings and a fix, or returns quietly).
+
+export {
+  assertBudget,
+  assertMeasure,
+  assertMotionClear,
+  assertParts,
+  assertQaPass,
+  type QaOptions,
+} from './assert.ts';
+export { ALL_LODS, compileLods, describeFinding, type LodOptions } from './compiled.ts';
+export { hashBytes } from './hash.ts';
+export { assertDeterministic, type SnapshotOptions, snapshotHash } from './snapshot.ts';

package/src/testing/snapshot.ts

@@ -0,0 +1,37 @@
+// Determinism and snapshot helpers: the GLB an asset compiles to, hashed. Pin a hash in a test to
+// catch any unintended geometry change; compile twice to prove the recipe has no ambient state.
+
+import { type Asset, compile, type Lod, Ts23dError } from '../core/index.ts';
+import { exportGlb, type GlbOptions } from '../export/index.ts';
+import type { LodOptions } from './compiled.ts';
+import { ALL_LODS } from './compiled.ts';
+import { hashBytes } from './hash.ts';
+
+export interface SnapshotOptions {
+  readonly lod?: Lod;
+  readonly seed?: number;
+  /** Exporter options; default the plain optimised GLB (no textures, no clips). */
+  readonly glb?: GlbOptions;
+}
+
+/** 16-hex-digit content hash of the asset's GLB at one LOD. */
+export function snapshotHash(asset: Asset, o: SnapshotOptions = {}): string {
+  const a = compile(asset, {
+    lod: o.lod ?? 0,
+    ...(o.seed !== undefined ? { seed: o.seed } : {}),
+  });
+  return hashBytes(exportGlb(a, o.glb ?? {}).glb);
+}
+
+/** Compile + export twice per LOD; the bytes must match. */
+export function assertDeterministic(asset: Asset, o: LodOptions = {}): void {
+  for (const lod of o.lods ?? ALL_LODS) {
+    const once = snapshotHash(asset, { lod, ...(o.seed !== undefined ? { seed: o.seed } : {}) });
+    const twice = snapshotHash(asset, { lod, ...(o.seed !== undefined ? { seed: o.seed } : {}) });
+    if (once !== twice)
+      throw new Ts23dError('T3D_QA_FAILED', {
+        cause: `${asset.name} LOD${lod} is not byte-deterministic (${once} vs ${twice})`,
+        fix: 'remove ambient state from build(): read ctx.rng/ctx.seed only — no Math.random, Date, or module-level counters',
+      });
+  }
+}

package/src/types/gltf-validator.d.ts

@@ -0,0 +1,13 @@
+// Minimal types for the dev-only Khronos validator (it ships none).
+declare module 'gltf-validator' {
+  export function validateBytes(
+    data: Uint8Array,
+    options?: Record<string, unknown>,
+  ): Promise<{
+    issues: {
+      numErrors: number;
+      numWarnings: number;
+      messages: { severity: number; code: string; pointer?: string; message: string }[];
+    };
+  }>;
+}