@forgeax/engine-pack 0.1.3 → 0.1.4

package/src/catalog-builder.ts

@@ -0,0 +1,313 @@
+import { relative } from 'node:path';
+import type { PackIndexEntry, ProviderProvenance } from '@forgeax/engine-types';
+import {
+  findReservedAssetKindConflict,
+  projectExternalCatalogEntries,
+  projectPackageCatalog,
+} from './catalog-projection.js';
+import { loadAssetConfig } from './config.js';
+import { deriveAssetName } from './deriveAssetName.js';
+import { resolveAssetSource } from './resolve-asset-source.js';
+import {
+  type MetaInventoryDocument,
+  type ScanOptions,
+  type ScanSourceDeclaration,
+  scanInventory,
+} from './scanner.js';
+
+type CatalogImportMeta = Pick<
+  MetaInventoryDocument,
+  | 'importer'
+  | 'packageId'
+  | 'provenance'
+  | 'revision'
+  | 'diagnostics'
+  | 'importSettings'
+  | 'sourceOverrides'
+  | 'subAssets'
+> & {
+  readonly source: string;
+  readonly sourceRevision?: string;
+  readonly buildPack?: boolean;
+};
+
+export type CatalogBuildErrorCode =
+  | 'catalog-meta-schema-invalid'
+  | 'catalog-scan-failed'
+  | 'catalog-raw-source-unsupported'
+  | 'catalog-scriptable-pack-invalid'
+  | 'catalog-host-kind-conflict';
+
+export interface CatalogBuildError {
+  readonly code: CatalogBuildErrorCode;
+  readonly path: string;
+  readonly message: string;
+  readonly expected?: string;
+  readonly actual?: string;
+  readonly hint?: string;
+  readonly subjects?: readonly string[];
+}
+
+export type CatalogAuthority = 'authoritative' | 'degraded';
+
+export interface CatalogBuildResult {
+  readonly schemaVersion: 'catalog-legacy-v1';
+  readonly entries: readonly PackIndexEntry[];
+  readonly authority: CatalogAuthority;
+  readonly diagnostics: readonly CatalogBuildError[];
+  readonly declarations: ReadonlyMap<string, CatalogImportMeta>;
+  readonly sourceDeclarations: ReadonlyMap<string, ScanSourceDeclaration>;
+}
+
+export type CatalogProducerVisibility = (
+  input: Pick<MetaInventoryDocument, 'importer' | 'importSettings' | 'subAssets'>,
+) => boolean;
+
+export interface CatalogImporterPolicy {
+  readonly disposition: 'publish' | 'exclude' | 'missing';
+  readonly expected: string;
+  readonly hint: string;
+  readonly hostProvided: boolean;
+}
+
+export interface CatalogBuildProjectionOptions {
+  readonly base?: string;
+  readonly scanOptions?: ScanOptions;
+  readonly importerPolicy: (importer: string) => CatalogImporterPolicy;
+  readonly visibility?: CatalogProducerVisibility;
+}
+
+function sourcePathFor(cwd: string, path: string): string {
+  return relative(cwd, path).replace(/\\/g, '/');
+}
+
+export function metaPathForGuid(
+  declarations: ReadonlyMap<string, CatalogImportMeta>,
+  guid: string,
+): string | undefined {
+  const lower = guid.toLowerCase();
+  for (const [path, declaration] of declarations) {
+    if (declaration.subAssets.some((asset) => asset.guid.toLowerCase() === lower)) return path;
+  }
+  return undefined;
+}
+
+function unsupportedPolicyError(
+  path: string,
+  importer: string,
+  policy: CatalogImporterPolicy,
+): CatalogBuildError {
+  return {
+    code: 'catalog-raw-source-unsupported',
+    path,
+    message: `sidecar provider ${JSON.stringify(importer)} cannot publish a Catalog product`,
+    expected: policy.expected,
+    actual: importer,
+    hint: policy.hint,
+    subjects: [path],
+  };
+}
+
+function projectMeta(
+  rawPath: string,
+  cwd: string,
+  base: string,
+  assetPaths: Record<string, string>,
+  importerPolicy: (importer: string) => CatalogImporterPolicy,
+  sourceDeclaration: Extract<ScanSourceDeclaration, { readonly format: 'meta.json' }>,
+): {
+  readonly entries: PackIndexEntry[];
+  readonly declaration?: CatalogImportMeta;
+  readonly error?: CatalogBuildError;
+} {
+  const meta = sourceDeclaration.value;
+  const policy = importerPolicy(meta.importer);
+  if (policy.disposition !== 'publish') {
+    return { entries: [], error: unsupportedPolicyError(rawPath, meta.importer, policy) };
+  }
+  const resolved = resolveAssetSource(rawPath, meta.source, assetPaths);
+  if (!resolved.ok) {
+    return {
+      entries: [],
+      error: {
+        code: 'catalog-meta-schema-invalid',
+        path: rawPath,
+        message: `source resolution failed: ${resolved.error.code} - ${resolved.error.hint}`,
+      },
+    };
+  }
+  const sourcePath = sourcePathFor(cwd, resolved.value);
+  const packageUrl = `${base}/__forgeax-ddc/${meta.subAssets[0]?.guid?.toLowerCase() ?? 'pack'}.pack.json`;
+  const declaration: CatalogImportMeta = {
+    importer: meta.importer,
+    source: resolved.value,
+    sourceRevision: sourceDeclaration.sourceRevision,
+    ...(meta.packageId === undefined ? {} : { packageId: meta.packageId }),
+    ...(meta.provenance === undefined ? {} : { provenance: meta.provenance }),
+    ...(meta.revision === undefined ? {} : { revision: meta.revision }),
+    ...(meta.diagnostics === undefined ? {} : { diagnostics: meta.diagnostics }),
+    importSettings: meta.importSettings,
+    ...(meta.sourceOverrides === undefined ? {} : { sourceOverrides: meta.sourceOverrides }),
+    subAssets: meta.subAssets,
+  };
+  if (policy.hostProvided) {
+    const conflict = findReservedAssetKindConflict(meta.subAssets);
+    if (conflict !== undefined) {
+      return {
+        entries: [],
+        error: {
+          code: 'catalog-host-kind-conflict',
+          path: rawPath,
+          message: `registered provider ${JSON.stringify(meta.importer)} declares reserved asset kind ${JSON.stringify(conflict.kind)}`,
+          expected: 'host provider kinds must not use engine-owned Pack kinds',
+          actual: conflict.kind,
+          hint: 'rename the provider kind to a provider-owned namespace before rebuilding',
+          subjects: [rawPath],
+        },
+      };
+    }
+  }
+  return {
+    declaration,
+    entries: projectExternalCatalogEntries(meta, sourcePath, packageUrl, meta.subAssets, (output) =>
+      deriveAssetName(resolved.value, meta.subAssets.length, output.name),
+    ),
+  };
+}
+
+function projectSource(
+  path: string,
+  cwd: string,
+  base: string,
+  assetPaths: Record<string, string>,
+  importerPolicy: (importer: string) => CatalogImporterPolicy,
+  visibility: CatalogBuildProjectionOptions['visibility'],
+  sourceDeclaration: ScanSourceDeclaration,
+  declarations: Map<string, CatalogImportMeta>,
+): { readonly entries: PackIndexEntry[]; readonly error?: CatalogBuildError } {
+  if (sourceDeclaration.format === 'pack.ts') {
+    const meta = { ...sourceDeclaration.meta, source: sourcePathFor(cwd, path) };
+    const anchorGuid = meta.subAssets.map((asset) => asset.guid.toLowerCase()).sort()[0];
+    return anchorGuid === undefined
+      ? { entries: [] }
+      : {
+          entries: projectExternalCatalogEntries(
+            meta,
+            sourcePathFor(cwd, path),
+            `${base}/__forgeax-ddc/${anchorGuid}.pack.json`,
+            meta.subAssets,
+            (output) => deriveAssetName(path, meta.subAssets.length, output.name),
+          ),
+        };
+  }
+  if (sourceDeclaration.format === 'meta.json') {
+    const policy = importerPolicy(sourceDeclaration.value.importer);
+    if (
+      policy.disposition === 'publish' &&
+      visibility?.({
+        importer: sourceDeclaration.value.importer,
+        importSettings: sourceDeclaration.value.importSettings,
+        subAssets: sourceDeclaration.value.subAssets,
+      }) === false
+    ) {
+      return { entries: [] };
+    }
+    const projected = projectMeta(path, cwd, base, assetPaths, importerPolicy, sourceDeclaration);
+    if (projected.declaration !== undefined) declarations.set(path, projected.declaration);
+    return projected;
+  }
+  const parsed = sourceDeclaration.value;
+  const sourcePath = sourcePathFor(cwd, path);
+  const provenance =
+    parsed.provenance ??
+    ({ provider: 'pack', version: parsed.schemaVersion } satisfies ProviderProvenance);
+  return {
+    entries: projectPackageCatalog(
+      parsed.assets.map((asset, sourceIndex) => ({
+        ...asset,
+        sourcePath,
+        sourceIndex: asset.sourceIndex ?? sourceIndex,
+        ...(parsed.packageId === undefined ? {} : { packageId: parsed.packageId }),
+        provenance,
+        ...(parsed.revision === undefined ? {} : { revision: parsed.revision }),
+        ...(parsed.diagnostics === undefined ? {} : { diagnostics: parsed.diagnostics }),
+        name: deriveAssetName(path, parsed.assets.length, asset.name),
+      })),
+      `${base}/${sourcePath}`,
+    ),
+  };
+}
+
+function warnErrors(errors: readonly CatalogBuildError[]): void {
+  for (const error of errors) {
+    console.warn(`[forgeax-pack] catalog error ${error.code} @ ${error.path}: ${error.message}`);
+  }
+}
+
+export async function buildCatalogProjection(
+  roots: readonly string[],
+  options: CatalogBuildProjectionOptions,
+): Promise<CatalogBuildResult> {
+  const empty = (
+    authority: CatalogAuthority,
+    diagnostics: readonly CatalogBuildError[] = [],
+  ): CatalogBuildResult => ({
+    schemaVersion: 'catalog-legacy-v1',
+    entries: [],
+    authority,
+    diagnostics,
+    declarations: new Map(),
+    sourceDeclarations: new Map(),
+  });
+  if (roots.length === 0) return empty('authoritative');
+  const cwd = process.cwd();
+  const base = (options.base ?? '/').replace(/\/$/, '');
+  const scanned = await scanInventory(roots, options.scanOptions);
+  if (!scanned.ok) {
+    const message =
+      scanned.error.detail === undefined
+        ? scanned.error.message
+        : `${scanned.error.message}; detail=${JSON.stringify(scanned.error.detail)}`;
+    const error: CatalogBuildError = {
+      code: 'catalog-scan-failed',
+      path: '<scan>',
+      message,
+      expected: 'one inventory scan across all Catalog roots to pass Pack scanning',
+      actual: message,
+      hint: 'repair the roots before treating any Catalog rows as authoritative',
+      subjects: [...roots],
+    };
+    warnErrors([error]);
+    return empty('degraded', [error]);
+  }
+  const { paths, declarations: sourceDeclarations } = scanned.value;
+  const { paths: assetPaths } = loadAssetConfig(cwd);
+  const entries: PackIndexEntry[] = [];
+  const errors: CatalogBuildError[] = [];
+  const declarations = new Map<string, CatalogImportMeta>();
+  for (const path of paths) {
+    const sourceDeclaration = sourceDeclarations.get(path);
+    if (sourceDeclaration === undefined) continue;
+    const projected = projectSource(
+      path,
+      cwd,
+      base,
+      assetPaths,
+      options.importerPolicy,
+      options.visibility,
+      sourceDeclaration,
+      declarations,
+    );
+    entries.push(...projected.entries);
+    if (projected.error !== undefined) errors.push(projected.error);
+  }
+  warnErrors(errors);
+  return {
+    schemaVersion: 'catalog-legacy-v1',
+    entries,
+    authority: errors.length === 0 ? 'authoritative' : 'degraded',
+    diagnostics: errors,
+    declarations,
+    sourceDeclarations,
+  };
+}

package/src/catalog-delta.ts

@@ -0,0 +1,189 @@
+import type {
+  CatalogDelta,
+  CatalogDiagnostic,
+  CatalogRevisionWindow,
+  ImportedOutputDeclaration,
+  PackIndexEntry,
+} from '@forgeax/engine-types';
+import { catalogEntryDigest } from '@forgeax/engine-types';
+import { diffTopology } from './topology.js';
+
+function rowsByGuid(rows: readonly PackIndexEntry[]): Map<string, PackIndexEntry> {
+  return new Map(rows.map((row) => [row.guid.toLowerCase(), row]));
+}
+
+function sameRow(left: PackIndexEntry, right: PackIndexEntry): boolean {
+  return catalogEntryDigest(left) === catalogEntryDigest(right);
+}
+
+function topologyGroups(rows: readonly PackIndexEntry[]): Map<string, ImportedOutputDeclaration[]> {
+  const groups = new Map<string, ImportedOutputDeclaration[]>();
+  for (const row of rows) {
+    // Legacy catalog rows have neither producer topology field. Do not turn
+    // their incidental catalog position into a false topology claim.
+    if (row.packageId === undefined) continue;
+    if (row.sourceKey === undefined && row.sourceIndex === undefined) continue;
+    const groupId = row.packageId;
+    const group = groups.get(groupId) ?? [];
+    group.push({
+      guid: row.guid,
+      ...(row.sourceKey !== undefined ? { sourceKey: row.sourceKey } : {}),
+      sourceIndex: row.sourceIndex ?? 0,
+      kind: row.kind,
+      ...(row.name !== undefined ? { name: row.name } : {}),
+    });
+    groups.set(groupId, group);
+  }
+  return groups;
+}
+
+function revisionDiagnostic(
+  code: string,
+  expected: string,
+  actual: string,
+  hint: string,
+  rootId?: string,
+): CatalogDiagnostic {
+  return {
+    code,
+    severity: 'blocking',
+    authority: 'catalog',
+    expected,
+    actual,
+    hint,
+    ...(rootId === undefined ? {} : { subject: { type: 'package' as const, id: rootId } }),
+  };
+}
+
+function checkRevisionContinuity(
+  window: CatalogRevisionWindow,
+  hasChanges: boolean,
+): CatalogDiagnostic | undefined {
+  const baselineByRoot = new Map(window.baseline.map((point) => [point.rootId, point]));
+  const currentByRoot = new Map(window.current.map((point) => [point.rootId, point]));
+
+  for (const point of window.current) {
+    const baseline = baselineByRoot.get(point.rootId);
+    if (baseline === undefined) {
+      return revisionDiagnostic(
+        'catalog-revision-conflict',
+        'every current root must have a verified baseline',
+        point.rootId,
+        'restore the latest verified snapshot for this root before applying the delta',
+        point.rootId,
+      );
+    }
+    if (point.revision < baseline.revision) {
+      return revisionDiagnostic(
+        'catalog-revision-stale',
+        'current revision must not be older than baseline',
+        `${baseline.revision} -> ${point.revision}`,
+        'discard the stale update and request a fresh catalog snapshot',
+        point.rootId,
+      );
+    }
+    if (point.revision === baseline.revision && hasChanges) {
+      return revisionDiagnostic(
+        'catalog-revision-conflict',
+        'a changed delta must advance the root revision',
+        `${baseline.revision} -> ${point.revision}`,
+        'keep the verified baseline and serialize concurrent updates before retrying',
+        point.rootId,
+      );
+    }
+    if (point.revision > baseline.revision + 1) {
+      return revisionDiagnostic(
+        'catalog-revision-conflict',
+        'the next revision must be exactly baseline + 1',
+        `${baseline.revision} -> ${point.revision}`,
+        'request the missing revisions or rebuild from the latest verified snapshot',
+        point.rootId,
+      );
+    }
+  }
+
+  for (const point of window.baseline) {
+    if (!currentByRoot.has(point.rootId)) {
+      return revisionDiagnostic(
+        'catalog-revision-conflict',
+        'every baseline root must be present in the current revision set',
+        point.rootId,
+        'do not apply a partial root set over the verified baseline',
+        point.rootId,
+      );
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Derives one neutral delta from consecutive complete catalog projections.
+ *
+ * The returned fields are canonical POD fields: topology, revision continuity,
+ * authority, and diagnostics remain structured so AI consumers do not parse
+ * producer or transport messages. Degraded results intentionally contain no
+ * added, changed, or removed identity rows.
+ */
+export function calculateCatalogDelta(
+  previous: readonly PackIndexEntry[],
+  next: readonly PackIndexEntry[],
+  revision?: CatalogRevisionWindow,
+): CatalogDelta | undefined {
+  const before = rowsByGuid(previous);
+  const after = rowsByGuid(next);
+  const added: PackIndexEntry[] = [];
+  const changed: PackIndexEntry[] = [];
+  const removed: string[] = [];
+
+  for (const [guid, row] of after) {
+    const prior = before.get(guid);
+    if (prior === undefined) added.push(row);
+    else if (!sameRow(prior, row)) changed.push(row);
+  }
+  for (const guid of before.keys()) {
+    if (!after.has(guid)) removed.push(guid);
+  }
+
+  const previousGroups = topologyGroups(previous);
+  const nextGroups = topologyGroups(next);
+  const topology = [];
+  const groupIds = new Set([...previousGroups.keys(), ...nextGroups.keys()]);
+  for (const groupId of groupIds) {
+    const diff = diffTopology(previousGroups.get(groupId) ?? [], nextGroups.get(groupId) ?? []);
+    if (
+      diff.added.length > 0 ||
+      diff.removed.length > 0 ||
+      diff.changedKind.length > 0 ||
+      diff.ambiguous.length > 0
+    ) {
+      topology.push(diff);
+    }
+  }
+
+  const hasChanges =
+    added.length > 0 || changed.length > 0 || removed.length > 0 || topology.length > 0;
+  if (!hasChanges) return undefined;
+
+  const delta = { added, changed, removed, ...(topology.length > 0 ? { topology } : {}) };
+  if (revision === undefined) return delta;
+
+  const diagnostic = checkRevisionContinuity(revision, hasChanges);
+  if (diagnostic !== undefined) {
+    return {
+      added: [],
+      changed: [],
+      removed: [],
+      authority: 'degraded',
+      diagnostics: [diagnostic],
+      revisions: revision,
+    };
+  }
+
+  return {
+    ...delta,
+    authority: 'authoritative',
+    diagnostics: [],
+    revisions: revision,
+  };
+}