@prisma-next/core-control-plane 0.3.0-dev.2 → 0.3.0-dev.20

package/src/config-validation.ts

@@ -0,0 +1,270 @@
+import type { PrismaNextConfig } from './config-types';
+import { errorConfigValidation } from './errors';
+
+/**
+ * Validates that the config has the required structure.
+ * This is pure validation logic with no file I/O or CLI awareness.
+ *
+ * @param config - Config object to validate
+ * @throws CliStructuredError if config structure is invalid
+ */
+export function validateConfig(config: unknown): asserts config is PrismaNextConfig {
+  if (!config || typeof config !== 'object') {
+    throw errorConfigValidation('object', {
+      why: 'Config must be an object',
+    });
+  }
+
+  const configObj = config as Record<string, unknown>;
+
+  if (!configObj['family']) {
+    throw errorConfigValidation('family');
+  }
+
+  if (!configObj['target']) {
+    throw errorConfigValidation('target');
+  }
+
+  if (!configObj['adapter']) {
+    throw errorConfigValidation('adapter');
+  }
+
+  // Validate family descriptor
+  const family = configObj['family'] as Record<string, unknown>;
+  if (family['kind'] !== 'family') {
+    throw errorConfigValidation('family.kind', {
+      why: 'Config.family must have kind: "family"',
+    });
+  }
+  if (typeof family['familyId'] !== 'string') {
+    throw errorConfigValidation('family.familyId', {
+      why: 'Config.family must have familyId: string',
+    });
+  }
+  if (typeof family['version'] !== 'string') {
+    throw errorConfigValidation('family.version', {
+      why: 'Config.family must have version: string',
+    });
+  }
+  if (!family['hook'] || typeof family['hook'] !== 'object') {
+    throw errorConfigValidation('family.hook', {
+      why: 'Config.family must have hook: TargetFamilyHook',
+    });
+  }
+  if (typeof family['create'] !== 'function') {
+    throw errorConfigValidation('family.create', {
+      why: 'Config.family must have create: function',
+    });
+  }
+
+  const familyId = family['familyId'] as string;
+
+  // Validate target descriptor
+  const target = configObj['target'] as Record<string, unknown>;
+  if (target['kind'] !== 'target') {
+    throw errorConfigValidation('target.kind', {
+      why: 'Config.target must have kind: "target"',
+    });
+  }
+  if (typeof target['id'] !== 'string') {
+    throw errorConfigValidation('target.id', {
+      why: 'Config.target must have id: string',
+    });
+  }
+  if (typeof target['familyId'] !== 'string') {
+    throw errorConfigValidation('target.familyId', {
+      why: 'Config.target must have familyId: string',
+    });
+  }
+  if (typeof target['version'] !== 'string') {
+    throw errorConfigValidation('target.version', {
+      why: 'Config.target must have version: string',
+    });
+  }
+  if (target['familyId'] !== familyId) {
+    throw errorConfigValidation('target.familyId', {
+      why: `Config.target.familyId must match Config.family.familyId (expected: ${familyId}, got: ${target['familyId']})`,
+    });
+  }
+  if (typeof target['targetId'] !== 'string') {
+    throw errorConfigValidation('target.targetId', {
+      why: 'Config.target must have targetId: string',
+    });
+  }
+  if (typeof target['create'] !== 'function') {
+    throw errorConfigValidation('target.create', {
+      why: 'Config.target must have create: function',
+    });
+  }
+  const expectedTargetId = target['targetId'] as string;
+
+  // Validate adapter descriptor
+  const adapter = configObj['adapter'] as Record<string, unknown>;
+  if (adapter['kind'] !== 'adapter') {
+    throw errorConfigValidation('adapter.kind', {
+      why: 'Config.adapter must have kind: "adapter"',
+    });
+  }
+  if (typeof adapter['id'] !== 'string') {
+    throw errorConfigValidation('adapter.id', {
+      why: 'Config.adapter must have id: string',
+    });
+  }
+  if (typeof adapter['familyId'] !== 'string') {
+    throw errorConfigValidation('adapter.familyId', {
+      why: 'Config.adapter must have familyId: string',
+    });
+  }
+  if (typeof adapter['version'] !== 'string') {
+    throw errorConfigValidation('adapter.version', {
+      why: 'Config.adapter must have version: string',
+    });
+  }
+  if (adapter['familyId'] !== familyId) {
+    throw errorConfigValidation('adapter.familyId', {
+      why: `Config.adapter.familyId must match Config.family.familyId (expected: ${familyId}, got: ${adapter['familyId']})`,
+    });
+  }
+  if (typeof adapter['targetId'] !== 'string') {
+    throw errorConfigValidation('adapter.targetId', {
+      why: 'Config.adapter must have targetId: string',
+    });
+  }
+  if (adapter['targetId'] !== expectedTargetId) {
+    throw errorConfigValidation('adapter.targetId', {
+      why: `Config.adapter.targetId must match Config.target.targetId (expected: ${expectedTargetId}, got: ${adapter['targetId']})`,
+    });
+  }
+  if (typeof adapter['create'] !== 'function') {
+    throw errorConfigValidation('adapter.create', {
+      why: 'Config.adapter must have create: function',
+    });
+  }
+
+  // Validate extensions array if present
+  if (configObj['extensions'] !== undefined) {
+    if (!Array.isArray(configObj['extensions'])) {
+      throw errorConfigValidation('extensions', {
+        why: 'Config.extensions must be an array',
+      });
+    }
+    for (const ext of configObj['extensions']) {
+      if (!ext || typeof ext !== 'object') {
+        throw errorConfigValidation('extensions[]', {
+          why: 'Config.extensions must contain ExtensionDescriptor objects',
+        });
+      }
+      const extObj = ext as Record<string, unknown>;
+      if (extObj['kind'] !== 'extension') {
+        throw errorConfigValidation('extensions[].kind', {
+          why: 'Config.extensions items must have kind: "extension"',
+        });
+      }
+      if (typeof extObj['id'] !== 'string') {
+        throw errorConfigValidation('extensions[].id', {
+          why: 'Config.extensions items must have id: string',
+        });
+      }
+      if (typeof extObj['familyId'] !== 'string') {
+        throw errorConfigValidation('extensions[].familyId', {
+          why: 'Config.extensions items must have familyId: string',
+        });
+      }
+      if (typeof extObj['version'] !== 'string') {
+        throw errorConfigValidation('extensions[].version', {
+          why: 'Config.extensions items must have version: string',
+        });
+      }
+      if (extObj['familyId'] !== familyId) {
+        throw errorConfigValidation('extensions[].familyId', {
+          why: `Config.extensions[].familyId must match Config.family.familyId (expected: ${familyId}, got: ${extObj['familyId']})`,
+        });
+      }
+      if (typeof extObj['targetId'] !== 'string') {
+        throw errorConfigValidation('extensions[].targetId', {
+          why: 'Config.extensions items must have targetId: string',
+        });
+      }
+      if (extObj['targetId'] !== expectedTargetId) {
+        throw errorConfigValidation('extensions[].targetId', {
+          why: `Config.extensions[].targetId must match Config.target.targetId (expected: ${expectedTargetId}, got: ${extObj['targetId']})`,
+        });
+      }
+      if (typeof extObj['create'] !== 'function') {
+        throw errorConfigValidation('extensions[].create', {
+          why: 'Config.extensions items must have create: function',
+        });
+      }
+    }
+  }
+
+  // Validate driver descriptor if present
+  if (configObj['driver'] !== undefined) {
+    const driver = configObj['driver'] as Record<string, unknown>;
+    if (driver['kind'] !== 'driver') {
+      throw errorConfigValidation('driver.kind', {
+        why: 'Config.driver must have kind: "driver"',
+      });
+    }
+    if (typeof driver['id'] !== 'string') {
+      throw errorConfigValidation('driver.id', {
+        why: 'Config.driver must have id: string',
+      });
+    }
+    if (typeof driver['version'] !== 'string') {
+      throw errorConfigValidation('driver.version', {
+        why: 'Config.driver must have version: string',
+      });
+    }
+    if (typeof driver['familyId'] !== 'string') {
+      throw errorConfigValidation('driver.familyId', {
+        why: 'Config.driver must have familyId: string',
+      });
+    }
+    if (driver['familyId'] !== familyId) {
+      throw errorConfigValidation('driver.familyId', {
+        why: `Config.driver.familyId must match Config.family.familyId (expected: ${familyId}, got: ${driver['familyId']})`,
+      });
+    }
+    if (typeof driver['targetId'] !== 'string') {
+      throw errorConfigValidation('driver.targetId', {
+        why: 'Config.driver must have targetId: string',
+      });
+    }
+    if (driver['targetId'] !== expectedTargetId) {
+      throw errorConfigValidation('driver.targetId', {
+        why: `Config.driver.targetId must match Config.target.targetId (expected: ${expectedTargetId}, got: ${driver['targetId']})`,
+      });
+    }
+    if (typeof driver['create'] !== 'function') {
+      throw errorConfigValidation('driver.create', {
+        why: 'Config.driver must have create: function',
+      });
+    }
+  }
+
+  // Validate contract config if present (structure validation - defineConfig() handles normalization)
+  if (configObj['contract'] !== undefined) {
+    const contract = configObj['contract'] as Record<string, unknown>;
+    if (!contract || typeof contract !== 'object') {
+      throw errorConfigValidation('contract', {
+        why: 'Config.contract must be an object',
+      });
+    }
+    if (!('source' in contract)) {
+      throw errorConfigValidation('contract.source', {
+        why: 'Config.contract.source is required when contract is provided',
+      });
+    }
+    if (contract['output'] !== undefined && typeof contract['output'] !== 'string') {
+      throw errorConfigValidation('contract.output', {
+        why: 'Config.contract.output must be a string when provided',
+      });
+    }
+    if (contract['types'] !== undefined && typeof contract['types'] !== 'string') {
+      throw errorConfigValidation('contract.types', {
+        why: 'Config.contract.types must be a string when provided',
+      });
+    }
+  }
+}

package/src/emission/canonicalization.ts

@@ -0,0 +1,253 @@
+import type { ContractIR } from '@prisma-next/contract/ir';
+import { isArrayEqual } from '@prisma-next/utils/array-equal';
+
+type NormalizedContract = {
+  schemaVersion: string;
+  targetFamily: string;
+  target: string;
+  coreHash?: string;
+  profileHash?: string;
+  models: Record<string, unknown>;
+  relations: Record<string, unknown>;
+  storage: Record<string, unknown>;
+  extensionPacks: Record<string, unknown>;
+  capabilities: Record<string, Record<string, boolean>>;
+  meta: Record<string, unknown>;
+  sources: Record<string, unknown>;
+};
+
+const TOP_LEVEL_ORDER = [
+  'schemaVersion',
+  'canonicalVersion',
+  'targetFamily',
+  'target',
+  'coreHash',
+  'profileHash',
+  'models',
+  'storage',
+  'capabilities',
+  'extensionPacks',
+  'meta',
+  'sources',
+] as const;
+
+function isDefaultValue(value: unknown): boolean {
+  if (value === false) return true;
+  if (value === null) return false;
+  if (Array.isArray(value) && value.length === 0) return true;
+  if (typeof value === 'object' && value !== null) {
+    const keys = Object.keys(value);
+    return keys.length === 0;
+  }
+  return false;
+}
+
+function omitDefaults(obj: unknown, path: readonly string[]): unknown {
+  if (obj === null || typeof obj !== 'object') {
+    return obj;
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map((item) => omitDefaults(item, path));
+  }
+
+  const result: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(obj)) {
+    const currentPath = [...path, key];
+
+    // Exclude metadata fields from canonicalization
+    if (key === '_generated') {
+      continue;
+    }
+
+    if (key === 'nullable' && value === false) {
+      continue;
+    }
+
+    if (key === 'generated' && value === false) {
+      continue;
+    }
+
+    if (isDefaultValue(value)) {
+      const isRequiredModels = isArrayEqual(currentPath, ['models']);
+      const isRequiredTables = isArrayEqual(currentPath, ['storage', 'tables']);
+      const isRequiredRelations = isArrayEqual(currentPath, ['relations']);
+      const isRequiredExtensionPacks = isArrayEqual(currentPath, ['extensionPacks']);
+      const isRequiredCapabilities = isArrayEqual(currentPath, ['capabilities']);
+      const isRequiredMeta = isArrayEqual(currentPath, ['meta']);
+      const isRequiredSources = isArrayEqual(currentPath, ['sources']);
+      const isExtensionNamespace = currentPath.length === 2 && currentPath[0] === 'extensionPacks';
+      const isModelRelations =
+        currentPath.length === 3 &&
+        isArrayEqual([currentPath[0], currentPath[2]], ['models', 'relations']);
+      const isTableUniques =
+        currentPath.length === 4 &&
+        isArrayEqual(
+          [currentPath[0], currentPath[1], currentPath[3]],
+          ['storage', 'tables', 'uniques'],
+        );
+      const isTableIndexes =
+        currentPath.length === 4 &&
+        isArrayEqual(
+          [currentPath[0], currentPath[1], currentPath[3]],
+          ['storage', 'tables', 'indexes'],
+        );
+      const isTableForeignKeys =
+        currentPath.length === 4 &&
+        isArrayEqual(
+          [currentPath[0], currentPath[1], currentPath[3]],
+          ['storage', 'tables', 'foreignKeys'],
+        );
+
+      if (
+        !isRequiredModels &&
+        !isRequiredTables &&
+        !isRequiredRelations &&
+        !isRequiredExtensionPacks &&
+        !isRequiredCapabilities &&
+        !isRequiredMeta &&
+        !isRequiredSources &&
+        !isExtensionNamespace &&
+        !isModelRelations &&
+        !isTableUniques &&
+        !isTableIndexes &&
+        !isTableForeignKeys
+      ) {
+        continue;
+      }
+    }
+
+    result[key] = omitDefaults(value, currentPath);
+  }
+
+  return result;
+}
+
+function sortObjectKeys(obj: unknown): unknown {
+  if (obj === null || typeof obj !== 'object') {
+    return obj;
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map((item) => sortObjectKeys(item));
+  }
+
+  const sorted: Record<string, unknown> = {};
+  const keys = Object.keys(obj).sort();
+  for (const key of keys) {
+    sorted[key] = sortObjectKeys((obj as Record<string, unknown>)[key]);
+  }
+
+  return sorted;
+}
+
+type StorageObject = {
+  tables?: Record<string, unknown>;
+  [key: string]: unknown;
+};
+
+type TableObject = {
+  indexes?: unknown[];
+  uniques?: unknown[];
+  [key: string]: unknown;
+};
+
+function sortIndexesAndUniques(storage: unknown): unknown {
+  if (!storage || typeof storage !== 'object') {
+    return storage;
+  }
+
+  const storageObj = storage as StorageObject;
+  if (!storageObj.tables || typeof storageObj.tables !== 'object') {
+    return storage;
+  }
+
+  const tables = storageObj.tables;
+  const result: StorageObject = { ...storageObj };
+
+  result.tables = {};
+  // Sort table names to ensure deterministic ordering
+  const sortedTableNames = Object.keys(tables).sort();
+  for (const tableName of sortedTableNames) {
+    const table = tables[tableName];
+    if (!table || typeof table !== 'object') {
+      result.tables[tableName] = table;
+      continue;
+    }
+
+    const tableObj = table as TableObject;
+    const sortedTable: TableObject = { ...tableObj };
+
+    if (Array.isArray(tableObj.indexes)) {
+      sortedTable.indexes = [...tableObj.indexes].sort((a, b) => {
+        const nameA = (a as { name?: string })?.name || '';
+        const nameB = (b as { name?: string })?.name || '';
+        return nameA.localeCompare(nameB);
+      });
+    }
+
+    if (Array.isArray(tableObj.uniques)) {
+      sortedTable.uniques = [...tableObj.uniques].sort((a, b) => {
+        const nameA = (a as { name?: string })?.name || '';
+        const nameB = (b as { name?: string })?.name || '';
+        return nameA.localeCompare(nameB);
+      });
+    }
+
+    result.tables[tableName] = sortedTable;
+  }
+
+  return result;
+}
+
+function orderTopLevel(obj: Record<string, unknown>): Record<string, unknown> {
+  const ordered: Record<string, unknown> = {};
+  const remaining = new Set(Object.keys(obj));
+
+  for (const key of TOP_LEVEL_ORDER) {
+    if (remaining.has(key)) {
+      ordered[key] = obj[key];
+      remaining.delete(key);
+    }
+  }
+
+  for (const key of Array.from(remaining).sort()) {
+    ordered[key] = obj[key];
+  }
+
+  return ordered;
+}
+
+export function canonicalizeContract(
+  ir: ContractIR & { coreHash?: string; profileHash?: string },
+): string {
+  const normalized: NormalizedContract = {
+    schemaVersion: ir.schemaVersion,
+    targetFamily: ir.targetFamily,
+    target: ir.target,
+    models: ir.models,
+    relations: ir.relations,
+    storage: ir.storage,
+    extensionPacks: ir.extensionPacks,
+    capabilities: ir.capabilities,
+    meta: ir.meta,
+    sources: ir.sources,
+  };
+
+  if (ir.coreHash !== undefined) {
+    normalized.coreHash = ir.coreHash;
+  }
+
+  if (ir.profileHash !== undefined) {
+    normalized.profileHash = ir.profileHash;
+  }
+
+  const withDefaultsOmitted = omitDefaults(normalized, []) as NormalizedContract;
+  const withSortedIndexes = sortIndexesAndUniques(withDefaultsOmitted.storage);
+  const withSortedStorage = { ...withDefaultsOmitted, storage: withSortedIndexes };
+  const withSortedKeys = sortObjectKeys(withSortedStorage) as Record<string, unknown>;
+  const withOrderedTopLevel = orderTopLevel(withSortedKeys);
+
+  return JSON.stringify(withOrderedTopLevel, null, 2);
+}

package/src/emission/emit.ts

@@ -0,0 +1,118 @@
+import type { ContractIR } from '@prisma-next/contract/ir';
+import type { TargetFamilyHook, ValidationContext } from '@prisma-next/contract/types';
+import { format } from 'prettier';
+import { canonicalizeContract } from './canonicalization';
+import { computeCoreHash, computeProfileHash } from './hashing';
+import type { EmitOptions, EmitResult } from './types';
+
+function validateCoreStructure(ir: ContractIR): void {
+  if (!ir.targetFamily) {
+    throw new Error('ContractIR must have targetFamily');
+  }
+  if (!ir.target) {
+    throw new Error('ContractIR must have target');
+  }
+  if (!ir.schemaVersion) {
+    throw new Error('ContractIR must have schemaVersion');
+  }
+  if (!ir.models || typeof ir.models !== 'object') {
+    throw new Error('ContractIR must have models');
+  }
+  if (!ir.storage || typeof ir.storage !== 'object') {
+    throw new Error('ContractIR must have storage');
+  }
+  if (!ir.relations || typeof ir.relations !== 'object') {
+    throw new Error('ContractIR must have relations');
+  }
+  if (!ir.extensionPacks || typeof ir.extensionPacks !== 'object') {
+    throw new Error('ContractIR must have extensionPacks');
+  }
+  if (!ir.capabilities || typeof ir.capabilities !== 'object') {
+    throw new Error('ContractIR must have capabilities');
+  }
+  if (!ir.meta || typeof ir.meta !== 'object') {
+    throw new Error('ContractIR must have meta');
+  }
+  if (!ir.sources || typeof ir.sources !== 'object') {
+    throw new Error('ContractIR must have sources');
+  }
+}
+
+export async function emit(
+  ir: ContractIR,
+  options: EmitOptions,
+  targetFamily: TargetFamilyHook,
+): Promise<EmitResult> {
+  const { operationRegistry, codecTypeImports, operationTypeImports, extensionIds } = options;
+
+  validateCoreStructure(ir);
+
+  const ctx: ValidationContext = {
+    ...(operationRegistry ? { operationRegistry } : {}),
+    ...(codecTypeImports ? { codecTypeImports } : {}),
+    ...(operationTypeImports ? { operationTypeImports } : {}),
+    ...(extensionIds ? { extensionIds } : {}),
+  };
+  targetFamily.validateTypes(ir, ctx);
+
+  targetFamily.validateStructure(ir);
+
+  const contractJson = {
+    schemaVersion: ir.schemaVersion,
+    targetFamily: ir.targetFamily,
+    target: ir.target,
+    models: ir.models,
+    relations: ir.relations,
+    storage: ir.storage,
+    extensionPacks: ir.extensionPacks,
+    capabilities: ir.capabilities,
+    meta: ir.meta,
+    sources: ir.sources,
+  } as const;
+
+  const coreHash = computeCoreHash(contractJson);
+  const profileHash = computeProfileHash(contractJson);
+
+  const contractWithHashes: ContractIR & { coreHash?: string; profileHash?: string } = {
+    ...ir,
+    schemaVersion: contractJson.schemaVersion,
+    coreHash,
+    profileHash,
+  };
+
+  // Add _generated metadata to indicate this is a generated artifact
+  // This ensures consistency between CLI emit and programmatic emit
+  // Always add/update _generated with standard content for consistency
+  const contractJsonObj = JSON.parse(canonicalizeContract(contractWithHashes)) as Record<
+    string,
+    unknown
+  >;
+  const contractJsonWithMeta = {
+    ...contractJsonObj,
+    _generated: {
+      warning: '⚠️  GENERATED FILE - DO NOT EDIT',
+      message: 'This file is automatically generated by "prisma-next contract emit".',
+      regenerate: 'To regenerate, run: prisma-next contract emit',
+    },
+  };
+  const contractJsonString = JSON.stringify(contractJsonWithMeta, null, 2);
+
+  const contractDtsRaw = targetFamily.generateContractTypes(
+    ir,
+    codecTypeImports ?? [],
+    operationTypeImports ?? [],
+  );
+  const contractDts = await format(contractDtsRaw, {
+    parser: 'typescript',
+    singleQuote: true,
+    semi: true,
+    printWidth: 100,
+  });
+
+  return {
+    contractJson: contractJsonString,
+    contractDts,
+    coreHash,
+    profileHash,
+  };
+}

package/src/emission/hashing.ts

@@ -0,0 +1,57 @@
+import { createHash } from 'node:crypto';
+import type { ContractIR } from '@prisma-next/contract/ir';
+import { canonicalizeContract } from './canonicalization';
+
+type ContractInput = {
+  schemaVersion: string;
+  targetFamily: string;
+  target: string;
+  models: Record<string, unknown>;
+  relations: Record<string, unknown>;
+  storage: Record<string, unknown>;
+  extensionPacks: Record<string, unknown>;
+  sources: Record<string, unknown>;
+  capabilities: Record<string, Record<string, boolean>>;
+  meta: Record<string, unknown>;
+  [key: string]: unknown;
+};
+
+function computeHash(content: string): string {
+  const hash = createHash('sha256');
+  hash.update(content);
+  return `sha256:${hash.digest('hex')}`;
+}
+
+export function computeCoreHash(contract: ContractInput): string {
+  const coreContract: ContractIR = {
+    schemaVersion: contract.schemaVersion,
+    targetFamily: contract.targetFamily,
+    target: contract.target,
+    models: contract.models,
+    relations: contract.relations,
+    storage: contract.storage,
+    extensionPacks: contract.extensionPacks,
+    sources: contract.sources,
+    capabilities: contract.capabilities,
+    meta: contract.meta,
+  };
+  const canonical = canonicalizeContract(coreContract);
+  return computeHash(canonical);
+}
+
+export function computeProfileHash(contract: ContractInput): string {
+  const profileContract: ContractIR = {
+    schemaVersion: contract.schemaVersion,
+    targetFamily: contract.targetFamily,
+    target: contract.target,
+    models: {},
+    relations: {},
+    storage: {},
+    extensionPacks: {},
+    capabilities: contract.capabilities,
+    meta: {},
+    sources: {},
+  };
+  const canonical = canonicalizeContract(profileContract);
+  return computeHash(canonical);
+}