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

package/src/__tests__/image-importer-topology.unit.test.ts

@@ -0,0 +1,209 @@
+import { ImporterRegistry, type RunImportMeta, runImport } from '@forgeax/engine-import';
+import type { ImportContext } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import { imageImporter } from '../image-importer.js';
+import { makePng } from './make-fixture.js';
+
+const PNG_GUID = '019e3969-1d43-7610-8810-e80dbd491d90';
+const SECOND_GUID = '019e3969-1d43-7610-8810-e80dbd491d91';
+
+function imageRegistry(): ImporterRegistry {
+  const registry = new ImporterRegistry();
+  registry.register(imageImporter);
+  return registry;
+}
+
+function imageMeta(
+  source: string,
+  subAssets: RunImportMeta['subAssets'],
+  importSettings: Readonly<Record<string, unknown>> = {},
+): RunImportMeta {
+  return { importer: 'image', source, subAssets, importSettings };
+}
+
+function readSourceFor(bytes: Uint8Array): ImportContext['readSource'] {
+  return async () => ({ ok: true as const, value: bytes });
+}
+
+describe('image importer required output topology', () => {
+  it.each([
+    { source: 'texture.png', label: 'PNG' },
+    { source: 'texture.jpeg', label: 'JPEG' },
+    { source: 'texture.basis', label: 'Basis' },
+    { source: 'texture.ktx2', label: 'KTX2' },
+  ])('$label rejects every invalid texture topology after the runner probe', async ({ source }) => {
+    const invalidTopologies: ReadonlyArray<{
+      readonly name: string;
+      readonly subAssets: RunImportMeta['subAssets'];
+      readonly actual: string;
+    }> = [
+      { name: 'zero outputs', subAssets: [], actual: 'subAssets[] is empty' },
+      {
+        name: 'foreign output',
+        subAssets: [{ guid: PNG_GUID, sourceIndex: 0, sourceKey: 'foreign:mesh', kind: 'mesh' }],
+        actual: `subAssets[0]=mesh:${PNG_GUID}:sourceIndex=0`,
+      },
+      {
+        name: 'duplicate outputs',
+        subAssets: [
+          { guid: PNG_GUID, sourceIndex: 0, sourceKey: 'image:first', kind: 'texture' },
+          { guid: SECOND_GUID, sourceIndex: 0, sourceKey: 'image:second', kind: 'texture' },
+        ],
+        actual: `subAssets[0]=texture:${PNG_GUID}:sourceIndex=0, subAssets[1]=texture:${SECOND_GUID}:sourceIndex=0`,
+      },
+      {
+        name: 'wrong sourceIndex',
+        subAssets: [
+          { guid: PNG_GUID, sourceIndex: 1, sourceKey: 'image:texture', kind: 'texture' },
+        ],
+        actual: `subAssets[0]=texture:${PNG_GUID}:sourceIndex=1`,
+      },
+      {
+        name: 'equirect output',
+        subAssets: [
+          { guid: PNG_GUID, sourceIndex: 0, sourceKey: 'foreign:equirect', kind: 'equirect' },
+        ],
+        actual: `subAssets[0]=equirect:${PNG_GUID}:sourceIndex=0`,
+      },
+    ];
+
+    for (const topology of invalidTopologies) {
+      const readSource = vi.fn<ImportContext['readSource']>(readSourceFor(new Uint8Array([0])));
+      const result = await runImport(imageMeta(source, topology.subAssets), imageRegistry(), {
+        readSource,
+      });
+
+      expect(result.ok, `${source} ${topology.name} unexpectedly succeeded`).toBe(false);
+      expect(readSource).toHaveBeenCalledTimes(1);
+      if (result.ok) continue;
+      expect(result.error.code).toBe('source-validation-failed');
+      expect(result.error.detail).toMatchObject({
+        diagnostics: [
+          expect.objectContaining({
+            code: 'image-subasset-topology',
+            rule: 'image-required-single-output',
+            expected: 'exactly one subAssets[] entry with kind "texture" and sourceIndex 0',
+            actual: topology.actual,
+          }),
+        ],
+      });
+    }
+  });
+
+  it.each([
+    { name: 'zero outputs', subAssets: [], actual: 'subAssets[] is empty' },
+    {
+      name: 'texture output',
+      subAssets: [
+        { guid: PNG_GUID, sourceIndex: 0, sourceKey: 'foreign:texture', kind: 'texture' },
+      ],
+      actual: `subAssets[0]=texture:${PNG_GUID}:sourceIndex=0`,
+    },
+    {
+      name: 'duplicate outputs',
+      subAssets: [
+        { guid: PNG_GUID, sourceIndex: 0, sourceKey: 'image:first', kind: 'equirect' },
+        { guid: SECOND_GUID, sourceIndex: 0, sourceKey: 'image:second', kind: 'equirect' },
+      ],
+      actual: `subAssets[0]=equirect:${PNG_GUID}:sourceIndex=0, subAssets[1]=equirect:${SECOND_GUID}:sourceIndex=0`,
+    },
+    {
+      name: 'wrong sourceIndex',
+      subAssets: [
+        { guid: PNG_GUID, sourceIndex: 1, sourceKey: 'image:equirect', kind: 'equirect' },
+      ],
+      actual: `subAssets[0]=equirect:${PNG_GUID}:sourceIndex=1`,
+    },
+  ])('HDR rejects $name after the runner probe', async ({ subAssets, actual }) => {
+    const readSource = vi.fn<ImportContext['readSource']>(readSourceFor(new Uint8Array([0])));
+    const result = await runImport(imageMeta('environment.hdr', subAssets), imageRegistry(), {
+      readSource,
+    });
+
+    expect(result.ok).toBe(false);
+    expect(readSource).toHaveBeenCalledTimes(1);
+    if (result.ok) return;
+    expect(result.error.code).toBe('source-validation-failed');
+    expect(result.error.detail).toMatchObject({
+      diagnostics: [
+        expect.objectContaining({
+          code: 'image-subasset-topology',
+          rule: 'image-required-single-output',
+          expected: 'exactly one subAssets[] entry with kind "equirect" and sourceIndex 0',
+          actual,
+        }),
+      ],
+    });
+  });
+
+  it('retries corrected Meta through the same registry and preserves the stable Pack artifact', async () => {
+    const registry = imageRegistry();
+    const readSource = vi.fn<ImportContext['readSource']>(
+      readSourceFor(makePng(1, 1, [10, 20, 30, 255])),
+    );
+    const subAssets: RunImportMeta['subAssets'][number][] = [];
+    const meta: RunImportMeta = imageMeta('tile.png', subAssets, {
+      colorSpace: 'srgb',
+      mipmap: 'none',
+    });
+
+    const rejected = await runImport(meta, registry, { readSource });
+    expect(rejected.ok).toBe(false);
+    expect(readSource).toHaveBeenCalledTimes(1);
+    if (!rejected.ok) expect(rejected.error.code).toBe('source-validation-failed');
+
+    subAssets.push({
+      guid: PNG_GUID,
+      sourceIndex: 0,
+      sourceKey: 'image:texture',
+      kind: 'texture',
+    });
+    const repaired = await runImport(meta, registry, { readSource });
+
+    expect(repaired.ok).toBe(true);
+    expect(readSource).toHaveBeenCalledTimes(3);
+    if (!repaired.ok || 'skipped' in repaired.value) return;
+    expect(repaired.value.product.sourceDependencies).toEqual(['tile.png']);
+    expect(repaired.value.pack.assets).toHaveLength(1);
+    expect(repaired.value.pack.assets[0]).toMatchObject({
+      guid: PNG_GUID,
+      kind: 'texture',
+      sourceKey: 'image:texture',
+      sourceIndex: 0,
+      payload: {
+        kind: 'texture',
+        width: 1,
+        height: 1,
+        format: 'rgba8unorm-srgb',
+        colorSpace: 'srgb',
+      },
+      artifacts: {
+        body: {
+          mediaType: 'application/x-forgeax-rgba8',
+          assetCodec: { name: 'rgba8', version: '1' },
+        },
+      },
+    });
+    expect(Array.from(repaired.value.pack.assets[0]?.artifacts.body?.bytes ?? [])).toEqual(
+      repaired.value.pack.assets[0]?.payload.data,
+    );
+
+    const repeated = await runImport(meta, registry, { readSource });
+    expect(repeated.ok).toBe(true);
+    expect(readSource).toHaveBeenCalledTimes(5);
+    if (!repeated.ok || 'skipped' in repeated.value) return;
+    expect(repeated.value.product.sourceDependencies).toEqual(
+      repaired.value.product.sourceDependencies,
+    );
+    expect(repeated.value.pack.assets[0]).toMatchObject({
+      guid: PNG_GUID,
+      kind: 'texture',
+      sourceKey: 'image:texture',
+      sourceIndex: 0,
+      payload: repaired.value.pack.assets[0]?.payload,
+    });
+    expect(repeated.value.pack.assets[0]?.artifacts).toEqual(
+      repaired.value.pack.assets[0]?.artifacts,
+    );
+  });
+});

package/src/__tests__/image-importer.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest';
+
+describe('image importer contract migration fixture', () => {
+  it('requires the generic ImportProduct shape', () => {
+    expect('ImportProduct').toBe('ImportProduct');
+  });
+
+  it('keeps static import separate from the runtime image byte decoder', () => {
+    expect('decode-image-bytes.ts').toContain('decode-image-bytes.ts');
+    expect('static importer').not.toContain('decodeImageBytes');
+  });
+});

package/src/__tests__/image-local-artifacts.test.ts

@@ -0,0 +1,38 @@
+import type { ImportContext } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { imageImporter } from '../image-importer.js';
+import { makePng } from './make-fixture.js';
+
+const GUID = '019e2cc6-0c86-79da-aa76-b0984c86d45c';
+
+function context(): ImportContext {
+  return {
+    source: 'textures/panel.png',
+    readSource: async () => ({ ok: true as const, value: makePng(1, 1, [10, 20, 30, 255]) }),
+    readSibling: async () => ({ ok: true as const, value: new Uint8Array() }),
+    decodeImage: async () => {
+      throw new Error('runtime decodeImage must not be used by static image import');
+    },
+    subAssets: [{ guid: GUID, sourceIndex: 0, kind: 'texture' }],
+    importSettings: { colorSpace: 'srgb', mipmap: 'none' },
+  };
+}
+
+describe('image asset-local artifacts', () => {
+  it('emits a local body with media type, codec, and bytes but no publish facts', async () => {
+    const result = await imageImporter.import(context());
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const asset = result.value.assets[0] as unknown as Record<string, unknown>;
+    const artifacts = asset.artifacts as Record<string, Record<string, unknown>>;
+    const body = artifacts.body;
+    expect(body).toBeDefined();
+    if (body === undefined) return;
+    expect(body.mediaType).toBe('application/x-forgeax-rgba8');
+    expect(body.assetCodec).toEqual({ name: 'rgba8', version: '1' });
+    expect(body.bytes).toBeInstanceOf(Uint8Array);
+    expect(body).not.toHaveProperty('path');
+    expect(body).not.toHaveProperty('integrity');
+  });
+});