@prisma-next/migration-tools 0.5.0-dev.6 → 0.5.0-dev.60

package/src/invariants.ts

@@ -0,0 +1,45 @@
+import type { MigrationPlanOperation } from '@prisma-next/framework-components/control';
+import { errorDuplicateInvariantInEdge, errorInvalidInvariantId } from './errors';
+import type { MigrationOps } from './package';
+
+/**
+ * Hygiene check for `invariantId`. Rejects empty values plus any
+ * whitespace or control character (including Unicode whitespace like
+ * NBSP and em space, which are visually identical to ASCII space and
+ * routinely sneak in via paste).
+ */
+export function validateInvariantId(invariantId: string): boolean {
+  if (invariantId.length === 0) return false;
+  return !/[\p{Cc}\p{White_Space}]/u.test(invariantId);
+}
+
+/**
+ * Walk a migration's operations and produce its `providedInvariants`
+ * aggregate: the sorted, deduplicated list of `invariantId`s declared
+ * by data-transform ops. Ops without `operationClass === 'data'` are
+ * skipped; data ops without an `invariantId` are skipped.
+ *
+ * Throws `MIGRATION.INVALID_INVARIANT_ID` on a malformed id and
+ * `MIGRATION.DUPLICATE_INVARIANT_IN_EDGE` on duplicates.
+ */
+export function deriveProvidedInvariants(ops: MigrationOps): readonly string[] {
+  const seen = new Set<string>();
+  for (const op of ops) {
+    const invariantId = readInvariantId(op);
+    if (invariantId === undefined) continue;
+    if (!validateInvariantId(invariantId)) {
+      throw errorInvalidInvariantId(invariantId);
+    }
+    if (seen.has(invariantId)) {
+      throw errorDuplicateInvariantInEdge(invariantId);
+    }
+    seen.add(invariantId);
+  }
+  return [...seen].sort();
+}
+
+function readInvariantId(op: MigrationPlanOperation): string | undefined {
+  if (op.operationClass !== 'data') return undefined;
+  const candidate = (op as { invariantId?: unknown }).invariantId;
+  return typeof candidate === 'string' ? candidate : undefined;
+}

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

@@ -8,20 +8,27 @@ import type {
 } from '@prisma-next/framework-components/control';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { type } from 'arktype';
-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,7 +37,7 @@ 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.
  */
@@ -74,11 +81,7 @@ export abstract class Migration<
 
   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 } {
@@ -104,83 +107,114 @@ export function isDirectEntrypoint(importMetaUrl: string): boolean {
   }
 }
 
-export function printMigrationHelp(): void {
-  printHelp();
-}
-
-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` manifest object, and
+ * 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 manifest: MigrationManifest;
-  readonly manifestJson: string;
+  readonly metadata: MigrationMetadata;
+  readonly metadataJson: string;
 }
 
 /**
- * Build the attested manifest from `describe()`-derived metadata, the
- * operations list, and the previously-scaffolded manifest (if any).
+ * Build the attested metadata from `describe()`-derived metadata, the
+ * operations list, and the previously-scaffolded metadata (if any).
  *
  * 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(
+function buildAttestedMetadata(
   meta: MigrationMeta,
   ops: MigrationOps,
-  existing: Partial<MigrationManifest> | null,
-): MigrationManifest {
-  const baseManifest: Omit<MigrationManifest, 'migrationId'> = {
+  existing: Partial<MigrationMetadata> | null,
+): MigrationMetadata {
+  assertBookendsMatchMeta(meta, existing);
+
+  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.
@@ -195,33 +229,40 @@ function normalizeHints(existing: MigrationHints | undefined): MigrationHints {
 
 /**
  * Pure conversion from a `Migration` instance (plus the previously
- * scaffolded manifest, when one exists on disk) to the in-memory
+ * scaffolded metadata, when one exists on disk) to the in-memory
  * artifacts that downstream tooling persists. Owns metadata validation,
- * manifest synthesis/preservation, hint normalization, and the
- * content-addressed `migrationId` computation, but performs no file I/O
+ * 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` / `manifestJson`).
+ * `opsJson` / `metadataJson`).
  */
 export function buildMigrationArtifacts(
   instance: Migration,
-  existing: Partial<MigrationManifest> | null,
+  existing: Partial<MigrationMetadata> | null,
 ): MigrationArtifacts {
   const ops = instance.operations;
   if (!Array.isArray(ops)) {
     throw new Error('operations must be an array');
   }
 
+  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);
   if (parsed instanceof type.errors) {
     throw new Error(`describe() returned invalid metadata: ${parsed.summary}`);
   }
 
-  const manifest = buildAttestedManifest(parsed, ops, existing);
+  const metadata = buildAttestedMetadata(parsed, ops, existing);
 
   return {
     opsJson: JSON.stringify(ops, null, 2),
-    manifest,
-    manifestJson: JSON.stringify(manifest, null, 2),
+    metadata,
+    metadataJson: JSON.stringify(metadata, null, 2),
   };
 }