@prisma-next/family-sql 0.3.0-pr.99.5 → 0.3.0

package/src/core/migrations/contract-to-schema-ir.ts

@@ -0,0 +1,269 @@
+import type { ColumnDefault, Contract } from '@prisma-next/contract/types';
+import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
+import type { MigrationPlannerConflict } from '@prisma-next/framework-components/control';
+import type {
+  ForeignKey,
+  Index,
+  SqlStorage,
+  StorageColumn,
+  StorageTable,
+  UniqueConstraint,
+} from '@prisma-next/sql-contract/types';
+import { defaultIndexName } from '@prisma-next/sql-schema-ir/naming';
+import type {
+  DependencyIR,
+  SqlAnnotations,
+  SqlColumnIR,
+  SqlForeignKeyIR,
+  SqlIndexIR,
+  SqlSchemaIR,
+  SqlTableIR,
+  SqlUniqueIR,
+} from '@prisma-next/sql-schema-ir/types';
+import { ifDefined } from '@prisma-next/utils/defined';
+import { collectInitDependencies } from './types';
+
+/**
+ * Target-specific callback that expands a column's base `nativeType` and optional
+ * `typeParams` into the fully-qualified type string used by the database
+ * (e.g. `character` + `{ length: 36 }` → `character(36)`).
+ *
+ * This lives in the family layer as a callback rather than importing a concrete
+ * implementation because each target (Postgres, MySQL, SQLite, …) has its own
+ * parameterization syntax. The target wires its expander when calling
+ * `contractToSchemaIR`, keeping the family layer target-agnostic.
+ */
+export type NativeTypeExpander = (input: {
+  readonly nativeType: string;
+  readonly codecId?: string;
+  readonly typeParams?: Record<string, unknown>;
+}) => string;
+
+/**
+ * Target-specific callback that renders a `ColumnDefault` into the raw SQL literal
+ * string stored in `SqlColumnIR.default`.
+ *
+ * Default value serialization is target-specific (quoting, casting, type syntax vary
+ * between Postgres, MySQL, SQLite, …). This callback follows the same IoC pattern as
+ * `NativeTypeExpander`: the target provides its renderer when calling
+ * `contractToSchemaIR`, keeping the family layer target-agnostic.
+ */
+export type DefaultRenderer = (def: ColumnDefault, column: StorageColumn) => string;
+
+function convertColumn(
+  name: string,
+  column: StorageColumn,
+  expandNativeType: NativeTypeExpander | undefined,
+  renderDefault: DefaultRenderer | undefined,
+): SqlColumnIR {
+  const nativeType = expandNativeType
+    ? expandNativeType({
+        nativeType: column.nativeType,
+        codecId: column.codecId,
+        ...ifDefined('typeParams', column.typeParams),
+      })
+    : column.nativeType;
+  return {
+    name,
+    nativeType,
+    nullable: column.nullable,
+    ...ifDefined(
+      'default',
+      column.default != null && renderDefault ? renderDefault(column.default, column) : undefined,
+    ),
+  };
+}
+
+function convertUnique(unique: UniqueConstraint): SqlUniqueIR {
+  return {
+    columns: unique.columns,
+    ...ifDefined('name', unique.name),
+  };
+}
+
+function convertIndex(index: Index): SqlIndexIR {
+  return {
+    columns: index.columns,
+    unique: false,
+    ...ifDefined('name', index.name),
+  };
+}
+
+function convertForeignKey(fk: ForeignKey): SqlForeignKeyIR {
+  return {
+    columns: fk.columns,
+    referencedTable: fk.references.table,
+    referencedColumns: fk.references.columns,
+    ...ifDefined('name', fk.name),
+  };
+}
+
+function convertTable(
+  name: string,
+  table: StorageTable,
+  expandNativeType: NativeTypeExpander | undefined,
+  renderDefault: DefaultRenderer | undefined,
+): SqlTableIR {
+  const columns: Record<string, SqlColumnIR> = {};
+  for (const [colName, colDef] of Object.entries(table.columns)) {
+    columns[colName] = convertColumn(colName, colDef, expandNativeType, renderDefault);
+  }
+
+  const satisfiedIndexColumns = new Set([
+    ...table.indexes.map((idx) => idx.columns.join(',')),
+    ...table.uniques.map((unique) => unique.columns.join(',')),
+    ...(table.primaryKey ? [table.primaryKey.columns.join(',')] : []),
+  ]);
+  const fkBackingIndexes: SqlIndexIR[] = [];
+  for (const fk of table.foreignKeys) {
+    if (fk.index === false) continue;
+    const key = fk.columns.join(',');
+    if (satisfiedIndexColumns.has(key)) continue;
+    fkBackingIndexes.push({
+      columns: fk.columns,
+      unique: false,
+      name: defaultIndexName(name, fk.columns),
+    });
+    satisfiedIndexColumns.add(key);
+  }
+
+  return {
+    name,
+    columns,
+    ...ifDefined('primaryKey', table.primaryKey),
+    foreignKeys: table.foreignKeys.map(convertForeignKey),
+    uniques: table.uniques.map(convertUnique),
+    indexes: [...table.indexes.map(convertIndex), ...fkBackingIndexes],
+  };
+}
+
+/**
+ * Detects destructive changes between two contract storages.
+ *
+ * The additive-only planner silently ignores removals (tables, columns).
+ * This function detects those removals so callers can report them as conflicts
+ * rather than silently producing an empty plan.
+ *
+ * Returns an empty array if no destructive changes are found.
+ */
+export function detectDestructiveChanges(
+  from: SqlStorage | null,
+  to: SqlStorage,
+): readonly MigrationPlannerConflict[] {
+  if (!from) return [];
+
+  const hasOwn = (value: object, key: string): boolean => Object.hasOwn(value, key);
+
+  const conflicts: MigrationPlannerConflict[] = [];
+
+  for (const tableName of Object.keys(from.tables)) {
+    if (!hasOwn(to.tables, tableName)) {
+      conflicts.push({
+        kind: 'tableRemoved',
+        summary: `Table "${tableName}" was removed`,
+      });
+      continue;
+    }
+
+    const toTable = to.tables[tableName] as StorageTable;
+    const fromTable = from.tables[tableName];
+    if (!fromTable) continue;
+
+    for (const columnName of Object.keys(fromTable.columns)) {
+      if (!hasOwn(toTable.columns, columnName)) {
+        conflicts.push({
+          kind: 'columnRemoved',
+          summary: `Column "${tableName}"."${columnName}" was removed`,
+        });
+      }
+    }
+  }
+
+  return conflicts;
+}
+
+export interface ContractToSchemaIROptions {
+  readonly annotationNamespace: string;
+  readonly expandNativeType?: NativeTypeExpander;
+  readonly renderDefault?: DefaultRenderer;
+  readonly frameworkComponents?: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
+}
+
+/**
+ * Converts a `Contract` to `SqlSchemaIR`.
+ *
+ * Reads `contract.storage` for tables, `contract.storage.types` for type
+ * annotations, and derives database dependencies from `frameworkComponents`
+ * (each component's `databaseDependencies.init[].id`).
+ * Storage-type annotations are written under `options.annotationNamespace`.
+ *
+ * Drops codec metadata (`codecId`, `typeRef`) since the schema IR only represents
+ * structural information. When `expandNativeType` is provided, parameterized types
+ * are expanded (e.g. `character` + `{ length: 36 }` → `character(36)`) so the
+ * resulting IR compares correctly against the "to" contract during planning.
+ *
+ * Returns an empty schema IR when `contract` is `null` (new project).
+ */
+export function contractToSchemaIR(
+  contract: Contract<SqlStorage> | null,
+  options: ContractToSchemaIROptions,
+): SqlSchemaIR {
+  if (options.annotationNamespace.length === 0) {
+    throw new Error('annotationNamespace must be a non-empty string');
+  }
+
+  if (!contract) {
+    return { tables: {}, dependencies: [] };
+  }
+
+  const storage = contract.storage;
+  const tables: Record<string, SqlTableIR> = {};
+  for (const [tableName, tableDef] of Object.entries(storage.tables)) {
+    tables[tableName] = convertTable(
+      tableName,
+      tableDef,
+      options.expandNativeType,
+      options.renderDefault,
+    );
+  }
+
+  const dependencies = deduplicateDependencyIRs(
+    collectInitDependencies(options.frameworkComponents ?? []),
+  );
+  const annotations = deriveAnnotations(storage, options.annotationNamespace);
+
+  return {
+    tables,
+    dependencies,
+    ...ifDefined('annotations', annotations),
+  };
+}
+
+function deduplicateDependencyIRs(
+  deps: readonly { readonly id: string }[],
+): readonly DependencyIR[] {
+  const seen = new Set<string>();
+  const result: DependencyIR[] = [];
+  for (const dep of deps) {
+    if (dep.id.trim().length === 0) {
+      throw new Error('Dependency id must be a non-empty string');
+    }
+    if (seen.has(dep.id)) continue;
+    seen.add(dep.id);
+    result.push({ id: dep.id });
+  }
+  return result;
+}
+
+function deriveAnnotations(
+  storage: SqlStorage,
+  annotationNamespace: string,
+): SqlAnnotations | undefined {
+  if (!storage.types || Object.keys(storage.types).length === 0) return undefined;
+  // Re-key by nativeType to match the structure produced by introspection
+  const byNativeType: Record<string, (typeof storage.types)[string]> = {};
+  for (const typeInstance of Object.values(storage.types)) {
+    byNativeType[typeInstance.nativeType] = typeInstance;
+  }
+  return { [annotationNamespace]: { storageTypes: byNativeType } };
+}

package/src/core/migrations/descriptor-schemas.ts

@@ -0,0 +1,172 @@
+/**
+ * Arktype schemas for SQL migration operation descriptors.
+ *
+ * These schemas are the source of truth for descriptor shapes.
+ * TypeScript types are derived via `typeof schema.infer`.
+ */
+
+import { type } from 'arktype';
+
+// ============================================================================
+// Table descriptors
+// ============================================================================
+
+export const CreateTableSchema = type({ kind: "'createTable'", table: 'string' });
+export const DropTableSchema = type({ kind: "'dropTable'", table: 'string' });
+
+// ============================================================================
+// Column descriptors
+// ============================================================================
+
+export const AddColumnSchema = type({
+  kind: "'addColumn'",
+  table: 'string',
+  column: 'string',
+  'overrides?': { 'nullable?': 'boolean' },
+});
+
+export const DropColumnSchema = type({ kind: "'dropColumn'", table: 'string', column: 'string' });
+
+export const AlterColumnTypeSchema = type({
+  kind: "'alterColumnType'",
+  table: 'string',
+  column: 'string',
+  'using?': 'string',
+  'toType?': 'string',
+});
+
+export const SetNotNullSchema = type({ kind: "'setNotNull'", table: 'string', column: 'string' });
+export const DropNotNullSchema = type({ kind: "'dropNotNull'", table: 'string', column: 'string' });
+export const SetDefaultSchema = type({ kind: "'setDefault'", table: 'string', column: 'string' });
+export const DropDefaultSchema = type({ kind: "'dropDefault'", table: 'string', column: 'string' });
+
+// ============================================================================
+// Constraint descriptors
+// ============================================================================
+
+export const AddPrimaryKeySchema = type({ kind: "'addPrimaryKey'", table: 'string' });
+export const AddUniqueSchema = type({ kind: "'addUnique'", table: 'string', columns: 'string[]' });
+export const AddForeignKeySchema = type({
+  kind: "'addForeignKey'",
+  table: 'string',
+  columns: 'string[]',
+});
+export const DropConstraintSchema = type({
+  kind: "'dropConstraint'",
+  table: 'string',
+  constraintName: 'string',
+});
+
+// ============================================================================
+// Index descriptors
+// ============================================================================
+
+export const CreateIndexSchema = type({
+  kind: "'createIndex'",
+  table: 'string',
+  columns: 'string[]',
+});
+export const DropIndexSchema = type({
+  kind: "'dropIndex'",
+  table: 'string',
+  indexName: 'string',
+});
+
+// ============================================================================
+// Type descriptors
+// ============================================================================
+
+export const CreateEnumTypeSchema = type({
+  kind: "'createEnumType'",
+  typeName: 'string',
+  'values?': 'string[]',
+});
+export const AddEnumValuesSchema = type({
+  kind: "'addEnumValues'",
+  typeName: 'string',
+  values: 'string[]',
+});
+export const DropEnumTypeSchema = type({ kind: "'dropEnumType'", typeName: 'string' });
+export const RenameTypeSchema = type({
+  kind: "'renameType'",
+  fromName: 'string',
+  toName: 'string',
+});
+
+// ============================================================================
+// Dependency descriptors
+// ============================================================================
+
+export const CreateDependencySchema = type({
+  kind: "'createDependency'",
+  dependencyId: 'string',
+});
+
+// ============================================================================
+// Data transform descriptor
+// ============================================================================
+
+export const DataTransformSchema = type({
+  kind: "'dataTransform'",
+  name: 'string',
+  source: 'string',
+  check: 'boolean | Function | symbol | object',
+  run: '(Function | symbol | object)[]',
+});
+
+// ============================================================================
+// Union schema
+// ============================================================================
+
+export const SqlMigrationOpDescriptorSchema = type.or(
+  CreateTableSchema,
+  DropTableSchema,
+  AddColumnSchema,
+  DropColumnSchema,
+  AlterColumnTypeSchema,
+  SetNotNullSchema,
+  DropNotNullSchema,
+  SetDefaultSchema,
+  DropDefaultSchema,
+  AddPrimaryKeySchema,
+  AddUniqueSchema,
+  AddForeignKeySchema,
+  DropConstraintSchema,
+  CreateIndexSchema,
+  DropIndexSchema,
+  CreateEnumTypeSchema,
+  AddEnumValuesSchema,
+  DropEnumTypeSchema,
+  RenameTypeSchema,
+  CreateDependencySchema,
+  DataTransformSchema,
+);
+
+export const MigrationDescriptorArraySchema = SqlMigrationOpDescriptorSchema.array();
+
+// ============================================================================
+// Derived types
+// ============================================================================
+
+export type CreateTableDescriptor = typeof CreateTableSchema.infer;
+export type DropTableDescriptor = typeof DropTableSchema.infer;
+export type AddColumnDescriptor = typeof AddColumnSchema.infer;
+export type DropColumnDescriptor = typeof DropColumnSchema.infer;
+export type AlterColumnTypeDescriptor = typeof AlterColumnTypeSchema.infer;
+export type SetNotNullDescriptor = typeof SetNotNullSchema.infer;
+export type DropNotNullDescriptor = typeof DropNotNullSchema.infer;
+export type SetDefaultDescriptor = typeof SetDefaultSchema.infer;
+export type DropDefaultDescriptor = typeof DropDefaultSchema.infer;
+export type AddPrimaryKeyDescriptor = typeof AddPrimaryKeySchema.infer;
+export type AddUniqueDescriptor = typeof AddUniqueSchema.infer;
+export type AddForeignKeyDescriptor = typeof AddForeignKeySchema.infer;
+export type DropConstraintDescriptor = typeof DropConstraintSchema.infer;
+export type CreateIndexDescriptor = typeof CreateIndexSchema.infer;
+export type DropIndexDescriptor = typeof DropIndexSchema.infer;
+export type CreateEnumTypeDescriptor = typeof CreateEnumTypeSchema.infer;
+export type AddEnumValuesDescriptor = typeof AddEnumValuesSchema.infer;
+export type DropEnumTypeDescriptor = typeof DropEnumTypeSchema.infer;
+export type RenameTypeDescriptor = typeof RenameTypeSchema.infer;
+export type CreateDependencyDescriptor = typeof CreateDependencySchema.infer;
+export type DataTransformDescriptor = typeof DataTransformSchema.infer;
+export type SqlMigrationOpDescriptor = typeof SqlMigrationOpDescriptorSchema.infer;

package/src/core/migrations/operation-descriptors.ts

@@ -0,0 +1,213 @@
+/**
+ * SQL migration operation descriptors — builder functions and re-exports.
+ *
+ * Types are defined by arktype schemas in descriptor-schemas.ts and derived
+ * via `typeof schema.infer`. This file provides the builder functions that
+ * construct descriptors, plus re-exports the types and schemas.
+ */
+
+import type { SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';
+import { ifDefined } from '@prisma-next/utils/defined';
+
+// Re-export types and schemas from the schema source of truth
+export type {
+  AddColumnDescriptor,
+  AddEnumValuesDescriptor,
+  AddForeignKeyDescriptor,
+  AddPrimaryKeyDescriptor,
+  AddUniqueDescriptor,
+  AlterColumnTypeDescriptor,
+  CreateDependencyDescriptor,
+  CreateEnumTypeDescriptor,
+  CreateIndexDescriptor,
+  CreateTableDescriptor,
+  DataTransformDescriptor,
+  DropColumnDescriptor,
+  DropConstraintDescriptor,
+  DropDefaultDescriptor,
+  DropEnumTypeDescriptor,
+  DropIndexDescriptor,
+  DropNotNullDescriptor,
+  DropTableDescriptor,
+  RenameTypeDescriptor,
+  SetDefaultDescriptor,
+  SetNotNullDescriptor,
+  SqlMigrationOpDescriptor,
+} from './descriptor-schemas';
+
+export { MigrationDescriptorArraySchema } from './descriptor-schemas';
+
+import type {
+  AddColumnDescriptor,
+  AddEnumValuesDescriptor,
+  AddForeignKeyDescriptor,
+  AddPrimaryKeyDescriptor,
+  AddUniqueDescriptor,
+  AlterColumnTypeDescriptor,
+  CreateDependencyDescriptor,
+  CreateEnumTypeDescriptor,
+  CreateIndexDescriptor,
+  CreateTableDescriptor,
+  DropColumnDescriptor,
+  DropConstraintDescriptor,
+  DropDefaultDescriptor,
+  DropEnumTypeDescriptor,
+  DropIndexDescriptor,
+  DropNotNullDescriptor,
+  DropTableDescriptor,
+  RenameTypeDescriptor,
+  SetDefaultDescriptor,
+  SetNotNullDescriptor,
+} from './descriptor-schemas';
+
+// ============================================================================
+// Data transform support types (not validated by arktype — runtime values)
+// ============================================================================
+
+/** Something that can produce a SqlQueryPlan via .build(). */
+export interface Buildable {
+  build(): SqlQueryPlan;
+}
+
+/**
+ * Sentinel value for unimplemented data transform queries.
+ * The scaffold renders this as a TODO comment. The resolver throws if it encounters one.
+ */
+export const TODO = Symbol.for('prisma-next.migration.todo');
+export type TodoMarker = typeof TODO;
+
+// ============================================================================
+// Builder functions
+// ============================================================================
+
+export function createTable(table: string): CreateTableDescriptor {
+  return { kind: 'createTable', table };
+}
+
+export function dropTable(table: string): DropTableDescriptor {
+  return { kind: 'dropTable', table };
+}
+
+export function addColumn(
+  table: string,
+  column: string,
+  overrides?: { nullable?: boolean },
+): AddColumnDescriptor {
+  return { kind: 'addColumn', table, column, ...ifDefined('overrides', overrides) };
+}
+
+export function dropColumn(table: string, column: string): DropColumnDescriptor {
+  return { kind: 'dropColumn', table, column };
+}
+
+export function alterColumnType(
+  table: string,
+  column: string,
+  opts?: string | { using?: string; toType?: string },
+): AlterColumnTypeDescriptor {
+  const using = typeof opts === 'string' ? opts : opts?.using;
+  const toType = typeof opts === 'string' ? undefined : opts?.toType;
+  return {
+    kind: 'alterColumnType',
+    table,
+    column,
+    ...ifDefined('using', using),
+    ...ifDefined('toType', toType),
+  };
+}
+
+export function setNotNull(table: string, column: string): SetNotNullDescriptor {
+  return { kind: 'setNotNull', table, column };
+}
+
+export function dropNotNull(table: string, column: string): DropNotNullDescriptor {
+  return { kind: 'dropNotNull', table, column };
+}
+
+export function setDefault(table: string, column: string): SetDefaultDescriptor {
+  return { kind: 'setDefault', table, column };
+}
+
+export function dropDefault(table: string, column: string): DropDefaultDescriptor {
+  return { kind: 'dropDefault', table, column };
+}
+
+export function addPrimaryKey(table: string): AddPrimaryKeyDescriptor {
+  return { kind: 'addPrimaryKey', table };
+}
+
+export function addUnique(table: string, columns: readonly string[]): AddUniqueDescriptor {
+  return { kind: 'addUnique', table, columns: [...columns] };
+}
+
+export function addForeignKey(table: string, columns: readonly string[]): AddForeignKeyDescriptor {
+  return { kind: 'addForeignKey', table, columns: [...columns] };
+}
+
+export function dropConstraint(table: string, constraintName: string): DropConstraintDescriptor {
+  return { kind: 'dropConstraint', table, constraintName };
+}
+
+export function createIndex(table: string, columns: readonly string[]): CreateIndexDescriptor {
+  return { kind: 'createIndex', table, columns: [...columns] };
+}
+
+export function dropIndex(table: string, indexName: string): DropIndexDescriptor {
+  return { kind: 'dropIndex', table, indexName };
+}
+
+export function createEnumType(
+  typeName: string,
+  values?: readonly string[],
+): CreateEnumTypeDescriptor {
+  return {
+    kind: 'createEnumType',
+    typeName,
+    ...ifDefined('values', values ? [...values] : undefined),
+  };
+}
+
+export function addEnumValues(
+  typeName: string,
+  values: readonly string[],
+): AddEnumValuesDescriptor {
+  return { kind: 'addEnumValues', typeName, values: [...values] };
+}
+
+export function dropEnumType(typeName: string): DropEnumTypeDescriptor {
+  return { kind: 'dropEnumType', typeName };
+}
+
+export function renameType(fromName: string, toName: string): RenameTypeDescriptor {
+  return { kind: 'renameType', fromName, toName };
+}
+
+export function createDependency(dependencyId: string): CreateDependencyDescriptor {
+  return { kind: 'createDependency', dependencyId };
+}
+
+/**
+ * All structural builder functions keyed by descriptor kind.
+ */
+export const builders = {
+  createTable,
+  dropTable,
+  addColumn,
+  dropColumn,
+  alterColumnType,
+  setNotNull,
+  dropNotNull,
+  setDefault,
+  dropDefault,
+  addPrimaryKey,
+  addUnique,
+  addForeignKey,
+  dropConstraint,
+  createIndex,
+  dropIndex,
+  createEnumType,
+  addEnumValues,
+  dropEnumType,
+  renameType,
+  createDependency,
+} as const;

package/src/core/migrations/policies.ts

@@ -1,4 +1,4 @@
-import type { MigrationOperationPolicy } from '@prisma-next/core-control-plane/types';
+import type { MigrationOperationPolicy } from '@prisma-next/framework-components/control';
 
 /**
  * Policy used by `db init`: additive-only operations, no widening/destructive steps.