@prisma-next/target-sqlite 0.5.0-dev.8 → 0.5.0-dev.81

package/src/core/migrations/planner-strategies.ts

@@ -0,0 +1,231 @@
+/**
+ * SQLite migration strategies.
+ *
+ * Each strategy examines the issue list, consumes issues it handles, and
+ * returns the `SqliteOpFactoryCall[]` to address them. The issue planner
+ * runs each strategy in order and routes whatever's left through
+ * `mapIssueToCall`.
+ *
+ * SQLite has no enums, no data-safe backfill, and no component-declared
+ * database dependencies. The only recipe that needs strategy-level
+ * multi-issue consumption is `recreateTable` (added in a later phase), which
+ * absorbs type/nullability/default/constraint mismatches for a given table
+ * into a single recreate operation.
+ */
+
+import type { Contract } from '@prisma-next/contract/types';
+import type {
+  CodecControlHooks,
+  MigrationOperationClass,
+  MigrationOperationPolicy,
+} from '@prisma-next/family-sql/control';
+import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
+import type { SchemaIssue } from '@prisma-next/framework-components/control';
+import type { SqlStorage, StorageTypeInstance } from '@prisma-next/sql-contract/types';
+import { defaultIndexName } from '@prisma-next/sql-schema-ir/naming';
+import type { SqlSchemaIR } from '@prisma-next/sql-schema-ir/types';
+import { toTableSpec } from './issue-planner';
+import { DataTransformCall, RecreateTableCall, type SqliteOpFactoryCall } from './op-factory-call';
+import type { SqliteIndexSpec } from './operations/shared';
+import { buildRecreatePostchecks, buildRecreateSummary } from './operations/tables';
+
+export interface StrategyContext {
+  readonly toContract: Contract<SqlStorage>;
+  readonly fromContract: Contract<SqlStorage> | null;
+  readonly codecHooks: ReadonlyMap<string, CodecControlHooks>;
+  readonly storageTypes: Readonly<Record<string, StorageTypeInstance>>;
+  readonly schema: SqlSchemaIR;
+  readonly policy: MigrationOperationPolicy;
+  readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
+}
+
+export type CallMigrationStrategy = (
+  issues: readonly SchemaIssue[],
+  context: StrategyContext,
+) =>
+  | {
+      kind: 'match';
+      issues: readonly SchemaIssue[];
+      calls: readonly SqliteOpFactoryCall[];
+      recipe?: boolean;
+    }
+  | { kind: 'no_match' };
+
+// ============================================================================
+// Recreate-table strategy
+// ============================================================================
+
+const WIDENING_ISSUE_KINDS = new Set<SchemaIssue['kind']>(['default_mismatch', 'default_missing']);
+
+const DESTRUCTIVE_ISSUE_KINDS = new Set<SchemaIssue['kind']>([
+  'extra_default',
+  'type_mismatch',
+  'primary_key_mismatch',
+  'foreign_key_mismatch',
+  'unique_constraint_mismatch',
+  'extra_foreign_key',
+  'extra_unique_constraint',
+  'extra_primary_key',
+]);
+
+function classifyIssue(issue: SchemaIssue): 'widening' | 'destructive' | null {
+  if (issue.kind === 'enum_values_changed') return null;
+  if (!issue.table) return null;
+  if (issue.kind === 'nullability_mismatch') {
+    // Relaxing (NOT NULL → nullable) is widening; tightening is destructive.
+    return issue.expected === 'true' ? 'widening' : 'destructive';
+  }
+  if (WIDENING_ISSUE_KINDS.has(issue.kind)) return 'widening';
+  if (DESTRUCTIVE_ISSUE_KINDS.has(issue.kind)) return 'destructive';
+  return null;
+}
+
+/**
+ * Groups recreate-eligible issues by table, decides per-table operation class
+ * (destructive wins over widening), and emits one `RecreateTableCall` per
+ * table. Returns unchanged-or-smaller issue list — issues the strategy
+ * consumed are removed so `mapIssueToCall` doesn't double-handle them.
+ */
+export const recreateTableStrategy: CallMigrationStrategy = (issues, ctx) => {
+  const byTable = new Map<string, { issues: SchemaIssue[]; hasDestructive: boolean }>();
+  const consumed = new Set<SchemaIssue>();
+
+  for (const issue of issues) {
+    const cls = classifyIssue(issue);
+    if (!cls) continue;
+    if (issue.kind === 'enum_values_changed') continue;
+    if (!issue.table) continue;
+    const table = issue.table;
+    const entry = byTable.get(table);
+    if (entry) {
+      entry.issues.push(issue);
+      if (cls === 'destructive') entry.hasDestructive = true;
+    } else {
+      byTable.set(table, { issues: [issue], hasDestructive: cls === 'destructive' });
+    }
+    consumed.add(issue);
+  }
+
+  if (byTable.size === 0) return { kind: 'no_match' };
+
+  const calls: SqliteOpFactoryCall[] = [];
+  for (const [tableName, entry] of byTable) {
+    const contractTable = ctx.toContract.storage.tables[tableName];
+    const schemaTable = ctx.schema.tables[tableName];
+    if (!contractTable || !schemaTable) continue;
+    const operationClass: MigrationOperationClass = entry.hasDestructive
+      ? 'destructive'
+      : 'widening';
+
+    // Flatten the contract table to a self-contained spec — the Call holds
+    // pre-rendered SQL fragments only, no `StorageColumn` or `storageTypes`.
+    const tableSpec = toTableSpec(contractTable, ctx.storageTypes);
+
+    const seenIndexColumnKeys = new Set<string>();
+    const indexes: SqliteIndexSpec[] = [];
+    for (const idx of contractTable.indexes) {
+      const key = idx.columns.join(',');
+      if (seenIndexColumnKeys.has(key)) continue;
+      seenIndexColumnKeys.add(key);
+      indexes.push({
+        name: idx.name ?? defaultIndexName(tableName, idx.columns),
+        columns: idx.columns,
+      });
+    }
+    for (const fk of contractTable.foreignKeys) {
+      if (fk.index === false) continue;
+      const key = fk.columns.join(',');
+      if (seenIndexColumnKeys.has(key)) continue;
+      seenIndexColumnKeys.add(key);
+      indexes.push({
+        name: defaultIndexName(tableName, fk.columns),
+        columns: fk.columns,
+      });
+    }
+
+    calls.push(
+      new RecreateTableCall({
+        tableName,
+        contractTable: tableSpec,
+        schemaColumnNames: Object.keys(schemaTable.columns),
+        indexes,
+        summary: buildRecreateSummary(tableName, entry.issues),
+        postchecks: buildRecreatePostchecks(tableName, entry.issues, tableSpec),
+        operationClass,
+      }),
+    );
+  }
+
+  return {
+    kind: 'match',
+    issues: issues.filter((i) => !consumed.has(i)),
+    calls,
+    recipe: true,
+  };
+};
+
+// ============================================================================
+// Nullability-tightening backfill strategy
+// ============================================================================
+
+/**
+ * When the policy allows `'data'` and the contract tightens one or more
+ * columns from nullable to NOT NULL, emit a `DataTransformCall` stub per
+ * tightened column. The user fills the backfill `UPDATE` in the rendered
+ * `migration.ts` before the subsequent `RecreateTableCall` copies data into
+ * the tightened schema (whose `INSERT INTO temp SELECT … FROM old` would
+ * otherwise fail at runtime if any `NULL`s remain).
+ *
+ * Does NOT consume the tightening issue — `recreateTableStrategy` still
+ * needs it to produce the actual recreate that enforces the NOT NULL at
+ * the schema level. The backfill op and the recreate op end up in the
+ * recipe slot in strategy order (backfill first, recreate second), which
+ * matches the required execution order.
+ *
+ * Mirrors Postgres's `nullableTighteningCallStrategy` / `'data'`-class
+ * gating. When `'data'` is not in the policy (the default `db update` /
+ * `db init` path), the strategy short-circuits and the recreate alone
+ * runs with its current destructive-class gating — preserving today's
+ * behavior where a tightening blows up at runtime if NULLs are present.
+ */
+export const nullabilityTighteningBackfillStrategy: CallMigrationStrategy = (issues, ctx) => {
+  if (!ctx.policy.allowedOperationClasses.includes('data')) {
+    return { kind: 'no_match' };
+  }
+
+  const calls: SqliteOpFactoryCall[] = [];
+  for (const issue of issues) {
+    if (issue.kind !== 'nullability_mismatch') continue;
+    if (!issue.table || !issue.column) continue;
+    // Tightening only: `expected === 'true'` means the contract wants the
+    // column nullable (relaxing from NOT NULL → nullable), which is safe and
+    // needs no backfill.
+    if (issue.expected === 'true') continue;
+
+    const column = ctx.toContract.storage.tables[issue.table]?.columns[issue.column];
+    if (!column || column.nullable === true) continue;
+
+    calls.push(
+      new DataTransformCall(
+        `data_migration.backfill-${issue.table}-${issue.column}`,
+        `Backfill NULLs in "${issue.table}"."${issue.column}" before NOT NULL tightening`,
+        issue.table,
+        issue.column,
+      ),
+    );
+  }
+
+  if (calls.length === 0) return { kind: 'no_match' };
+
+  return {
+    kind: 'match',
+    issues,
+    calls,
+    recipe: true,
+  };
+};
+
+export const sqlitePlannerStrategies: readonly CallMigrationStrategy[] = [
+  nullabilityTighteningBackfillStrategy,
+  recreateTableStrategy,
+];

package/src/core/migrations/planner-target-details.ts

@@ -0,0 +1,33 @@
+import { ifDefined } from '@prisma-next/utils/defined';
+
+export type OperationClass = 'table' | 'column' | 'primaryKey' | 'unique' | 'index' | 'foreignKey';
+
+// SQLite's default (and only) schema name; keeps `SqlitePlanTargetDetails`
+// conformant with `SqlPlanTargetDetails`, which mandates a `schema` field.
+const DEFAULT_SCHEMA = 'main';
+
+export interface SqlitePlanTargetDetails {
+  readonly schema: string;
+  readonly objectType: OperationClass;
+  readonly name: string;
+  readonly table?: string;
+}
+
+export interface PlanningMode {
+  readonly includeExtraObjects: boolean;
+  readonly allowWidening: boolean;
+  readonly allowDestructive: boolean;
+}
+
+export function buildTargetDetails(
+  objectType: OperationClass,
+  name: string,
+  table?: string,
+): SqlitePlanTargetDetails {
+  return {
+    schema: DEFAULT_SCHEMA,
+    objectType,
+    name,
+    ...ifDefined('table', table),
+  };
+}

package/src/core/migrations/planner.ts

@@ -0,0 +1,183 @@
+import type { Contract } from '@prisma-next/contract/types';
+import type {
+  MigrationOperationPolicy,
+  SqlMigrationPlanner,
+  SqlMigrationPlannerPlanOptions,
+  SqlPlannerFailureResult,
+} from '@prisma-next/family-sql/control';
+import {
+  extractCodecControlHooks,
+  planFieldEventOperations,
+  plannerFailure,
+} from '@prisma-next/family-sql/control';
+import { verifySqlSchema } from '@prisma-next/family-sql/schema-verify';
+import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
+import type {
+  MigrationPlanner,
+  MigrationScaffoldContext,
+  SchemaIssue,
+} from '@prisma-next/framework-components/control';
+import { parseSqliteDefault } from '../default-normalizer';
+import { normalizeSqliteNativeType } from '../native-type-normalizer';
+import { planIssues } from './issue-planner';
+import {
+  type SqliteMigrationDestinationInfo,
+  TypeScriptRenderableSqliteMigration,
+} from './planner-produced-sqlite-migration';
+import { sqlitePlannerStrategies } from './planner-strategies';
+import type { SqlitePlanTargetDetails } from './planner-target-details';
+
+export function createSqliteMigrationPlanner(): SqliteMigrationPlanner {
+  return new SqliteMigrationPlanner();
+}
+
+export type SqlitePlanResult =
+  | { readonly kind: 'success'; readonly plan: TypeScriptRenderableSqliteMigration }
+  | SqlPlannerFailureResult;
+
+/**
+ * SQLite migration planner — a thin wrapper over `planIssues`.
+ *
+ * `plan()` verifies the live schema against the target contract (producing
+ * `SchemaIssue[]`) and delegates to `planIssues` with the registered
+ * strategies. Strategies absorb groups of related issues into composite
+ * recipes (e.g. recreating a table to apply type/nullability/default/
+ * constraint changes at once); anything not absorbed by a strategy flows
+ * through `mapIssueToCall` in the issue planner as a one-off call.
+ *
+ * FK-backing indexes are surfaced by `verifySqlSchema`'s index expansion
+ * (see `verify-sql-schema.ts:459-469`), so `mapIssueToCall` handles them
+ * uniformly alongside user-declared indexes.
+ */
+export class SqliteMigrationPlanner
+  implements SqlMigrationPlanner<SqlitePlanTargetDetails>, MigrationPlanner<'sql', 'sqlite'>
+{
+  plan(options: {
+    readonly contract: unknown;
+    readonly schema: unknown;
+    readonly policy: MigrationOperationPolicy;
+    /**
+     * The "from" contract (state the planner assumes the database starts at),
+     * or `null` for reconciliation flows.
+     *
+     * Typed as the framework `Contract | null` to satisfy the
+     * `MigrationPlanner` interface contract; `planSql` narrows to the SQL
+     * shape via `SqlMigrationPlannerPlanOptions`. Used to populate
+     * `describe().from` on the produced plan as
+     * `fromContract?.storage.storageHash ?? null`.
+     */
+    readonly fromContract: Contract | null;
+    readonly frameworkComponents: ReadonlyArray<TargetBoundComponentDescriptor<'sql', string>>;
+    /**
+     * Contract space this plan applies to. Stamped onto the produced
+     * {@link TypeScriptRenderableSqliteMigration.spaceId} so the runner keys
+     * the marker row by the right space.
+     */
+    readonly spaceId: string;
+  }): SqlitePlanResult {
+    return this.planSql(options as SqlMigrationPlannerPlanOptions);
+  }
+
+  emptyMigration(
+    context: MigrationScaffoldContext,
+    spaceId: string,
+  ): TypeScriptRenderableSqliteMigration {
+    return new TypeScriptRenderableSqliteMigration(
+      [],
+      {
+        from: context.fromHash,
+        to: context.toHash,
+      },
+      spaceId,
+    );
+  }
+
+  private planSql(options: SqlMigrationPlannerPlanOptions): SqlitePlanResult {
+    const policyResult = this.ensureAdditivePolicy(options.policy);
+    if (policyResult) return policyResult;
+
+    const schemaIssues = this.collectSchemaIssues(options);
+    const codecHooks = extractCodecControlHooks(options.frameworkComponents);
+    const storageTypes = options.contract.storage.types ?? {};
+
+    const result = planIssues({
+      issues: schemaIssues,
+      toContract: options.contract,
+      fromContract: options.fromContract,
+      codecHooks,
+      storageTypes,
+      schema: options.schema,
+      policy: options.policy,
+      frameworkComponents: options.frameworkComponents,
+      strategies: sqlitePlannerStrategies,
+    });
+
+    if (!result.ok) {
+      return plannerFailure(result.failure);
+    }
+
+    // Codec lifecycle hook (T2.2): inline `onFieldEvent`-emitted ops after
+    // structural DDL. Sub-spec § 5 fixes the ordering as
+    // `structural → added → dropped → altered`, with within-group sorting by
+    // `(tableName, fieldName)` deterministic for byte-stable re-emits.
+    // Hook fires only at the application emitter — extension-space planning
+    // (M2 R2) never reaches this helper.
+    const fieldEventOps = planFieldEventOperations({
+      priorContract: options.fromContract,
+      newContract: options.contract,
+      codecHooks,
+    });
+    // Codec-emitted calls already conform to `OpFactoryCall` — render +
+    // toOp + importRequirements ride directly through the same emit path
+    // as structural ops, no `RawSqlCall` wrap.
+    const calls = [...result.value.calls, ...fieldEventOps];
+
+    const destination: SqliteMigrationDestinationInfo = {
+      storageHash: options.contract.storage.storageHash,
+      ...(options.contract.profileHash !== undefined
+        ? { profileHash: options.contract.profileHash }
+        : {}),
+    };
+
+    return {
+      kind: 'success' as const,
+      plan: new TypeScriptRenderableSqliteMigration(
+        calls,
+        {
+          from: options.fromContract?.storage.storageHash ?? null,
+          to: options.contract.storage.storageHash,
+        },
+        options.spaceId,
+        destination,
+      ),
+    };
+  }
+
+  private ensureAdditivePolicy(policy: MigrationOperationPolicy): SqlPlannerFailureResult | null {
+    if (!policy.allowedOperationClasses.includes('additive')) {
+      return plannerFailure([
+        {
+          kind: 'unsupportedOperation',
+          summary: 'Migration planner requires additive operations be allowed',
+          why: 'The planner requires the "additive" operation class to be allowed in the policy.',
+        },
+      ]);
+    }
+    return null;
+  }
+
+  private collectSchemaIssues(options: SqlMigrationPlannerPlanOptions): readonly SchemaIssue[] {
+    const allowed = options.policy.allowedOperationClasses;
+    const strict = allowed.includes('widening') || allowed.includes('destructive');
+    const verifyResult = verifySqlSchema({
+      contract: options.contract,
+      schema: options.schema,
+      strict,
+      typeMetadataRegistry: new Map(),
+      frameworkComponents: options.frameworkComponents,
+      normalizeDefault: parseSqliteDefault,
+      normalizeNativeType: normalizeSqliteNativeType,
+    });
+    return verifyResult.schema.issues;
+  }
+}

package/src/core/migrations/render-ops.ts

@@ -0,0 +1,15 @@
+import type { SqlMigrationPlanOperation } from '@prisma-next/family-sql/control';
+import type { OpFactoryCall } from '@prisma-next/framework-components/control';
+import type { SqlitePlanTargetDetails } from './planner-target-details';
+
+type Op = SqlMigrationPlanOperation<SqlitePlanTargetDetails>;
+
+export function renderOps(calls: readonly OpFactoryCall[]): Op[] {
+  // Each call's `toOp()` is typed as the framework `MigrationPlanOperation`;
+  // every concrete Call class on the sqlite planner path produces an op
+  // whose `target.details` is `SqlitePlanTargetDetails`-shaped (or whose
+  // `target.details` is absent, which is structurally compatible). The
+  // narrowing cast happens at this single integration boundary instead of
+  // poisoning every caller's type.
+  return calls.map((c) => c.toOp() as Op);
+}

package/src/core/migrations/render-typescript.ts

@@ -0,0 +1,91 @@
+/**
+ * Polymorphic TypeScript emitter for the SQLite migration IR. Mirrors the
+ * Postgres `render-typescript.ts` — different base-class + factory module
+ * specifier, same overall shape.
+ */
+
+import type { OpFactoryCall } from '@prisma-next/framework-components/control';
+import { detectScaffoldRuntime, shebangLineFor } from '@prisma-next/migration-tools/migration-ts';
+import { type ImportRequirement, jsonToTsSource, renderImports } from '@prisma-next/ts-render';
+
+export interface RenderMigrationMeta {
+  readonly from: string | null;
+  readonly to: string;
+  readonly labels?: readonly string[];
+}
+
+/**
+ * Always-present base imports for the rendered scaffold. Both come from
+ * `@prisma-next/target-sqlite/migration` so an authored SQLite
+ * `migration.ts` only needs a single dependency for its base class and
+ * its CLI entrypoint. Mirrors Postgres's `BASE_IMPORTS`.
+ *
+ * - `Migration` — the target-owned re-export fixes the `SqlMigration`
+ *   generic to `SqlitePlanTargetDetails` and the abstract `targetId` to
+ *   `'sqlite'`.
+ * - `MigrationCLI` — the migration-file CLI entrypoint, re-exported from
+ *   `@prisma-next/cli/migration-cli`. Loads `prisma-next.config.ts`,
+ *   assembles a `ControlStack`, and instantiates the migration class.
+ */
+const BASE_IMPORTS: readonly ImportRequirement[] = [
+  { moduleSpecifier: '@prisma-next/target-sqlite/migration', symbol: 'Migration' },
+  { moduleSpecifier: '@prisma-next/target-sqlite/migration', symbol: 'MigrationCLI' },
+];
+
+export function renderCallsToTypeScript(
+  calls: ReadonlyArray<OpFactoryCall>,
+  meta: RenderMigrationMeta,
+): string {
+  const imports = buildImports(calls);
+  const operationsBody = calls.map((c) => c.renderTypeScript()).join(',\n');
+
+  return [
+    shebangLineFor(detectScaffoldRuntime()),
+    imports,
+    '',
+    'export default class M extends Migration {',
+    buildDescribeMethod(meta),
+    '  override get operations() {',
+    '    return [',
+    indent(operationsBody, 6),
+    '    ];',
+    '  }',
+    '}',
+    '',
+    'MigrationCLI.run(import.meta.url, M);',
+    '',
+  ].join('\n');
+}
+
+function buildImports(calls: ReadonlyArray<OpFactoryCall>): string {
+  const requirements: ImportRequirement[] = [...BASE_IMPORTS];
+  for (const call of calls) {
+    for (const req of call.importRequirements()) {
+      requirements.push(req);
+    }
+  }
+  return renderImports(requirements);
+}
+
+function buildDescribeMethod(meta: RenderMigrationMeta): string {
+  const lines: string[] = [];
+  lines.push('  override describe() {');
+  lines.push('    return {');
+  lines.push(`      from: ${JSON.stringify(meta.from)},`);
+  lines.push(`      to: ${JSON.stringify(meta.to)},`);
+  if (meta.labels && meta.labels.length > 0) {
+    lines.push(`      labels: ${jsonToTsSource(meta.labels)},`);
+  }
+  lines.push('    };');
+  lines.push('  }');
+  lines.push('');
+  return lines.join('\n');
+}
+
+function indent(text: string, spaces: number): string {
+  const pad = ' '.repeat(spaces);
+  return text
+    .split('\n')
+    .map((line) => (line.trim() ? `${pad}${line}` : line))
+    .join('\n');
+}