@prisma-next/migration-tools 0.4.1 → 0.4.3

package/src/io.ts

@@ -7,9 +7,15 @@ import {
   errorInvalidJson,
   errorInvalidManifest,
   errorInvalidSlug,
+  errorMigrationHashMismatch,
   errorMissingFile,
+  errorProvidedInvariantsMismatch,
 } from './errors';
-import type { MigrationBundle, MigrationManifest, MigrationOps } from './types';
+import { verifyMigrationHash } from './hash';
+import { deriveProvidedInvariants } from './invariants';
+import type { MigrationMetadata } from './metadata';
+import { MigrationOpsSchema } from './op-schema';
+import type { MigrationOps, MigrationPackage } from './package';
 
 const MANIFEST_FILE = 'migration.json';
 const OPS_FILE = 'ops.json';
@@ -25,15 +31,16 @@ const MigrationHintsSchema = type({
   plannerVersion: 'string',
 });
 
-const MigrationManifestSchema = type({
-  from: 'string',
+const MigrationMetadataSchema = type({
+  '+': 'reject',
+  from: 'string > 0 | null',
   to: 'string',
-  migrationId: 'string',
-  kind: "'regular' | 'baseline'",
+  migrationHash: 'string',
   fromContract: 'object | null',
   toContract: 'object',
   hints: MigrationHintsSchema,
   labels: 'string[]',
+  providedInvariants: 'string[]',
   'authorship?': type({
     'author?': 'string',
     'email?': 'string',
@@ -45,18 +52,9 @@ const MigrationManifestSchema = type({
   createdAt: 'string',
 });
 
-const MigrationOpSchema = type({
-  id: 'string',
-  label: 'string',
-  operationClass: "'additive' | 'widening' | 'destructive' | 'data'",
-});
-
-// Intentionally shallow: operation-specific payload validation is owned by planner/runner layers.
-const MigrationOpsSchema = MigrationOpSchema.array();
-
 export async function writeMigrationPackage(
   dir: string,
-  manifest: MigrationManifest,
+  metadata: MigrationMetadata,
   ops: MigrationOps,
 ): Promise<void> {
   await mkdir(dirname(dir), { recursive: true });
@@ -70,7 +68,9 @@ export async function writeMigrationPackage(
     throw error;
   }
 
-  await writeFile(join(dir, MANIFEST_FILE), JSON.stringify(manifest, null, 2), { flag: 'wx' });
+  await writeFile(join(dir, MANIFEST_FILE), JSON.stringify(metadata, null, 2), {
+    flag: 'wx',
+  });
   await writeFile(join(dir, OPS_FILE), JSON.stringify(ops, null, 2), { flag: 'wx' });
 }
 
@@ -98,18 +98,18 @@ export async function copyFilesWithRename(
   }
 }
 
-export async function writeMigrationManifest(
+export async function writeMigrationMetadata(
   dir: string,
-  manifest: MigrationManifest,
+  metadata: MigrationMetadata,
 ): Promise<void> {
-  await writeFile(join(dir, MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`);
+  await writeFile(join(dir, MANIFEST_FILE), `${JSON.stringify(metadata, null, 2)}\n`);
 }
 
 export async function writeMigrationOps(dir: string, ops: MigrationOps): Promise<void> {
   await writeFile(join(dir, OPS_FILE), `${JSON.stringify(ops, null, 2)}\n`);
 }
 
-export async function readMigrationPackage(dir: string): Promise<MigrationBundle> {
+export async function readMigrationPackage(dir: string): Promise<MigrationPackage> {
   const manifestPath = join(dir, MANIFEST_FILE);
   const opsPath = join(dir, OPS_FILE);
 
@@ -133,9 +133,9 @@ export async function readMigrationPackage(dir: string): Promise<MigrationBundle
     throw error;
   }
 
-  let manifest: MigrationManifest;
+  let metadata: MigrationMetadata;
   try {
-    manifest = JSON.parse(manifestRaw);
+    metadata = JSON.parse(manifestRaw);
   } catch (e) {
     throw errorInvalidJson(manifestPath, e instanceof Error ? e.message : String(e));
   }
@@ -147,22 +147,48 @@ export async function readMigrationPackage(dir: string): Promise<MigrationBundle
     throw errorInvalidJson(opsPath, e instanceof Error ? e.message : String(e));
   }
 
-  validateManifest(manifest, manifestPath);
+  validateMetadata(metadata, manifestPath);
   validateOps(ops, opsPath);
 
-  return {
+  // Re-derive before the hash check so format/duplicate diagnostics
+  // fire with their dedicated codes rather than as a generic hash mismatch.
+  const derivedInvariants = deriveProvidedInvariants(ops);
+  if (!arraysEqual(metadata.providedInvariants, derivedInvariants)) {
+    throw errorProvidedInvariantsMismatch(
+      manifestPath,
+      metadata.providedInvariants,
+      derivedInvariants,
+    );
+  }
+
+  const pkg: MigrationPackage = {
     dirName: basename(dir),
     dirPath: dir,
-    manifest,
+    metadata,
     ops,
   };
+
+  const verification = verifyMigrationHash(pkg);
+  if (!verification.ok) {
+    throw errorMigrationHashMismatch(dir, verification.storedHash, verification.computedHash);
+  }
+
+  return pkg;
+}
+
+function arraysEqual(a: readonly string[], b: readonly string[]): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
 }
 
-function validateManifest(
-  manifest: unknown,
+function validateMetadata(
+  metadata: unknown,
   filePath: string,
-): asserts manifest is MigrationManifest {
-  const result = MigrationManifestSchema(manifest);
+): asserts metadata is MigrationMetadata {
+  const result = MigrationMetadataSchema(metadata);
   if (result instanceof type.errors) {
     throw errorInvalidManifest(filePath, result.summary);
   }
@@ -177,7 +203,7 @@ function validateOps(ops: unknown, filePath: string): asserts ops is MigrationOp
 
 export async function readMigrationsDir(
   migrationsRoot: string,
-): Promise<readonly MigrationBundle[]> {
+): Promise<readonly MigrationPackage[]> {
   let entries: string[];
   try {
     entries = await readdir(migrationsRoot);
@@ -188,7 +214,7 @@ export async function readMigrationsDir(
     throw error;
   }
 
-  const packages: MigrationBundle[] = [];
+  const packages: MigrationPackage[] = [];
 
   for (const entry of entries.sort()) {
     const entryPath = join(migrationsRoot, entry);

package/src/metadata.ts

@@ -0,0 +1,41 @@
+import type { Contract } from '@prisma-next/contract/types';
+
+export interface MigrationHints {
+  readonly used: readonly string[];
+  readonly applied: readonly string[];
+  readonly plannerVersion: string;
+}
+
+/**
+ * In-memory migration metadata envelope. Every migration is content-addressed:
+ * the `migrationHash` is a hash over the metadata envelope plus the operations
+ * list, computed at write time. There is no draft state — a migration
+ * directory either exists with fully attested metadata or it does not.
+ *
+ * When the planner cannot lower an operation because of an unfilled
+ * `placeholder(...)` slot, the migration is still written with `migrationHash`
+ * hashed over `ops: []`. Re-running self-emit after the user fills the
+ * placeholder produces a *different* `migrationHash` (committed to the real
+ * ops); this is intentional.
+ *
+ * The on-disk JSON shape in `migration.json` matches this type field-for-field
+ * — `JSON.stringify(metadata, null, 2)` is the canonical writer output.
+ */
+export interface MigrationMetadata {
+  readonly migrationHash: string;
+  readonly from: string | null;
+  readonly to: string;
+  readonly fromContract: Contract | null;
+  readonly toContract: Contract;
+  readonly hints: MigrationHints;
+  readonly labels: readonly string[];
+  /**
+   * Sorted, deduplicated list of `invariantId`s declared by the
+   * migration's data-transform ops. Always present; an empty array
+   * means the migration has no routing-visible data transforms.
+   */
+  readonly providedInvariants: readonly string[];
+  readonly authorship?: { readonly author?: string; readonly email?: string };
+  readonly signature?: { readonly keyId: string; readonly value: string } | null;
+  readonly createdAt: string;
+}

package/src/migration-base.ts

@@ -1,27 +1,34 @@
-import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import type { Contract } from '@prisma-next/contract/types';
 import type {
+  ControlStack,
   MigrationPlan,
   MigrationPlanOperation,
 } from '@prisma-next/framework-components/control';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { type } from 'arktype';
-import { dirname, join } from 'pathe';
-import { computeMigrationId } from './attestation';
-import type { MigrationHints, MigrationManifest, MigrationOps } from './types';
+import { errorInvalidOperationEntry, errorStaleContractBookends } from './errors';
+import { computeMigrationHash } from './hash';
+import { deriveProvidedInvariants } from './invariants';
+import type { MigrationHints, MigrationMetadata } from './metadata';
+import { MigrationOpSchema } from './op-schema';
+import type { MigrationOps } from './package';
 
 export interface MigrationMeta {
-  readonly from: string;
+  readonly from: string | null;
   readonly to: string;
-  readonly kind?: 'regular' | 'baseline';
   readonly labels?: readonly string[];
 }
 
+// `from` rejects empty strings to mirror `MigrationMetadataSchema` in
+// `./io.ts`. Without this match, an authored migration could `describe()` with
+// `from: ''` and pass `buildMigrationArtifacts`'s validation, only to have
+// `readMigrationPackage` reject the resulting `migration.json` later — the
+// two validators must agree on the legal value space.
 const MigrationMetaSchema = type({
-  from: 'string',
+  from: 'string > 0 | null',
   to: 'string',
-  'kind?': "'regular' | 'baseline'",
   'labels?': type('string').array(),
 });
 
@@ -30,15 +37,33 @@ const MigrationMetaSchema = type({
  *
  * A `Migration` subclass is itself a `MigrationPlan`: CLI commands and the
  * runner can consume it directly via `targetId`, `operations`, `origin`, and
- * `destination`. The manifest-shaped inputs come from `describe()`, which
+ * `destination`. The metadata-shaped inputs come from `describe()`, which
  * every migration must implement — `migration.json` is required for a
  * migration to be valid.
  */
-export abstract class Migration<TOperation extends MigrationPlanOperation = MigrationPlanOperation>
-  implements MigrationPlan
+export abstract class Migration<
+  TOperation extends MigrationPlanOperation = MigrationPlanOperation,
+  TFamilyId extends string = string,
+  TTargetId extends string = string,
+> implements MigrationPlan
 {
   abstract readonly targetId: string;
 
+  /**
+   * Assembled `ControlStack` injected by the orchestrator (`runMigration`).
+   *
+   * Subclasses (e.g. `PostgresMigration`) read the stack to materialize their
+   * adapter once per instance. Optional at the abstract level so unit tests can
+   * construct `Migration` instances purely for `operations` / `describe`
+   * assertions without needing a real stack; concrete subclasses that need the
+   * stack at runtime should narrow the parameter to required.
+   */
+  protected readonly stack: ControlStack<TFamilyId, TTargetId> | undefined;
+
+  constructor(stack?: ControlStack<TFamilyId, TTargetId>) {
+    this.stack = stack;
+  }
+
   /**
    * Ordered list of operations this migration performs.
    *
@@ -56,124 +81,140 @@ export abstract class Migration<TOperation extends MigrationPlanOperation = Migr
 
   get origin(): { readonly storageHash: string } | null {
     const from = this.describe().from;
-    // An empty `from` represents a migration with no prior origin (e.g.
-    // initial baseline, or an in-process plan that was never persisted).
-    // Surface that as a null origin so runners treat the plan as
-    // origin-less rather than matching against an empty storage hash.
-    return from === '' ? null : { storageHash: from };
+    return from === null ? null : { storageHash: from };
   }
 
   get destination(): { readonly storageHash: string } {
     return { storageHash: this.describe().to };
   }
+}
 
-  /**
-   * Entrypoint guard for migration files. When called at module scope,
-   * detects whether the file is being run directly (e.g. `node migration.ts`)
-   * and if so, serializes the migration plan to `ops.json` and
-   * `migration.json` in the same directory. When the file is imported by
-   * another module, this is a no-op.
-   *
-   * Usage (at module scope, after the class definition):
-   *
-   *     class MyMigration extends Migration { ... }
-   *     export default MyMigration;
-   *     Migration.run(import.meta.url, MyMigration);
-   */
-  static run(importMetaUrl: string, MigrationClass: new () => Migration): void {
-    if (!importMetaUrl) return;
-
-    const metaFilename = fileURLToPath(importMetaUrl);
-    const argv1 = process.argv[1];
-    if (!argv1) return;
-
-    let isEntrypoint: boolean;
-    try {
-      isEntrypoint = realpathSync(metaFilename) === realpathSync(argv1);
-    } catch {
-      return;
-    }
-    if (!isEntrypoint) return;
-
-    const args = process.argv.slice(2);
-
-    if (args.includes('--help')) {
-      printHelp();
-      return;
-    }
-
-    const dryRun = args.includes('--dry-run');
-    const migrationDir = dirname(metaFilename);
-
-    try {
-      serializeMigration(MigrationClass, migrationDir, dryRun);
-    } catch (err) {
-      process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
-      process.exitCode = 1;
-    }
+/**
+ * Returns true when `import.meta.url` resolves to the same file that was
+ * invoked as the node entrypoint (`process.argv[1]`). Used by
+ * `MigrationCLI.run` (in `@prisma-next/cli/migration-cli`) to no-op when
+ * the migration module is being imported (e.g. by another script) rather
+ * than executed directly.
+ */
+export function isDirectEntrypoint(importMetaUrl: string): boolean {
+  const metaFilename = fileURLToPath(importMetaUrl);
+  const argv1 = process.argv[1];
+  if (!argv1) return false;
+  try {
+    return realpathSync(metaFilename) === realpathSync(argv1);
+  } catch {
+    return false;
   }
 }
 
-function printHelp(): void {
-  process.stdout.write(
-    [
-      'Usage: node <migration-file> [options]',
-      '',
-      'Options:',
-      '  --dry-run  Print operations to stdout without writing files',
-      '  --help     Show this help message',
-      '',
-    ].join('\n'),
-  );
+/**
+ * In-memory artifacts produced from a `Migration` instance: the
+ * serialized `ops.json` body, the `migration.json` metadata object, and
+ * its serialized form. Returned by `buildMigrationArtifacts` so callers
+ * (today: `MigrationCLI.run` in `@prisma-next/cli/migration-cli`) can
+ * decide how to persist them — write to disk, print in dry-run, ship
+ * over the wire — without coupling artifact construction to file I/O.
+ *
+ * `metadataJson` is `JSON.stringify(metadata, null, 2)` — the canonical
+ * on-disk shape that the arktype loader-schema in `./io` validates.
+ */
+export interface MigrationArtifacts {
+  readonly opsJson: string;
+  readonly metadata: MigrationMetadata;
+  readonly metadataJson: string;
 }
 
 /**
- * Build the attested manifest written by `Migration.run()`.
+ * Build the attested metadata from `describe()`-derived metadata, the
+ * operations list, and the previously-scaffolded metadata (if any).
  *
- * When a `migration.json` already exists in the directory (the common case:
- * the package was scaffolded by `migration plan`), preserve the contract
+ * When a `migration.json` already exists for this package (the common
+ * case: it was scaffolded by `migration plan`), preserve the contract
  * bookends, hints, labels, and `createdAt` set there — those fields are
  * owned by the CLI scaffolder, not the authored class. Only the
- * `describe()`-derived fields (`from`, `to`, `kind`) and the operations
- * change as the author iterates. When no manifest exists yet (a bare
+ * `describe()`-derived fields (`from`, `to`) and the operations
+ * change as the author iterates. When no metadata exists yet (a bare
  * `migration.ts` run from scratch), synthesize a minimal but
- * schema-conformant manifest so the resulting package can still be read,
+ * schema-conformant record so the resulting package can still be read,
  * verified, and applied.
  *
- * The `migrationId` is recomputed against the current manifest + ops so
+ * The `migrationHash` is recomputed against the current metadata + ops so
  * the on-disk artifacts are always fully attested.
  */
-function buildAttestedManifest(
-  migrationDir: string,
+function buildAttestedMetadata(
   meta: MigrationMeta,
   ops: MigrationOps,
-): MigrationManifest {
-  const existing = readExistingManifest(join(migrationDir, 'migration.json'));
+  existing: Partial<MigrationMetadata> | null,
+): MigrationMetadata {
+  assertBookendsMatchMeta(meta, existing);
 
-  const baseManifest: Omit<MigrationManifest, 'migrationId'> = {
+  const baseMetadata: Omit<MigrationMetadata, 'migrationHash'> = {
     from: meta.from,
     to: meta.to,
-    kind: meta.kind ?? 'regular',
     labels: meta.labels ?? existing?.labels ?? [],
+    providedInvariants: deriveProvidedInvariants(ops),
     createdAt: existing?.createdAt ?? new Date().toISOString(),
     fromContract: existing?.fromContract ?? null,
-    // When no scaffolded manifest exists we synthesize a minimal contract
+    // When no scaffolded metadata exists we synthesize a minimal contract
     // stub so the package is still readable end-to-end. The cast is
     // intentional: only the storage bookend matters for hash computation
-    // (everything else is stripped by `computeMigrationId`), and a real
+    // (everything else is stripped by `computeMigrationHash`), and a real
     // contract bookend would only be available after `migration plan`.
     toContract: existing?.toContract ?? ({ storage: { storageHash: meta.to } } as Contract),
     hints: normalizeHints(existing?.hints),
     ...ifDefined('authorship', existing?.authorship),
   };
 
-  const migrationId = computeMigrationId(baseManifest, ops);
-  return { ...baseManifest, migrationId };
+  const migrationHash = computeMigrationHash(baseMetadata, ops);
+  return { ...baseMetadata, migrationHash };
+}
+
+/**
+ * Verify each preserved contract bookend in `existing` agrees with the
+ * corresponding side of `describe()`'s output. A mismatch indicates the
+ * migration's `describe()` was edited after `migration plan` scaffolded
+ * the package, leaving a self-inconsistent manifest. Failing fast at
+ * write-time turns a silent foot-gun into an actionable diagnostic.
+ *
+ * Skipped when a side's `existing.<side>Contract` is null/absent (the
+ * synthesis path stays open for origin-less initial migrations and for
+ * bare `migration.ts` runs from scratch). When a bookend is *present*
+ * but its `storage.storageHash` is missing, that's treated as a
+ * mismatch — a malformed bookend is not equivalent to "no bookend".
+ *
+ * This check is paired with TML-2274, which removes `fromContract` /
+ * `toContract` from the manifest entirely; once that lands, this
+ * function and its error code are deleted.
+ */
+function assertBookendsMatchMeta(
+  meta: MigrationMeta,
+  existing: Partial<MigrationMetadata> | null,
+): void {
+  if (existing?.fromContract != null) {
+    const contractHash = existing.fromContract.storage?.storageHash ?? '';
+    if (contractHash !== meta.from) {
+      throw errorStaleContractBookends({
+        side: 'from',
+        metaHash: meta.from,
+        contractHash,
+      });
+    }
+  }
+  if (existing?.toContract != null) {
+    const contractHash = existing.toContract.storage?.storageHash ?? '';
+    if (contractHash !== meta.to) {
+      throw errorStaleContractBookends({
+        side: 'to',
+        metaHash: meta.to,
+        contractHash,
+      });
+    }
+  }
 }
 
 /**
  * Project `existing.hints` down to the known `MigrationHints` shape, dropping
- * any legacy keys that may linger in manifests scaffolded by older CLI
+ * any legacy keys that may linger in metadata scaffolded by older CLI
  * versions (e.g. `planningStrategy`). Picking fields explicitly instead of
  * spreading keeps refreshed `migration.json` files schema-clean regardless
  * of what was on disk before.
@@ -186,34 +227,30 @@ function normalizeHints(existing: MigrationHints | undefined): MigrationHints {
   };
 }
 
-function readExistingManifest(manifestPath: string): Partial<MigrationManifest> | null {
-  let raw: string;
-  try {
-    raw = readFileSync(manifestPath, 'utf-8');
-  } catch {
-    return null;
-  }
-  try {
-    return JSON.parse(raw) as Partial<MigrationManifest>;
-  } catch {
-    return null;
-  }
-}
-
-function serializeMigration(
-  MigrationClass: new () => Migration,
-  migrationDir: string,
-  dryRun: boolean,
-): void {
-  const instance = new MigrationClass();
-
+/**
+ * Pure conversion from a `Migration` instance (plus the previously
+ * scaffolded metadata, when one exists on disk) to the in-memory
+ * artifacts that downstream tooling persists. Owns metadata validation,
+ * metadata synthesis/preservation, hint normalization, and the
+ * content-addressed `migrationHash` computation, but performs no file I/O
+ * — callers handle reads (to source `existing`) and writes (to persist
+ * `opsJson` / `metadataJson`).
+ */
+export function buildMigrationArtifacts(
+  instance: Migration,
+  existing: Partial<MigrationMetadata> | null,
+): MigrationArtifacts {
   const ops = instance.operations;
-
   if (!Array.isArray(ops)) {
     throw new Error('operations must be an array');
   }
 
-  const serializedOps = JSON.stringify(ops, null, 2);
+  for (let index = 0; index < ops.length; index++) {
+    const result = MigrationOpSchema(ops[index]);
+    if (result instanceof type.errors) {
+      throw errorInvalidOperationEntry(index, result.summary);
+    }
+  }
 
   const rawMeta: unknown = instance.describe();
   const parsed = MigrationMetaSchema(rawMeta);
@@ -221,17 +258,11 @@ function serializeMigration(
     throw new Error(`describe() returned invalid metadata: ${parsed.summary}`);
   }
 
-  const manifest = buildAttestedManifest(migrationDir, parsed, ops);
-
-  if (dryRun) {
-    process.stdout.write(`--- migration.json ---\n${JSON.stringify(manifest, null, 2)}\n`);
-    process.stdout.write('--- ops.json ---\n');
-    process.stdout.write(`${serializedOps}\n`);
-    return;
-  }
+  const metadata = buildAttestedMetadata(parsed, ops, existing);
 
-  writeFileSync(join(migrationDir, 'ops.json'), serializedOps);
-  writeFileSync(join(migrationDir, 'migration.json'), JSON.stringify(manifest, null, 2));
-
-  process.stdout.write(`Wrote ops.json + migration.json to ${migrationDir}\n`);
+  return {
+    opsJson: JSON.stringify(ops, null, 2),
+    metadata,
+    metadataJson: JSON.stringify(metadata, null, 2),
+  };
 }