@forgeax/engine-pack 0.0.0-dev.8d955ade1c79

package/src/__tests__/scanner-mount-cycle.test.ts

@@ -0,0 +1,232 @@
+// scanner-mount-cycle.test - scanner step-6 mount-asset cycle coverage
+// (feat-20260608-scene-nesting-ecs-fication M1 / w13).
+//
+// Coverage (AC-12; plan-strategy D-1):
+//   (a) acyclic mount chain A -> B -> C: scanner returns Ok (no cycle).
+//   (b) two-asset cycle A -> B -> A: scanner returns
+//       Err(PackError{ code: 'pack-cyclic-reference', detail.kind: 'mount-asset',
+//       detail.cycle: GUID[] }) with the GUIDs in cycle order (first === last).
+//   (c) three-asset cycle A -> B -> C -> A: same, longer cycle.
+//   (d) self-mount A -> A: same, single-element cycle.
+//
+// The fixtures are hand-authored scene .pack.json files in a tmpdir;
+// each scene asset uses `payload.mounts[].source` as an integer index into
+// the parent scene's `refs[]` (D-1 + research Finding 11). The mount window
+// (memberFirst / memberCount) is set conservatively so the scanner step-6
+// cycle pass triggers before any mount-window collision check.
+//
+// TDD red signal: until w14 wires `payload.mounts[].source` -> `refsByGuid`
+// edge into scanner step-6, the scanner does NOT see the mount edge in the
+// DFS and the cycle assertions miss. With w14 the cycle producer surfaces
+// `pack-cyclic-reference + detail.kind: 'mount-asset'` (w8 landed the
+// detail.kind tagging at the producer).
+
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { scan } from '../scanner.js';
+
+const GUID_A = 'aa000000-0000-4000-8000-000000000aaa';
+const GUID_B = 'bb000000-0000-4000-8000-000000000bbb';
+const GUID_C = 'cc000000-0000-4000-8000-000000000ccc';
+
+interface MountSpec {
+  readonly localId: number;
+  readonly source: number;
+  readonly memberFirst: number;
+  readonly memberCount: number;
+}
+
+interface SceneAssetSpec {
+  readonly guid: string;
+  /** GUIDs the scene asset's `payload.mounts[].source` integers index into. */
+  readonly refs: readonly string[];
+  readonly mounts: readonly MountSpec[];
+}
+
+function sceneAssetPack(spec: SceneAssetSpec): unknown {
+  return {
+    schemaVersion: '1.0.0',
+    kind: 'internal-text-package',
+    assets: [
+      {
+        guid: spec.guid,
+        kind: 'scene',
+        refs: [...spec.refs],
+        payload: {
+          kind: 'scene',
+          entities: [{ localId: 0, components: {} }],
+          mounts: spec.mounts.map((m) => ({
+            localId: m.localId,
+            source: m.source,
+            memberFirst: m.memberFirst,
+            memberCount: m.memberCount,
+          })),
+        },
+      },
+    ],
+  };
+}
+
+interface CycleErrorShape {
+  readonly code: string;
+  readonly detail: {
+    readonly code?: string;
+    readonly kind?: string;
+    readonly cycle?: readonly string[];
+  };
+}
+
+describe('scanner step-6 mount-asset cycle detection (AC-12; D-1)', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'pack-mount-cycle-'));
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('(a) accepts an acyclic mount chain A -> B -> C', async () => {
+    // A mounts B (source=0 in A.refs) -> B mounts C (source=0 in B.refs) ->
+    // C mounts nothing.
+    await writeFile(
+      join(dir, 'a.pack.json'),
+      JSON.stringify(
+        sceneAssetPack({
+          guid: GUID_A,
+          refs: [GUID_B],
+          mounts: [{ localId: 1, source: 0, memberFirst: 2, memberCount: 1 }],
+        }),
+      ),
+      'utf-8',
+    );
+    await writeFile(
+      join(dir, 'b.pack.json'),
+      JSON.stringify(
+        sceneAssetPack({
+          guid: GUID_B,
+          refs: [GUID_C],
+          mounts: [{ localId: 1, source: 0, memberFirst: 2, memberCount: 1 }],
+        }),
+      ),
+      'utf-8',
+    );
+    await writeFile(
+      join(dir, 'c.pack.json'),
+      JSON.stringify(sceneAssetPack({ guid: GUID_C, refs: [], mounts: [] })),
+      'utf-8',
+    );
+
+    const result = await scan([dir]);
+    expect(result.ok).toBe(true);
+  });
+
+  it('(b) rejects a two-asset cycle A -> B -> A with kind: mount-asset', async () => {
+    await writeFile(
+      join(dir, 'a.pack.json'),
+      JSON.stringify(
+        sceneAssetPack({
+          guid: GUID_A,
+          refs: [GUID_B],
+          mounts: [{ localId: 1, source: 0, memberFirst: 2, memberCount: 1 }],
+        }),
+      ),
+      'utf-8',
+    );
+    await writeFile(
+      join(dir, 'b.pack.json'),
+      JSON.stringify(
+        sceneAssetPack({
+          guid: GUID_B,
+          refs: [GUID_A],
+          mounts: [{ localId: 1, source: 0, memberFirst: 2, memberCount: 1 }],
+        }),
+      ),
+      'utf-8',
+    );
+
+    const result = await scan([dir]);
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    const err = result.error as unknown as CycleErrorShape;
+    expect(err.code).toBe('pack-cyclic-reference');
+    expect(err.detail.kind).toBe('mount-asset');
+    const cycle = err.detail.cycle ?? [];
+    expect(cycle.length).toBeGreaterThanOrEqual(2);
+    expect(cycle[0]).toBe(cycle[cycle.length - 1]);
+    // Both GUIDs participate in the cycle (case-insensitive compare; scanner
+    // lowercases before storing).
+    const lower = cycle.map((g) => g.toLowerCase());
+    expect(lower).toContain(GUID_A.toLowerCase());
+    expect(lower).toContain(GUID_B.toLowerCase());
+  });
+
+  it('(c) rejects a three-asset cycle A -> B -> C -> A with kind: mount-asset', async () => {
+    await writeFile(
+      join(dir, 'a.pack.json'),
+      JSON.stringify(
+        sceneAssetPack({
+          guid: GUID_A,
+          refs: [GUID_B],
+          mounts: [{ localId: 1, source: 0, memberFirst: 2, memberCount: 1 }],
+        }),
+      ),
+      'utf-8',
+    );
+    await writeFile(
+      join(dir, 'b.pack.json'),
+      JSON.stringify(
+        sceneAssetPack({
+          guid: GUID_B,
+          refs: [GUID_C],
+          mounts: [{ localId: 1, source: 0, memberFirst: 2, memberCount: 1 }],
+        }),
+      ),
+      'utf-8',
+    );
+    await writeFile(
+      join(dir, 'c.pack.json'),
+      JSON.stringify(
+        sceneAssetPack({
+          guid: GUID_C,
+          refs: [GUID_A],
+          mounts: [{ localId: 1, source: 0, memberFirst: 2, memberCount: 1 }],
+        }),
+      ),
+      'utf-8',
+    );
+
+    const result = await scan([dir]);
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    const err = result.error as unknown as CycleErrorShape;
+    expect(err.code).toBe('pack-cyclic-reference');
+    expect(err.detail.kind).toBe('mount-asset');
+    const cycle = err.detail.cycle ?? [];
+    expect(cycle.length).toBeGreaterThanOrEqual(3);
+    expect(cycle[0]).toBe(cycle[cycle.length - 1]);
+  });
+
+  it('(d) rejects a self-mount A -> A', async () => {
+    await writeFile(
+      join(dir, 'a.pack.json'),
+      JSON.stringify(
+        sceneAssetPack({
+          guid: GUID_A,
+          refs: [GUID_A],
+          mounts: [{ localId: 1, source: 0, memberFirst: 2, memberCount: 1 }],
+        }),
+      ),
+      'utf-8',
+    );
+    const result = await scan([dir]);
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    const err = result.error as unknown as CycleErrorShape;
+    expect(err.code).toBe('pack-cyclic-reference');
+    expect(err.detail.kind).toBe('mount-asset');
+  });
+});

package/src/__tests__/scriptable-pack-cli.integration.test.ts

@@ -0,0 +1,47 @@
+// @perf-budget-skip: intentional ScriptablePack CLI integration gate.
+
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { runCliAsset } from '../cli-asset.js';
+
+describe('ScriptablePack CLI Meta inspection', () => {
+  it('loads the definition without invoking build', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'forgeax-scriptable-pack-'));
+    try {
+      const source = join(root, 'house.pack.mjs');
+      await writeFile(
+        source,
+        `
+        const guid = (hex) => new Uint8Array(hex.match(/../g).map((byte) => Number.parseInt(byte, 16)));
+        export default {
+          schemaVersion: '1.0.0',
+          packageId: guid('019ffa978b397ad284cc273268591ab4'),
+          assets: {
+            wall: { guid: guid('019ffa97a5ee7645b613043323952808'), kind: 'mesh' }
+          },
+          externalAssets: {},
+          build() { throw new Error('META_MUST_NOT_BUILD'); }
+        };
+      `,
+      );
+      const stdout: string[] = [];
+      const stderr: string[] = [];
+      const code = await runCliAsset(['meta', source, '--json'], {
+        stdoutWrite: (line) => stdout.push(line),
+        stderrWrite: (line) => stderr.push(line),
+        cwd: root,
+      });
+      expect(code).toBe(0);
+      expect(stderr).toEqual([]);
+      expect(JSON.parse(stdout[0] ?? '{}')).toMatchObject({
+        importer: 'pack-ts',
+        source,
+        subAssets: [{ sourceKey: 'wall', kind: 'mesh' }],
+      });
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+});

package/src/__tests__/scriptable-pack-ddc-key.unit.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+import {
+  type ProducerSemanticIdentityInput,
+  producerRelativeDdcIdentity,
+  producerRelativeDdcKey,
+  producerRelativeLogicalPath,
+} from '../evidence/source-inventory.js';
+import { scriptablePackDdcKey } from '../scriptable-pack-node.js';
+
+const base = (
+  overrides: Partial<ProducerSemanticIdentityInput> = {},
+): ProducerSemanticIdentityInput => ({
+  producerRoot: '/checkout/game-a',
+  sourcePath: '/checkout/game-a/assets/vehicle.pack.ts',
+  sourceDigest: 'sha256:source',
+  schemaVersion: '1.0.0',
+  importer: 'scriptable-pack-importer@2',
+  codec: 'pack-v2',
+  settings: { compression: 'basis', quality: 8 },
+  producer: 'scriptable-pack@4',
+  profile: 'webgpu/v1',
+  declaredGuids: ['guid-vehicle'],
+  ...overrides,
+});
+
+describe('producer-relative ScriptablePack DDC identity', () => {
+  it('uses producer-root-relative logical path rather than absolute checkout path', () => {
+    expect(
+      producerRelativeLogicalPath('/checkout/game-a', '/checkout/game-a/assets/vehicle.pack.ts'),
+    ).toBe('assets/vehicle.pack.ts');
+    expect(
+      producerRelativeDdcKey(
+        base({
+          producerRoot: '/checkout/game-b',
+          sourcePath: '/checkout/game-b/assets/vehicle.pack.ts',
+        }),
+      ),
+    ).toBe(producerRelativeDdcKey(base()));
+  });
+
+  it.each([
+    ['source', { sourceDigest: 'sha256:changed' }],
+    ['importer', { importer: 'other-importer@1' }],
+    ['codec', { codec: 'other-codec' }],
+    ['settings', { settings: { compression: 'raw', quality: 8 } }],
+    ['producer', { producer: 'other-producer@1' }],
+    ['profile', { profile: 'webgl2/fallback' }],
+    ['schema', { schemaVersion: '2.0.0' }],
+  ])('misses when semantic input %s changes', (_name, change) => {
+    expect(producerRelativeDdcKey(base(change))).not.toBe(producerRelativeDdcKey(base()));
+  });
+
+  it('returns an inspectable identity and preserves producer-relative path in the key input', () => {
+    const identity = producerRelativeDdcIdentity(base());
+
+    expect(identity).toMatchObject({
+      logicalPath: 'assets/vehicle.pack.ts',
+      sourceDigest: 'sha256:source',
+      key: expect.stringMatching(/^[a-f0-9]{64}$/),
+    });
+    expect(scriptablePackDdcKey(base())).toBe(identity.key);
+  });
+});

package/src/__tests__/scriptable-pack.test-d.ts

@@ -0,0 +1,131 @@
+import type {
+  AnimationClip,
+  AnimationGraph,
+  AssetGuid,
+  AudioClipAsset,
+  EquirectAsset,
+  FontAsset,
+  MaterialAsset,
+  MeshAsset,
+  ParticleEffectAsset,
+  RenderPipelineAsset,
+  SamplerAsset,
+  SceneAsset,
+  SkeletonAsset,
+  SkinAsset,
+  TextureAsset,
+  TilesetAsset,
+  VideoAsset,
+} from '@forgeax/engine-types';
+import { describe, expectTypeOf, it } from 'vitest';
+import type {
+  ScriptablePackAssetDeclarations,
+  ScriptablePackAssetFor,
+  ScriptablePackAssetKind,
+  ScriptablePackGatewayOperation,
+  ScriptablePackOutputs,
+} from '../scriptable-pack.js';
+import { SCRIPTABLE_PACK_ASSET_KINDS } from '../scriptable-pack.js';
+
+function typeContract(): void {
+  const meshGuid = null as unknown as AssetGuid;
+  const sceneGuid = null as unknown as AssetGuid;
+  const mesh = null as unknown as MeshAsset;
+  const scene = null as unknown as SceneAsset;
+
+  const assets = {
+    mesh: { guid: meshGuid, kind: 'mesh' },
+    scene: { guid: sceneGuid, kind: 'scene' },
+  } as const satisfies ScriptablePackAssetDeclarations;
+
+  const valid = { mesh, scene } satisfies ScriptablePackOutputs<typeof assets>;
+  void valid;
+
+  // @ts-expect-error mesh descriptor requires MeshAsset
+  const wrongKind = { mesh: scene, scene } satisfies ScriptablePackOutputs<typeof assets>;
+  void wrongKind;
+
+  const allKinds = SCRIPTABLE_PACK_ASSET_KINDS;
+  type ExpectedKinds =
+    | MeshAsset
+    | MaterialAsset
+    | SceneAsset
+    | TextureAsset
+    | EquirectAsset
+    | SamplerAsset
+    | FontAsset
+    | RenderPipelineAsset
+    | TilesetAsset
+    | VideoAsset
+    | SkeletonAsset
+    | SkinAsset
+    | AnimationClip
+    | AnimationGraph
+    | AudioClipAsset
+    | ParticleEffectAsset;
+  type DiscoveredKinds = ScriptablePackAssetFor<{
+    readonly guid: AssetGuid;
+    readonly kind: (typeof allKinds)[number];
+  }>;
+  expectTypeOf<DiscoveredKinds>().toEqualTypeOf<ExpectedKinds>();
+
+  // @ts-expect-error unknown kinds cannot enter the ordinary producer matrix
+  const unknownKind: ScriptablePackAssetKind = 'unknown-kind';
+  void unknownKind;
+
+  // @ts-expect-error scene output is required
+  const missing = { mesh } satisfies ScriptablePackOutputs<typeof assets>;
+  void missing;
+
+  // @ts-expect-error plain strings are not AssetGuid values
+  const plainStringGuid: AssetGuid = '019ffa97-a5ee-7645-b613-043323952808';
+  void plainStringGuid;
+
+  const gatewayOperations = [
+    {
+      requestId: 'create',
+      kind: 'create-scriptable-pack',
+      sourcePath: 'new.pack.ts',
+      initialOutput: { sourceKey: 'scene', kind: 'scene' },
+    },
+    {
+      requestId: 'add',
+      kind: 'add-output',
+      sourcePath: 'new.pack.ts',
+      sourceKey: 'mesh',
+      assetKind: 'mesh',
+    },
+    {
+      requestId: 'external',
+      kind: 'add-external-asset',
+      sourcePath: 'new.pack.ts',
+      alias: 'material',
+      guid: meshGuid,
+    },
+    {
+      requestId: 'rename',
+      kind: 'rename-display',
+      sourcePath: 'new.pack.ts',
+      target: { kind: 'output', sourceKey: 'mesh' },
+      name: 'Wall',
+    },
+    { requestId: 'remove', kind: 'remove-output', sourcePath: 'new.pack.ts', sourceKey: 'mesh' },
+    {
+      requestId: 'clone',
+      kind: 'clone-scriptable-pack',
+      sourcePath: 'new.pack.ts',
+      targetPath: 'clone.pack.ts',
+    },
+    { requestId: 'preflight', kind: 'preflight', sourcePath: 'new.pack.ts' },
+    { requestId: 'inspect', kind: 'inspect-meta', sourcePath: 'new.pack.ts' },
+    { requestId: 'rebuild', kind: 'rebuild', sourcePath: 'new.pack.ts' },
+    { requestId: 'cold-cook', kind: 'cold-cook', sourcePath: 'new.pack.ts' },
+  ] as const satisfies readonly ScriptablePackGatewayOperation[];
+  void gatewayOperations;
+}
+
+describe('ScriptablePack public type contract', () => {
+  it('constrains output payloads, GUID brands, and gateway operations', () => {
+    typeContract();
+  });
+});