@forgeax/engine-pack 0.1.2

package/src/__tests__/atlas-cli-region-mismatch.test.ts

@@ -0,0 +1,134 @@
+// `forgeax-engine-remote-asset atlas` region-mismatch safety-net test
+// (feat-20260521-sprite-atlas-animation M5' T-29 / requirements AC-10 (c)).
+//
+// The shelfPack pure function never produces regions whose summed area
+// exceeds the atlas footprint -- that would be a packer regression. We
+// still keep an `atlas-region-mismatch` invariant in runAtlas so a future
+// algorithm swap (D-4 MaxRects / rectpack2D) cannot silently drop
+// pixels. To exercise that branch we replace shelfPack with a vi.mock
+// factory that fabricates an over-large region map; runAtlas must then
+// project the failure to ImageError code='atlas-region-mismatch' with
+// detail.{name, regionsTotalPixels, atlasPixels}.
+
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('../atlas/shelf-pack.js', async () => {
+  return {
+    shelfPack: () => ({
+      ok: true,
+      value: {
+        atlasWidth: 64,
+        atlasHeight: 64,
+        regions: [
+          { name: 'walk-0', x: 0, y: 0, w: 64, h: 64 },
+          { name: 'walk-1', x: 0, y: 0, w: 64, h: 64 },
+          { name: 'walk-2', x: 0, y: 0, w: 64, h: 64 },
+        ],
+      },
+    }),
+  };
+});
+
+import { runCliAsset } from '../cli-asset.js';
+
+interface CapturedIO {
+  stdout: string[];
+  stderr: string[];
+}
+
+function makeIO(): CapturedIO {
+  return { stdout: [], stderr: [] };
+}
+
+function ctxFor(io: CapturedIO) {
+  return {
+    stdoutWrite: (line: string): void => {
+      io.stdout.push(line);
+    },
+    stderrWrite: (line: string): void => {
+      io.stderr.push(line);
+    },
+  };
+}
+
+interface UpngEncode {
+  encode: (imgs: ArrayBuffer[], w: number, h: number, cnum: number) => ArrayBuffer;
+}
+
+async function loadUpng(): Promise<UpngEncode> {
+  const mod = (await import('upng-js')) as { default?: UpngEncode } & UpngEncode;
+  return (mod.default ?? mod) as UpngEncode;
+}
+
+async function writeSolidPng(
+  path: string,
+  width: number,
+  height: number,
+  rgba: [number, number, number, number],
+): Promise<void> {
+  const upng = await loadUpng();
+  const pixels = new Uint8Array(width * height * 4);
+  for (let i = 0; i < width * height; i++) {
+    pixels[i * 4 + 0] = rgba[0];
+    pixels[i * 4 + 1] = rgba[1];
+    pixels[i * 4 + 2] = rgba[2];
+    pixels[i * 4 + 3] = rgba[3];
+  }
+  const buf = upng.encode([pixels.buffer as ArrayBuffer], width, height, 0);
+  await writeFile(path, Buffer.from(buf));
+}
+
+describe('atlas CLI region-mismatch safety net (T-29 / AC-10 c)', () => {
+  let tmp: string;
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(join(tmpdir(), 'atlas-cli-region-'));
+  });
+
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  it('exits 1 with atlas-region-mismatch + detail name/regionsTotalPixels/atlasPixels', async () => {
+    await writeSolidPng(join(tmp, 'walk-0.png'), 32, 32, [255, 0, 0, 255]);
+    await writeSolidPng(join(tmp, 'walk-1.png'), 32, 32, [0, 255, 0, 255]);
+    await writeSolidPng(join(tmp, 'walk-2.png'), 32, 32, [0, 0, 255, 255]);
+
+    const io = makeIO();
+    const code = await runCliAsset(
+      [
+        'atlas',
+        '--input',
+        `${tmp}/*.png`,
+        '--name',
+        'walk',
+        '--output',
+        tmp,
+        '--max-atlas-size',
+        '4096',
+      ],
+      ctxFor(io),
+    );
+
+    expect(code).toBe(1);
+    expect(io.stderr.length).toBe(1);
+    const parsed = JSON.parse(io.stderr[0] as string) as {
+      code: string;
+      expected: string;
+      hint: string;
+      detail?: { name?: string; regionsTotalPixels?: number; atlasPixels?: number };
+    };
+    expect(parsed.code).toBe('atlas-region-mismatch');
+    expect(typeof parsed.expected).toBe('string');
+    expect(parsed.expected.length).toBeGreaterThan(0);
+    expect(typeof parsed.hint).toBe('string');
+    expect(parsed.hint.length).toBeGreaterThan(0);
+    expect(typeof parsed.detail?.name).toBe('string');
+    expect(typeof parsed.detail?.regionsTotalPixels).toBe('number');
+    expect(typeof parsed.detail?.atlasPixels).toBe('number');
+    expect(parsed.detail?.regionsTotalPixels ?? 0).toBeGreaterThan(parsed.detail?.atlasPixels ?? 0);
+  });
+});

package/src/__tests__/atlas-error-code-owner.test-d.ts

@@ -0,0 +1,23 @@
+import { readFileSync } from 'node:fs';
+import type { IMAGE_ERROR_HINTS } from '@forgeax/engine-types';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+type AtlasErrorCode = Extract<keyof typeof IMAGE_ERROR_HINTS, `atlas-${string}`>;
+
+const ownerSource = readFileSync(new URL('../atlas/run-atlas.ts', import.meta.url), 'utf8');
+
+describe('runAtlas ErrorEnvelope.code owner', () => {
+  it('retains the exact public atlas code membership', () => {
+    expectTypeOf<AtlasErrorCode>().toEqualTypeOf<
+      'atlas-empty-input' | 'atlas-size-exceeded' | 'atlas-region-mismatch'
+    >();
+    expectTypeOf<'atlas-unknown'>().not.toExtend<AtlasErrorCode>();
+  });
+
+  it('derives ErrorEnvelope.code from ATLAS_EXPECTED', () => {
+    expect(ownerSource).toContain('readonly code: keyof typeof ATLAS_EXPECTED;');
+    expect(ownerSource).not.toContain(
+      "readonly code: 'atlas-empty-input' | 'atlas-size-exceeded' | 'atlas-region-mismatch';",
+    );
+  });
+});

package/src/__tests__/cli-asset-evidence.integration.test.ts

@@ -0,0 +1,172 @@
+import { createHash } from 'node:crypto';
+import { mkdir, mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { runCliAsset } from '../cli-asset.js';
+
+const guid = '11111111-1111-4111-8111-111111111111';
+const tempRoots: string[] = [];
+
+async function evidenceFixture(): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), 'forgeax-asset-evidence-'));
+  tempRoots.push(root);
+  await mkdir(join(root, 'assets', 'artifacts'), { recursive: true });
+  const bytes = Buffer.from('data');
+  const digest = createHash('sha256').update(bytes).digest('base64');
+  await writeFile(join(root, 'assets', 'artifacts', 'data.bin'), bytes);
+  await writeFile(
+    join(root, 'assets', 'config.pack.json'),
+    JSON.stringify({
+      schemaVersion: '2.0.0',
+      kind: 'internal-text-package',
+      assets: [
+        {
+          guid,
+          kind: 'config',
+          payload: { answer: 42 },
+          refs: [],
+          artifacts: {
+            data: {
+              path: 'artifacts/data.bin',
+              mediaType: 'application/octet-stream',
+              byteLength: bytes.byteLength,
+              integrity: { algorithm: 'sha256', digest },
+            },
+          },
+        },
+      ],
+    }),
+  );
+  await writeFile(join(root, 'config.source'), 'source declaration');
+  const meta = {
+    schemaVersion: '1.0.0',
+    kind: 'external-asset-package',
+    importer: 'image',
+    source: 'config.source',
+    importSettings: {},
+    subAssets: [{ guid, sourceIndex: 0, kind: 'config' }],
+  };
+  const metaRaw = JSON.stringify(meta);
+  const inputFingerprint = createHash('sha256').update(metaRaw).digest('base64');
+  await writeFile(join(root, 'config.source.meta.json'), metaRaw);
+  await writeFile(
+    join(root, 'receipts.json'),
+    JSON.stringify({
+      guid,
+      origin: 'sourceMeta',
+      status: 'succeeded',
+      inputFingerprint,
+      outputDigest: digest,
+    }),
+  );
+  await writeFile(
+    join(root, 'catalog.json'),
+    JSON.stringify([
+      {
+        guid,
+        packageUrl: '/assets/config.pack.json',
+        cookReceiptUrl: '/receipts.json',
+        kind: 'config',
+        sourcePath: 'config.source.meta.json',
+      },
+    ]),
+  );
+  return root;
+}
+
+afterEach(async () => {
+  for (const root of tempRoots.splice(0)) {
+    await import('node:fs/promises').then(({ rm }) => rm(root, { recursive: true, force: true }));
+  }
+});
+
+describe('asset evidence CLI contract', () => {
+  it('advertises the complete AI inspection and recovery vocabulary', async () => {
+    const stdout: string[] = [];
+    const stderr: string[] = [];
+    const code = await runCliAsset(['--help'], {
+      stdoutWrite: (line) => stdout.push(line),
+      stderrWrite: (line) => stderr.push(line),
+    });
+
+    expect(code).toBe(0);
+    expect(stderr).toEqual([]);
+    const help = stdout.join('\n');
+    for (const operation of [
+      'inspect',
+      'rebuild',
+      'cold-cook',
+      'preview-LKG',
+      'override',
+      'promote',
+      'stop-publish',
+    ]) {
+      expect(help).toContain(operation);
+    }
+  });
+
+  it('returns the shared evidence JSON for lookup --guid --json', async () => {
+    const project = await evidenceFixture();
+    const stdout: string[] = [];
+    const stderr: string[] = [];
+    const code = await runCliAsset(
+      [
+        'lookup',
+        '--guid',
+        guid,
+        '--project',
+        project,
+        '--catalog',
+        join(project, 'catalog.json'),
+        '--json',
+      ],
+      { stdoutWrite: (line) => stdout.push(line), stderrWrite: (line) => stderr.push(line) },
+    );
+
+    expect(code).toBe(0);
+    expect(stderr).toEqual([]);
+    const evidence = JSON.parse(stdout[0] as string) as {
+      guid: string;
+      packageUrl?: string;
+      cook: { status: string; freshness: string };
+      artifacts: Record<string, { verification: string }>;
+    };
+    expect(evidence.guid).toBe(guid);
+    expect(evidence.packageUrl).toBe('/assets/config.pack.json');
+    expect(evidence.cook.status).toBe('ready');
+    expect(evidence.cook.freshness).toBe('current');
+    const dataArtifact = evidence.artifacts.data;
+    expect(dataArtifact).toBeDefined();
+    if (dataArtifact === undefined) return;
+    expect(dataArtifact.verification).toBe('passed');
+  });
+
+  it('emits exactly one structured JSON error and no free-text protocol', async () => {
+    const stdout: string[] = [];
+    const stderr: string[] = [];
+    const code = await runCliAsset(
+      [
+        'verify',
+        '--guid',
+        'not-a-guid',
+        '--project',
+        '/project',
+        '--catalog',
+        '/project/catalog.json',
+        '--json',
+      ],
+      { stdoutWrite: (line) => stdout.push(line), stderrWrite: (line) => stderr.push(line) },
+    );
+
+    expect(code).toBe(1);
+    expect(stdout).toEqual([]);
+    expect(stderr).toHaveLength(1);
+    expect(JSON.parse(stderr[0] as string)).toMatchObject({
+      code: 'pack-guid-malformed',
+      expected: expect.any(String),
+      hint: expect.any(String),
+      detail: expect.any(Object),
+    });
+  });
+});