@prisma-next/core-control-plane 0.3.0-dev.1 → 0.3.0-dev.100

package/package.json

@@ -1,60 +1,53 @@
 {
   "name": "@prisma-next/core-control-plane",
-  "version": "0.3.0-dev.1",
+  "version": "0.3.0-dev.100",
   "type": "module",
   "sideEffects": false,
-  "description": "Control plane domain actions, config types, validation, and error factories for Prisma Next",
+  "description": "Control-plane migration/emission primitives and structured error utilities",
   "dependencies": {
     "arktype": "^2.1.26",
     "prettier": "^3.3.3",
-    "@prisma-next/contract": "0.3.0-dev.1",
-    "@prisma-next/operations": "0.3.0-dev.1",
-    "@prisma-next/utils": "0.3.0-dev.1"
+    "@prisma-next/operations": "0.3.0-dev.100",
+    "@prisma-next/utils": "0.3.0-dev.100",
+    "@prisma-next/contract": "0.3.0-dev.100"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "^4.0.0",
-    "tsup": "^8.3.0",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.16",
+    "tsdown": "0.18.4",
+    "typescript": "5.9.3",
+    "vitest": "4.0.17",
+    "@prisma-next/tsdown": "0.0.0",
+    "@prisma-next/tsconfig": "0.0.0",
     "@prisma-next/test-utils": "0.0.1"
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
+  "engines": {
+    "node": ">=20"
+  },
   "exports": {
-    "./config-types": {
-      "types": "./dist/exports/config-types.d.ts",
-      "import": "./dist/exports/config-types.js"
-    },
-    "./config-validation": {
-      "types": "./dist/exports/config-validation.d.ts",
-      "import": "./dist/exports/config-validation.js"
-    },
-    "./errors": {
-      "types": "./dist/exports/errors.d.ts",
-      "import": "./dist/exports/errors.js"
-    },
-    "./types": {
-      "types": "./dist/exports/types.d.ts",
-      "import": "./dist/exports/types.js"
-    },
-    "./emission": {
-      "types": "./dist/exports/emission.d.ts",
-      "import": "./dist/exports/emission.js"
-    },
-    "./schema-view": {
-      "types": "./dist/exports/schema-view.d.ts",
-      "import": "./dist/exports/schema-view.js"
-    }
+    "./constants": "./dist/constants.mjs",
+    "./emission": "./dist/emission.mjs",
+    "./errors": "./dist/errors.mjs",
+    "./schema-view": "./dist/schema-view.mjs",
+    "./stack": "./dist/stack.mjs",
+    "./types": "./dist/types.mjs",
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prisma/prisma-next.git",
+    "directory": "packages/1-framework/1-core/migration/control-plane"
   },
   "scripts": {
-    "build": "tsup --config tsup.config.ts",
+    "build": "tsdown",
     "test": "vitest run --passWithNoTests",
     "test:coverage": "vitest run --coverage --passWithNoTests",
-    "typecheck": "tsc --project tsconfig.json --noEmit",
-    "lint": "biome check . --config-path ../../../../../biome.json --error-on-warnings",
-    "lint:fix": "biome check --write . --config-path ../../../biome.json",
-    "lint:fix:unsafe": "biome check --write --unsafe . --config-path ../../../biome.json",
-    "clean": "node ../../../../../scripts/clean.mjs"
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check . --error-on-warnings",
+    "lint:fix": "biome check --write .",
+    "lint:fix:unsafe": "biome check --write --unsafe .",
+    "clean": "rm -rf dist dist-tsc dist-tsc-prod coverage .tmp-output"
   }
 }

package/src/constants.ts

@@ -0,0 +1,5 @@
+/**
+ * Sentinel value representing the absence of a contract (empty/new project).
+ * This is a human-readable marker, not a real SHA-256 hash.
+ */
+export const EMPTY_CONTRACT_HASH = 'sha256:empty' as const;

package/src/emission/canonicalization.ts

@@ -0,0 +1,300 @@
+import { bigintJsonReplacer } from '@prisma-next/contract/types';
+import { isArrayEqual } from '@prisma-next/utils/array-equal';
+import { ifDefined } from '@prisma-next/utils/defined';
+
+type NormalizedContract = {
+  schemaVersion: string;
+  targetFamily: string;
+  target: string;
+  storageHash?: string;
+  executionHash?: string;
+  profileHash?: string;
+  models: Record<string, unknown>;
+  relations: Record<string, unknown>;
+  storage: Record<string, unknown>;
+  execution?: Record<string, unknown>;
+  extensionPacks: Record<string, unknown>;
+  capabilities: Record<string, Record<string, boolean>>;
+  meta: Record<string, unknown>;
+};
+
+export type CanonicalContractInput = {
+  schemaVersion: string;
+  targetFamily: string;
+  target: string;
+  models: Record<string, unknown>;
+  relations: Record<string, unknown>;
+  storage: Record<string, unknown>;
+  execution?: Record<string, unknown>;
+  extensionPacks: Record<string, unknown>;
+  capabilities: Record<string, Record<string, boolean>>;
+  meta: Record<string, unknown>;
+  storageHash?: string;
+  executionHash?: string;
+  profileHash?: string;
+};
+
+const TOP_LEVEL_ORDER = [
+  'schemaVersion',
+  'canonicalVersion',
+  'targetFamily',
+  'target',
+  'storageHash',
+  'executionHash',
+  'profileHash',
+  'models',
+  'relations',
+  'storage',
+  'execution',
+  'capabilities',
+  'extensionPacks',
+  'meta',
+] as const;
+
+function isDefaultValue(value: unknown): boolean {
+  if (value === false) return true;
+  if (value === null) return false;
+  if (value instanceof Date) 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 (obj instanceof Date) {
+    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;
+    }
+
+    // Strip 'noAction' referential actions (the database default) for hash stability.
+    // A contract with explicit `onDelete: 'noAction'` is semantically identical to
+    // one that omits `onDelete` entirely, so they should produce the same hash.
+    if ((key === 'onDelete' || key === 'onUpdate') && value === 'noAction') {
+      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 isRequiredExecutionDefaults = isArrayEqual(currentPath, [
+        'execution',
+        'mutations',
+        'defaults',
+      ]);
+      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'],
+        );
+
+      // Preserve per-FK `constraint` and `index` booleans (even when `false`)
+      // so that hash distinguishes `false` from absent.
+      // Path: ['storage', 'tables', <tableName>, 'foreignKeys', 'constraint' | 'index']
+      const isFkBooleanField =
+        currentPath.length === 5 &&
+        currentPath[0] === 'storage' &&
+        currentPath[1] === 'tables' &&
+        currentPath[3] === 'foreignKeys' &&
+        (key === 'constraint' || key === 'index');
+
+      if (
+        !isRequiredModels &&
+        !isRequiredTables &&
+        !isRequiredRelations &&
+        !isRequiredExtensionPacks &&
+        !isRequiredCapabilities &&
+        !isRequiredMeta &&
+        !isRequiredExecutionDefaults &&
+        !isExtensionNamespace &&
+        !isModelRelations &&
+        !isTableUniques &&
+        !isTableIndexes &&
+        !isTableForeignKeys &&
+        !isFkBooleanField
+      ) {
+        continue;
+      }
+    }
+
+    result[key] = omitDefaults(value, currentPath);
+  }
+
+  return result;
+}
+
+function sortObjectKeys(obj: unknown): unknown {
+  if (obj === null || typeof obj !== 'object') {
+    return obj;
+  }
+
+  if (obj instanceof Date) {
+    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: CanonicalContractInput): string {
+  const normalized: NormalizedContract = {
+    schemaVersion: ir.schemaVersion,
+    targetFamily: ir.targetFamily,
+    target: ir.target,
+    models: ir.models,
+    relations: ir.relations,
+    storage: ir.storage,
+    ...ifDefined('execution', ir.execution),
+    extensionPacks: ir.extensionPacks,
+    capabilities: ir.capabilities,
+    meta: ir.meta,
+  };
+  Object.assign(
+    normalized,
+    ifDefined('storageHash', ir.storageHash),
+    ifDefined('executionHash', ir.executionHash),
+    ifDefined('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, bigintJsonReplacer, 2);
+}

package/src/emission/emit.ts

@@ -0,0 +1,181 @@
+import type { ContractIR } from '@prisma-next/contract/ir';
+import type { TargetFamilyHook, ValidationContext } from '@prisma-next/contract/types';
+import { ifDefined } from '@prisma-next/utils/defined';
+import { type } from 'arktype';
+import { format } from 'prettier';
+import { canonicalizeContract } from './canonicalization';
+import { computeExecutionHash, computeProfileHash, computeStorageHash } from './hashing';
+import type { EmitOptions, EmitResult } from './types';
+
+const CanonicalMetaSchema = type({
+  '[string]': 'unknown',
+});
+
+const CanonicalContractSchema = type({
+  '+': 'reject',
+  schemaVersion: 'string',
+  targetFamily: 'string',
+  target: 'string',
+  models: type({ '[string]': 'unknown' }),
+  relations: type({ '[string]': 'unknown' }),
+  storage: type({ '[string]': 'unknown' }),
+  'execution?': type({ '[string]': 'unknown' }),
+  extensionPacks: type({ '[string]': 'unknown' }),
+  capabilities: type({
+    '[string]': type({
+      '[string]': 'boolean',
+    }),
+  }),
+  meta: CanonicalMetaSchema,
+});
+
+function assertCanonicalArtifactShape(value: unknown): void {
+  const result = CanonicalContractSchema(value);
+  if (result instanceof type.errors) {
+    const issues = result
+      .map((error) => {
+        const path = error.path?.toString() ?? '<root>';
+        return `${path}: ${error.message}`;
+      })
+      .join('; ');
+    throw new Error(`ContractIR canonical artifact validation failed: ${issues}`);
+  }
+}
+
+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');
+  }
+}
+
+export async function emit(
+  ir: ContractIR,
+  options: EmitOptions,
+  targetFamily: TargetFamilyHook,
+): Promise<EmitResult> {
+  const {
+    operationRegistry,
+    codecTypeImports,
+    operationTypeImports,
+    extensionIds,
+    parameterizedRenderers,
+    parameterizedTypeImports,
+    queryOperationTypeImports,
+  } = options;
+
+  validateCoreStructure(ir);
+
+  const ctx: ValidationContext = {
+    ...ifDefined('operationRegistry', operationRegistry),
+    ...ifDefined('codecTypeImports', codecTypeImports),
+    ...ifDefined('operationTypeImports', operationTypeImports),
+    ...ifDefined('extensionIds', extensionIds),
+  };
+  targetFamily.validateTypes(ir, ctx);
+
+  targetFamily.validateStructure(ir);
+
+  const canonicalContract = {
+    schemaVersion: ir.schemaVersion,
+    targetFamily: ir.targetFamily,
+    target: ir.target,
+    models: ir.models,
+    relations: ir.relations,
+    storage: ir.storage,
+    ...ifDefined('execution', ir.execution),
+    extensionPacks: ir.extensionPacks,
+    capabilities: ir.capabilities,
+    meta: ir.meta,
+  };
+  assertCanonicalArtifactShape(canonicalContract);
+
+  const storageHash = computeStorageHash(canonicalContract);
+  const executionHash = canonicalContract.execution
+    ? computeExecutionHash(canonicalContract)
+    : undefined;
+  const profileHash = computeProfileHash(canonicalContract);
+
+  const contractWithHashes = {
+    ...canonicalContract,
+    storageHash,
+    ...ifDefined('executionHash', executionHash),
+    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 generateOptions =
+    parameterizedRenderers || parameterizedTypeImports || queryOperationTypeImports
+      ? {
+          ...ifDefined('parameterizedRenderers', parameterizedRenderers),
+          ...ifDefined('parameterizedTypeImports', parameterizedTypeImports),
+          ...ifDefined('queryOperationTypeImports', queryOperationTypeImports),
+        }
+      : undefined;
+
+  const contractTypeHashes = {
+    storageHash,
+    ...ifDefined('executionHash', executionHash),
+    profileHash,
+  };
+  const contractDtsRaw = targetFamily.generateContractTypes(
+    ir,
+    codecTypeImports ?? [],
+    operationTypeImports ?? [],
+    contractTypeHashes,
+    generateOptions,
+  );
+  const contractDts = await format(contractDtsRaw, {
+    parser: 'typescript',
+    singleQuote: true,
+    semi: true,
+    printWidth: 100,
+  });
+
+  return {
+    contractJson: contractJsonString,
+    contractDts,
+    storageHash,
+    ...ifDefined('executionHash', executionHash),
+    profileHash,
+  };
+}

package/src/emission/hashing.ts

@@ -0,0 +1,59 @@
+import { createHash } from 'node:crypto';
+import { ifDefined } from '@prisma-next/utils/defined';
+import type { CanonicalContractInput } from './canonicalization';
+import { canonicalizeContract } from './canonicalization';
+
+function computeHash(content: string): string {
+  const hash = createHash('sha256');
+  hash.update(content);
+  return `sha256:${hash.digest('hex')}`;
+}
+
+export function computeStorageHash(contract: CanonicalContractInput): string {
+  const storageContract = {
+    schemaVersion: contract.schemaVersion,
+    targetFamily: contract.targetFamily,
+    target: contract.target,
+    storage: contract.storage,
+    models: {},
+    relations: {},
+    extensionPacks: {},
+    capabilities: {},
+    meta: {},
+  };
+  const canonical = canonicalizeContract(storageContract);
+  return computeHash(canonical);
+}
+
+export function computeProfileHash(contract: CanonicalContractInput): string {
+  const profileContract = {
+    schemaVersion: contract.schemaVersion,
+    targetFamily: contract.targetFamily,
+    target: contract.target,
+    models: {},
+    relations: {},
+    storage: {},
+    extensionPacks: {},
+    capabilities: contract.capabilities,
+    meta: {},
+  };
+  const canonical = canonicalizeContract(profileContract);
+  return computeHash(canonical);
+}
+
+export function computeExecutionHash(contract: CanonicalContractInput): string {
+  const executionContract = {
+    schemaVersion: contract.schemaVersion,
+    targetFamily: contract.targetFamily,
+    target: contract.target,
+    models: {},
+    relations: {},
+    storage: {},
+    extensionPacks: {},
+    capabilities: {},
+    meta: {},
+    ...ifDefined('execution', contract.execution),
+  };
+  const canonical = canonicalizeContract(executionContract);
+  return computeHash(canonical);
+}

package/src/emission/types.ts

@@ -0,0 +1,33 @@
+import type { TypeRenderEntry, TypesImportSpec } from '@prisma-next/contract/types';
+import type { OperationRegistry } from '@prisma-next/operations';
+
+export interface EmitOptions {
+  readonly outputDir: string;
+  readonly operationRegistry?: OperationRegistry;
+  readonly codecTypeImports?: ReadonlyArray<TypesImportSpec>;
+  readonly operationTypeImports?: ReadonlyArray<TypesImportSpec>;
+  readonly extensionIds?: ReadonlyArray<string>;
+  /**
+   * Normalized parameterized type renderers, keyed by codecId.
+   * These are extracted from descriptors and normalized during assembly.
+   */
+  readonly parameterizedRenderers?: Map<string, TypeRenderEntry>;
+  /**
+   * Type imports for parameterized codecs.
+   * These are added to contract.d.ts alongside codec and operation type imports.
+   */
+  readonly parameterizedTypeImports?: ReadonlyArray<TypesImportSpec>;
+  /**
+   * Query operation type imports for the query builder.
+   * Flat operation signatures keyed by operation name.
+   */
+  readonly queryOperationTypeImports?: ReadonlyArray<TypesImportSpec>;
+}
+
+export interface EmitResult {
+  readonly contractJson: string;
+  readonly contractDts: string;
+  readonly storageHash: string;
+  readonly executionHash?: string;
+  readonly profileHash: string;
+}