@forgeax/engine-import 0.1.3 → 0.1.6

package/src/source-package-publication.ts

@@ -0,0 +1,295 @@
+import { mkdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import {
+  type DdcEntry,
+  type DdcGenerationEntryCandidate,
+  DdcGenerationSession,
+  type DdcHead,
+  DdcLifecycle,
+  ddcOutputDigest,
+} from '@forgeax/engine-ddc';
+import {
+  type CatalogEntry,
+  err,
+  ok,
+  type ResourceRevision,
+  type Result,
+} from '@forgeax/engine-types';
+import {
+  type SourcePackageError,
+  type SourcePackageErrorContext,
+  sourcePackageError,
+} from './source-package-errors.js';
+
+interface SourcePackageDdcEntryInput {
+  readonly root: string;
+  readonly entry: DdcEntry;
+  readonly context: SourcePackageErrorContext;
+}
+
+interface StagedSourcePackageDdc extends DdcGenerationEntryCandidate {
+  readonly root: string;
+  readonly session: DdcGenerationSession;
+  readonly context: SourcePackageErrorContext;
+}
+
+export interface ImportPublicationInput {
+  readonly root: string;
+  readonly guid: string;
+  readonly desiredKey: string;
+  readonly pack: unknown;
+  readonly previousCatalog: readonly CatalogEntry[];
+  readonly nextCatalog: readonly CatalogEntry[];
+  readonly publishedGuids: readonly string[];
+  readonly transport?: {
+    readonly path: string;
+    readonly body: string;
+  };
+}
+
+export interface ImportPublicationError {
+  readonly code: SourcePackageError['code'];
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: string;
+  readonly diagnostic: SourcePackageError;
+}
+
+export type ImportPublicationResult =
+  | {
+      readonly ok: true;
+      readonly key: string;
+      readonly head: DdcHead;
+      readonly catalog: readonly CatalogEntry[];
+      readonly revision: ResourceRevision;
+      readonly transportPersisted: boolean;
+    }
+  | { readonly ok: false; readonly error: ImportPublicationError; readonly head: DdcHead };
+
+export interface StagedImportPublication {
+  readonly input: ImportPublicationInput;
+  readonly ddc: StagedSourcePackageDdc;
+  readonly key: string;
+  readonly head: DdcHead;
+  readonly catalog: readonly CatalogEntry[];
+  readonly revision: ResourceRevision;
+}
+
+export type StagedImportPublicationResult =
+  | { readonly ok: true; readonly candidate: StagedImportPublication }
+  | { readonly ok: false; readonly error: ImportPublicationError; readonly head: DdcHead };
+
+function inspectHead(root: string, guid: string, desiredKey: string): Promise<DdcHead> {
+  return new DdcLifecycle(root).inspect(guid, desiredKey);
+}
+
+async function stageSourcePackageDdc(
+  input: SourcePackageDdcEntryInput,
+): Promise<Result<StagedSourcePackageDdc, SourcePackageError>> {
+  const session = new DdcGenerationSession(input.root, { generation: 1 });
+  try {
+    const candidate = await session.stageEntry(input.entry);
+    return ok({ ...candidate, root: input.root, session, context: input.context });
+  } catch (error) {
+    return err(
+      sourcePackageError('source-package-ddc-failed', input.context, {
+        stage: 'ddc',
+        reason: error instanceof Error ? error.message : String(error),
+      }),
+    );
+  }
+}
+
+async function commitSourcePackageDdc(
+  candidate: StagedSourcePackageDdc,
+): Promise<Result<DdcHead, SourcePackageError>> {
+  try {
+    const commit = await candidate.session.commitEntry(candidate, candidate.lease.desiredKey);
+    if (commit.result !== 'current') {
+      return err(
+        sourcePackageError('source-package-ddc-failed', candidate.context, {
+          stage: 'ddc',
+          reason: `DDC lifecycle commit returned ${commit.result}`,
+        }),
+      );
+    }
+    return ok(await inspectHead(candidate.root, candidate.lease.guid, candidate.lease.desiredKey));
+  } catch (error) {
+    return err(
+      sourcePackageError('source-package-ddc-failed', candidate.context, {
+        stage: 'ddc',
+        reason: error instanceof Error ? error.message : String(error),
+      }),
+    );
+  }
+}
+
+async function persistTransport(transport: ImportPublicationInput['transport']): Promise<boolean> {
+  if (transport === undefined) return true;
+  const directory = dirname(transport.path);
+  const temporary = `${transport.path}.tmp`;
+  try {
+    await mkdir(directory, { recursive: true });
+    if (((await stat(directory)).mode & 0o222) === 0) {
+      throw new Error('transport directory is read-only');
+    }
+    await writeFile(temporary, transport.body);
+    await rename(temporary, transport.path);
+    return true;
+  } catch {
+    await rm(temporary, { force: true }).catch(() => {});
+    return false;
+  }
+}
+
+function importPublicationFailure(error: SourcePackageError): ImportPublicationError {
+  return {
+    code: error.code,
+    expected: error.expected,
+    hint: error.hint,
+    detail: error.detail.reason ?? error.detail.stage,
+    diagnostic: error,
+  };
+}
+
+function projectImportPublication(
+  input: ImportPublicationInput,
+  head: DdcHead,
+  observedAt: number,
+): { readonly catalog: readonly CatalogEntry[]; readonly revision: ResourceRevision } {
+  const digest = head.currentKey ?? input.desiredKey;
+  const revision: ResourceRevision = { digest, observedAt, rootId: input.root };
+  const published = new Set(input.publishedGuids.map((guid) => guid.toLowerCase()));
+  const catalog = input.nextCatalog.map((row) => {
+    if (!published.has(row.guid.toLowerCase())) return row;
+    const previousLkg =
+      head.lastKnownGoodKey === undefined
+        ? undefined
+        : input.previousCatalog.find(
+            (candidate) =>
+              candidate.guid.toLowerCase() === row.guid.toLowerCase() &&
+              candidate.revision?.digest === head.lastKnownGoodKey,
+          );
+    const projection =
+      row.projection === undefined
+        ? undefined
+        : (() => {
+            const { lastKnownGood: _staleLastKnownGood, ...withoutLastKnownGood } = row.projection;
+            return previousLkg?.packageUrl === undefined
+              ? withoutLastKnownGood
+              : { ...withoutLastKnownGood, lastKnownGood: { packageUrl: previousLkg.packageUrl } };
+          })();
+    return {
+      ...row,
+      revision,
+      ...(projection === undefined ? {} : { projection }),
+    };
+  });
+  return { catalog, revision };
+}
+
+export async function publishImportPublication(
+  input: ImportPublicationInput,
+): Promise<ImportPublicationResult> {
+  const staged = await stageImportPublication(input);
+  if (!staged.ok) return staged;
+  return commitImportPublication(staged.candidate);
+}
+
+export async function stageImportPublication(
+  input: ImportPublicationInput,
+): Promise<StagedImportPublicationResult> {
+  const staged = await stageSourcePackageDdc({
+    root: input.root,
+    entry: {
+      key: input.desiredKey,
+      guid: input.guid,
+      payload: input.pack,
+      refs: [],
+      artifacts: {},
+      receipt: {
+        guid: input.guid,
+        key: input.desiredKey,
+        producer: 'engine-import/source-package-publication',
+        inputFingerprint: input.desiredKey,
+        outputDigest: ddcOutputDigest({
+          guid: input.guid,
+          payload: input.pack,
+          refs: [],
+          artifacts: {},
+        }),
+      },
+    },
+    context: {
+      sourceMeta: '<import-publication>',
+      anchorGuid: input.guid,
+      affectedGuids: input.publishedGuids,
+      producer: 'source-package/import-publication',
+      importer: 'import-publication',
+    },
+  });
+  if (!staged.ok) {
+    return {
+      ok: false,
+      error: importPublicationFailure(staged.error),
+      head: await inspectHead(input.root, input.guid, input.desiredKey),
+    };
+  }
+  const lastKnownGoodKey =
+    staged.value.previousHead.currentKey !== undefined &&
+    staged.value.previousHead.currentKey !== input.desiredKey
+      ? staged.value.previousHead.currentKey
+      : staged.value.previousHead.lastKnownGoodKey;
+  const projectedHead: DdcHead = {
+    ...staged.value.previousHead,
+    state: 'cooking',
+    currentKey: input.desiredKey,
+    ...(lastKnownGoodKey === undefined ? {} : { lastKnownGoodKey }),
+  };
+  const projected = projectImportPublication(input, projectedHead, Date.now());
+  return {
+    ok: true,
+    candidate: {
+      input,
+      ddc: staged.value,
+      key: input.desiredKey,
+      head: projectedHead,
+      catalog: projected.catalog,
+      revision: projected.revision,
+    },
+  };
+}
+
+export async function commitImportPublication(
+  candidate: StagedImportPublication,
+): Promise<ImportPublicationResult> {
+  const publication = await commitSourcePackageDdc(candidate.ddc);
+  if (!publication.ok) {
+    return {
+      ok: false,
+      error: importPublicationFailure(publication.error),
+      head: await inspectHead(
+        candidate.input.root,
+        candidate.input.guid,
+        candidate.input.desiredKey,
+      ),
+    };
+  }
+  const projected = projectImportPublication(candidate.input, publication.value, Date.now());
+  return {
+    ok: true,
+    key: candidate.input.desiredKey,
+    head: publication.value,
+    catalog: projected.catalog,
+    revision: projected.revision,
+    transportPersisted: await persistTransport(candidate.input.transport),
+  };
+}
+
+export async function discardImportPublication(candidate: StagedImportPublication): Promise<void> {
+  await candidate.ddc.session.discardEntry(candidate.ddc);
+}
+
+export async function restoreImportPublication(candidate: StagedImportPublication): Promise<void> {
+  await candidate.ddc.session.restoreEntry(candidate.ddc);
+}

package/src/source-package.ts

@@ -0,0 +1,187 @@
+import type {
+  ImportErrorDetail,
+  ImportedAsset,
+  ImportProduct,
+  ImportProductFinalizeOptions,
+  ImportProductFinalizeResult,
+  Result,
+} from '@forgeax/engine-types';
+import { err, ok } from '@forgeax/engine-types';
+import type { ImportRunnerFs, RunImportMeta } from './import-runner.js';
+import { runImport } from './import-runner.js';
+import type { ImporterRegistry } from './importer-registry.js';
+
+export type ProducerReadiness = 'before-consume' | 'on-demand';
+
+export interface ProducerReadinessError {
+  readonly code: 'producer-readiness-invalid';
+  readonly expected: "'before-consume' or 'on-demand'";
+  readonly hint: 'set producerReadiness to before-consume or on-demand';
+  readonly detail: { readonly value: unknown };
+}
+
+export type ProducerReadinessResult =
+  | { readonly ok: true; readonly value: ProducerReadiness }
+  | { readonly ok: false; readonly error: ProducerReadinessError };
+
+export function parseProducerReadiness(value: unknown): ProducerReadinessResult {
+  if (value === undefined || value === 'before-consume' || value === 'on-demand') {
+    return { ok: true, value: value ?? 'before-consume' };
+  }
+  return {
+    ok: false,
+    error: {
+      code: 'producer-readiness-invalid',
+      expected: "'before-consume' or 'on-demand'",
+      hint: 'set producerReadiness to before-consume or on-demand',
+      detail: { value },
+    },
+  };
+}
+
+export interface SourcePackageProducerInput {
+  readonly meta: RunImportMeta;
+  readonly registry: ImporterRegistry;
+  readonly fs: ImportRunnerFs;
+}
+
+export interface SourcePackageClosureDetail {
+  readonly stage: 'closure';
+  readonly declaredGuids: readonly string[];
+  readonly producedGuids: readonly string[];
+  readonly missingGuids: readonly string[];
+  readonly unexpectedGuids: readonly string[];
+  readonly duplicateGuids: readonly string[];
+}
+
+export interface SourcePackageClosureError {
+  readonly code: 'source-package-guid-closure-mismatch';
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: SourcePackageClosureDetail;
+}
+
+export interface SourcePackageProduct {
+  readonly anchorGuid: string;
+  readonly declaredGuids: readonly string[];
+  readonly product: ImportProduct<unknown>;
+}
+
+type SourcePackageFinalizeError = Extract<
+  ImportProductFinalizeResult,
+  { readonly ok: false }
+>['error'];
+
+/** Apply an importer-owned transport finalizer without teaching the adapter its kind. */
+export function finalizeSourcePackage(
+  product: ImportProduct<unknown>,
+  finalizer:
+    | ((
+        product: ImportProduct<unknown>,
+        options: ImportProductFinalizeOptions,
+      ) => ImportProductFinalizeResult)
+    | undefined,
+  artifactUrl: ImportProductFinalizeOptions['artifactUrl'],
+): Result<ImportProduct<unknown>, SourcePackageFinalizeError> {
+  if (finalizer === undefined) return ok(product);
+  const result = finalizer(product, { artifactUrl });
+  if (!result.ok) return err(result.error);
+  return ok({
+    ...product,
+    assets: product.assets.map((asset, index) =>
+      index === 0 ? { ...asset, payload: result.value.asset } : asset,
+    ),
+  });
+}
+
+export type SourcePackageProducerResult =
+  | { readonly ok: true; readonly value: SourcePackageProduct }
+  | { readonly ok: false; readonly error: SourcePackageClosureError };
+
+function closureError(
+  declaredGuids: readonly string[],
+  producedGuids: readonly string[],
+): SourcePackageClosureError {
+  const declared = new Set(declaredGuids.map((guid) => guid.toLowerCase()));
+  const produced = new Set(producedGuids.map((guid) => guid.toLowerCase()));
+  const counts = new Map<string, number>();
+  for (const guid of producedGuids) {
+    const key = guid.toLowerCase();
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  const duplicateGuids = [...counts.entries()]
+    .filter(([, count]) => count > 1)
+    .map(([guid]) => guid);
+  return {
+    code: 'source-package-guid-closure-mismatch',
+    expected: 'the importer to return exactly one asset for every declared Meta GUID',
+    hint: 'repair the Meta declaration or importer output, then rebuild the whole source package',
+    detail: {
+      stage: 'closure',
+      declaredGuids,
+      producedGuids,
+      missingGuids: declaredGuids.filter((guid) => !produced.has(guid.toLowerCase())),
+      unexpectedGuids: producedGuids.filter((guid) => !declared.has(guid.toLowerCase())),
+      duplicateGuids,
+    },
+  };
+}
+
+function producedGuidsFromImportFailure(
+  declaredGuids: readonly string[],
+  detail: ImportErrorDetail,
+): readonly string[] {
+  if ('missingGuids' in detail) {
+    return declaredGuids.filter((guid) => !detail.missingGuids.includes(guid));
+  }
+  if ('unexpectedGuids' in detail) return [...declaredGuids, ...detail.unexpectedGuids];
+  return [];
+}
+
+export async function produceSourcePackage(
+  input: SourcePackageProducerInput,
+): Promise<SourcePackageProducerResult> {
+  const declaredGuids = input.meta.subAssets.map((asset) => asset.guid);
+  const result = await runImport(input.meta, input.registry, input.fs);
+  if (!result.ok) {
+    const producedGuids = producedGuidsFromImportFailure(declaredGuids, result.error.detail);
+    return {
+      ok: false,
+      error: closureError(declaredGuids, producedGuids),
+    };
+  }
+  if ('skipped' in result.value) {
+    return { ok: false, error: closureError(declaredGuids, []) };
+  }
+
+  const producedGuids = result.value.product.assets.map((asset) => asset.guid);
+  const declaredSet = new Set(declaredGuids.map((guid) => guid.toLowerCase()));
+  const producedSet = new Set(producedGuids.map((guid) => guid.toLowerCase()));
+  const hasDuplicate =
+    new Set(producedGuids.map((guid) => guid.toLowerCase())).size !== producedGuids.length;
+  const complete =
+    !hasDuplicate &&
+    declaredGuids.length === producedGuids.length &&
+    declaredGuids.every((guid) => producedSet.has(guid.toLowerCase())) &&
+    producedGuids.every((guid) => declaredSet.has(guid.toLowerCase()));
+  if (!complete) return { ok: false, error: closureError(declaredGuids, producedGuids) };
+
+  const product = result.value.product;
+  const anchorGuid = [...declaredGuids].sort((left, right) => left.localeCompare(right))[0];
+  if (anchorGuid === undefined)
+    return { ok: false, error: closureError(declaredGuids, producedGuids) };
+  return {
+    ok: true,
+    value: {
+      anchorGuid,
+      declaredGuids,
+      product,
+    },
+  };
+}
+
+export function sourcePackageAssetsByGuid(
+  source: SourcePackageProduct,
+): ReadonlyMap<string, ImportedAsset<unknown>> {
+  return new Map(source.product.assets.map((asset) => [asset.guid.toLowerCase(), asset]));
+}

package/dist/__tests__/material-import-product.unit.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=material-import-product.unit.test.d.ts.map

package/dist/__tests__/material-import-product.unit.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"material-import-product.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/material-import-product.unit.test.ts"],"names":[],"mappings":""}

package/src/__tests__/material-import-product.unit.test.ts

@@ -1,56 +0,0 @@
-import type { AssetGuid } from '@forgeax/engine-types';
-import { describe, expect, it } from 'vitest';
-import {
-  createMaterialImportProduct,
-  type MaterialImportProductInput,
-  materialImportProductReady,
-} from '../import-product.js';
-
-const input: MaterialImportProductInput = {
-  guid: 'mat-child',
-  sourcePath: 'materials/child.material.json',
-  material: {
-    kind: 'material',
-    parent: 'mat-parent' as unknown as AssetGuid,
-    values: {
-      baseColor: {
-        texture: 'texture/albedo' as unknown as AssetGuid,
-        sampler: 'sampler/linear' as unknown as AssetGuid,
-      },
-    },
-  },
-  refs: {
-    parent: ['mat-parent'],
-    textures: ['texture/albedo'],
-    samplers: ['sampler/linear'],
-    modules: ['module/pbr'],
-  },
-  sourceEvidence: { inputFingerprint: 'sha256:source', importerVersion: 'material/1' },
-};
-
-describe('material import product', () => {
-  it('keeps authored material and source evidence without runtime handles', () => {
-    const result = createMaterialImportProduct(input);
-
-    expect(result.ok).toBe(true);
-    if (!result.ok) return;
-    expect(result.value.asset.payload).toEqual(input.material);
-    expect(result.value.asset.refs.map((ref) => ref.guid)).toEqual([
-      'mat-parent',
-      'texture/albedo',
-      'sampler/linear',
-      'module/pbr',
-    ]);
-    expect(result.value.sourceEvidence).toEqual(input.sourceEvidence);
-    expect(result.value).not.toHaveProperty('compiler');
-    expect(result.value).not.toHaveProperty('handle');
-  });
-
-  it('does not claim Ready when a declared dependency is absent', () => {
-    const result = createMaterialImportProduct({ ...input, refs: { ...input.refs, parent: [] } });
-
-    expect(result.ok).toBe(true);
-    if (!result.ok) return;
-    expect(materialImportProductReady(result.value, new Set(['texture/albedo']))).toBe(false);
-  });
-});