@prisma-next/migration-tools 0.4.0-dev.9 → 0.5.0-dev.1

package/src/dag.ts

@@ -7,9 +7,30 @@ import {
   errorNoTarget,
   errorSameSourceAndTarget,
 } from './errors';
-import type { AttestedMigrationBundle, MigrationChainEntry, MigrationGraph } from './types';
+import { bfs } from './graph-ops';
+import type { MigrationBundle, MigrationChainEntry, MigrationGraph } from './types';
 
-export function reconstructGraph(packages: readonly AttestedMigrationBundle[]): MigrationGraph {
+/** Forward-edge neighbours for BFS: edge `e` from `n` visits `e.to` next. */
+function forwardNeighbours(graph: MigrationGraph, node: string) {
+  return (graph.forwardChain.get(node) ?? []).map((edge) => ({ next: edge.to, edge }));
+}
+
+/** Reverse-edge neighbours for BFS: edge `e` from `n` visits `e.from` next. */
+function reverseNeighbours(graph: MigrationGraph, node: string) {
+  return (graph.reverseChain.get(node) ?? []).map((edge) => ({ next: edge.from, edge }));
+}
+
+function appendEdge(
+  map: Map<string, MigrationChainEntry[]>,
+  key: string,
+  entry: MigrationChainEntry,
+): void {
+  const bucket = map.get(key);
+  if (bucket) bucket.push(entry);
+  else map.set(key, [entry]);
+}
+
+export function reconstructGraph(packages: readonly MigrationBundle[]): MigrationGraph {
   const nodes = new Set<string>();
   const forwardChain = new Map<string, MigrationChainEntry[]>();
   const reverseChain = new Map<string, MigrationChainEntry[]>();
@@ -34,31 +55,24 @@ export function reconstructGraph(packages: readonly AttestedMigrationBundle[]):
       labels: pkg.manifest.labels,
     };
 
-    if (migration.migrationId !== null) {
-      if (migrationById.has(migration.migrationId)) {
-        throw errorDuplicateMigrationId(migration.migrationId);
-      }
-      migrationById.set(migration.migrationId, migration);
-    }
-
-    const fwd = forwardChain.get(from);
-    if (fwd) {
-      fwd.push(migration);
-    } else {
-      forwardChain.set(from, [migration]);
+    if (migrationById.has(migration.migrationId)) {
+      throw errorDuplicateMigrationId(migration.migrationId);
     }
+    migrationById.set(migration.migrationId, migration);
 
-    const rev = reverseChain.get(to);
-    if (rev) {
-      rev.push(migration);
-    } else {
-      reverseChain.set(to, [migration]);
-    }
+    appendEdge(forwardChain, from, migration);
+    appendEdge(reverseChain, to, migration);
   }
 
   return { nodes, forwardChain, reverseChain, migrationById };
 }
 
+// ---------------------------------------------------------------------------
+// Deterministic tie-breaking for BFS neighbour order.
+// Used by `findPath` and `findPathWithDecision` only; not a general-purpose
+// utility. Ordering: label priority → createdAt → to → migrationId.
+// ---------------------------------------------------------------------------
+
 const LABEL_PRIORITY: Record<string, number> = { main: 0, default: 1, feature: 2 };
 
 function labelPriority(labels: readonly string[]): number {
@@ -70,16 +84,25 @@ function labelPriority(labels: readonly string[]): number {
   return best;
 }
 
+function compareTieBreak(a: MigrationChainEntry, b: MigrationChainEntry): number {
+  const lp = labelPriority(a.labels) - labelPriority(b.labels);
+  if (lp !== 0) return lp;
+  const ca = a.createdAt.localeCompare(b.createdAt);
+  if (ca !== 0) return ca;
+  const tc = a.to.localeCompare(b.to);
+  if (tc !== 0) return tc;
+  return a.migrationId.localeCompare(b.migrationId);
+}
+
 function sortedNeighbors(edges: readonly MigrationChainEntry[]): readonly MigrationChainEntry[] {
-  return [...edges].sort((a, b) => {
-    const lp = labelPriority(a.labels) - labelPriority(b.labels);
-    if (lp !== 0) return lp;
-    const ca = a.createdAt.localeCompare(b.createdAt);
-    if (ca !== 0) return ca;
-    const tc = a.to.localeCompare(b.to);
-    if (tc !== 0) return tc;
-    return (a.migrationId ?? '').localeCompare(b.migrationId ?? '');
-  });
+  return [...edges].sort(compareTieBreak);
+}
+
+/** Ordering adapter for `bfs` — sorts `{next, edge}` pairs by tie-break. */
+function bfsOrdering(
+  items: readonly { next: string; edge: MigrationChainEntry }[],
+): readonly { next: string; edge: MigrationChainEntry }[] {
+  return items.slice().sort((a, b) => compareTieBreak(a.edge, b.edge));
 }
 
 /**
@@ -97,44 +120,40 @@ export function findPath(
 ): readonly MigrationChainEntry[] | null {
   if (fromHash === toHash) return [];
 
-  const visited = new Set<string>();
-  const parent = new Map<string, { node: string; edge: MigrationChainEntry }>();
-  const queue: string[] = [fromHash];
-  visited.add(fromHash);
-
-  while (queue.length > 0) {
-    const current = queue.shift();
-    if (current === undefined) break;
-
-    if (current === toHash) {
+  const parents = new Map<string, { parent: string; edge: MigrationChainEntry }>();
+  for (const step of bfs([fromHash], (n) => forwardNeighbours(graph, n), bfsOrdering)) {
+    if (step.parent !== null && step.incomingEdge !== null) {
+      parents.set(step.node, { parent: step.parent, edge: step.incomingEdge });
+    }
+    if (step.node === toHash) {
       const path: MigrationChainEntry[] = [];
-      let node = toHash;
-      let entry = parent.get(node);
-      while (entry) {
-        const { node: prev, edge } = entry;
-        path.push(edge);
-        node = prev;
-        entry = parent.get(node);
+      let cur = toHash;
+      let p = parents.get(cur);
+      while (p) {
+        path.push(p.edge);
+        cur = p.parent;
+        p = parents.get(cur);
       }
       path.reverse();
       return path;
     }
-
-    const outgoing = graph.forwardChain.get(current);
-    if (!outgoing) continue;
-
-    for (const edge of sortedNeighbors(outgoing)) {
-      if (!visited.has(edge.to)) {
-        visited.add(edge.to);
-        parent.set(edge.to, { node: current, edge });
-        queue.push(edge.to);
-      }
-    }
   }
 
   return null;
 }
 
+/**
+ * Reverse-BFS from `toHash` over `reverseChain` to collect every node from
+ * which `toHash` is reachable (inclusive of `toHash` itself).
+ */
+function collectNodesReachingTarget(graph: MigrationGraph, toHash: string): Set<string> {
+  const reached = new Set<string>();
+  for (const step of bfs([toHash], (n) => reverseNeighbours(graph, n))) {
+    reached.add(step.node);
+  }
+  return reached;
+}
+
 export interface PathDecision {
   readonly selectedPath: readonly MigrationChainEntry[];
   readonly fromHash: string;
@@ -168,16 +187,18 @@ export function findPathWithDecision(
   const path = findPath(graph, fromHash, toHash);
   if (!path) return null;
 
+  // Single reverse BFS marks every node from which `toHash` is reachable.
+  // Replaces a per-edge `findPath(e.to, toHash)` call inside the loop below,
+  // which made the whole function O(|path| · (V + E)) instead of O(V + E).
+  const reachesTarget = collectNodesReachingTarget(graph, toHash);
+
   const tieBreakReasons: string[] = [];
   let alternativeCount = 0;
 
   for (const edge of path) {
     const outgoing = graph.forwardChain.get(edge.from);
     if (outgoing && outgoing.length > 1) {
-      const reachable = outgoing.filter((e) => {
-        const pathFromE = findPath(graph, e.to, toHash);
-        return pathFromE !== null || e.to === toHash;
-      });
+      const reachable = outgoing.filter((e) => reachesTarget.has(e.to));
       if (reachable.length > 1) {
         alternativeCount += reachable.length - 1;
         const sorted = sortedNeighbors(reachable);
@@ -213,17 +234,8 @@ function findDivergencePoint(
 ): string {
   const ancestorSets = leaves.map((leaf) => {
     const ancestors = new Set<string>();
-    const queue = [leaf];
-    while (queue.length > 0) {
-      const current = queue.shift() as string;
-      if (ancestors.has(current)) continue;
-      ancestors.add(current);
-      const incoming = graph.reverseChain.get(current);
-      if (incoming) {
-        for (const edge of incoming) {
-          queue.push(edge.from);
-        }
-      }
+    for (const step of bfs([leaf], (n) => reverseNeighbours(graph, n))) {
+      ancestors.add(step.node);
     }
     return ancestors;
   });
@@ -250,40 +262,26 @@ function findDivergencePoint(
  * `fromHash` via forward edges.
  */
 export function findReachableLeaves(graph: MigrationGraph, fromHash: string): readonly string[] {
-  const visited = new Set<string>();
-  const queue: string[] = [fromHash];
-  visited.add(fromHash);
   const leaves: string[] = [];
-
-  while (queue.length > 0) {
-    const current = queue.shift();
-    if (current === undefined) break;
-    const outgoing = graph.forwardChain.get(current);
-
-    if (!outgoing || outgoing.length === 0) {
-      leaves.push(current);
-    } else {
-      for (const edge of outgoing) {
-        if (!visited.has(edge.to)) {
-          visited.add(edge.to);
-          queue.push(edge.to);
-        }
-      }
+  for (const step of bfs([fromHash], (n) => forwardNeighbours(graph, n))) {
+    if (!graph.forwardChain.get(step.node)?.length) {
+      leaves.push(step.node);
     }
   }
-
   return leaves;
 }
 
 /**
  * Find the target contract hash of the migration graph reachable from
- * EMPTY_CONTRACT_HASH. Throws NO_INITIAL_MIGRATION if the graph has
- * nodes but none originate from the empty hash.
- * Throws AMBIGUOUS_TARGET if multiple branch tips exist.
+ * EMPTY_CONTRACT_HASH. Returns `null` for a graph that has no target
+ * state (either empty, or containing only the root with no outgoing
+ * edges). Throws NO_INITIAL_MIGRATION if the graph has nodes but none
+ * originate from the empty hash, and AMBIGUOUS_TARGET if multiple
+ * branch tips exist.
  */
-export function findLeaf(graph: MigrationGraph): string {
+export function findLeaf(graph: MigrationGraph): string | null {
   if (graph.nodes.size === 0) {
-    return EMPTY_CONTRACT_HASH;
+    return null;
   }
 
   if (!graph.nodes.has(EMPTY_CONTRACT_HASH)) {
@@ -297,7 +295,7 @@ export function findLeaf(graph: MigrationGraph): string {
     if (reachable.length > 0) {
       throw errorNoTarget(reachable);
     }
-    return EMPTY_CONTRACT_HASH;
+    return null;
   }
 
   if (leaves.length > 1) {
@@ -312,8 +310,8 @@ export function findLeaf(graph: MigrationGraph): string {
     throw errorAmbiguousTarget(leaves, { divergencePoint, branches });
   }
 
-  const leaf = leaves[0];
-  return leaf !== undefined ? leaf : EMPTY_CONTRACT_HASH;
+  // biome-ignore lint/style/noNonNullAssertion: leaves.length is neither 0 nor >1 per the branches above, so exactly one leaf remains
+  return leaves[0]!;
 }
 
 /**
@@ -322,21 +320,11 @@ export function findLeaf(graph: MigrationGraph): string {
  * Throws AMBIGUOUS_TARGET if the graph has multiple branch tips.
  */
 export function findLatestMigration(graph: MigrationGraph): MigrationChainEntry | null {
-  if (graph.nodes.size === 0) {
-    return null;
-  }
-
   const leafHash = findLeaf(graph);
-  if (leafHash === EMPTY_CONTRACT_HASH) {
-    return null;
-  }
+  if (leafHash === null) return null;
 
   const path = findPath(graph, EMPTY_CONTRACT_HASH, leafHash);
-  if (!path || path.length === 0) {
-    return null;
-  }
-
-  return path[path.length - 1] ?? null;
+  return path?.at(-1) ?? null;
 }
 
 export function detectCycles(graph: MigrationGraph): readonly string[][] {
@@ -352,37 +340,50 @@ export function detectCycles(graph: MigrationGraph): readonly string[][] {
     color.set(node, WHITE);
   }
 
-  function dfs(u: string): void {
+  // Iterative three-color DFS. A frame is (node, outgoing edges, next-index).
+  interface Frame {
+    node: string;
+    outgoing: readonly MigrationChainEntry[];
+    index: number;
+  }
+  const stack: Frame[] = [];
+
+  function pushFrame(u: string): void {
     color.set(u, GRAY);
+    stack.push({ node: u, outgoing: graph.forwardChain.get(u) ?? [], index: 0 });
+  }
 
-    const outgoing = graph.forwardChain.get(u);
-    if (outgoing) {
-      for (const edge of outgoing) {
-        const v = edge.to;
-        if (color.get(v) === GRAY) {
-          const cycle: string[] = [v];
-          let cur = u;
-          while (cur !== v) {
-            cycle.push(cur);
-            cur = parentMap.get(cur) ?? v;
-          }
-          cycle.reverse();
-          cycles.push(cycle);
-        } else if (color.get(v) === WHITE) {
-          parentMap.set(v, u);
-          dfs(v);
+  for (const root of graph.nodes) {
+    if (color.get(root) !== WHITE) continue;
+    parentMap.set(root, null);
+    pushFrame(root);
+
+    while (stack.length > 0) {
+      // biome-ignore lint/style/noNonNullAssertion: stack.length > 0 should guarantee that this cannot be undefined
+      const frame = stack[stack.length - 1]!;
+      if (frame.index >= frame.outgoing.length) {
+        color.set(frame.node, BLACK);
+        stack.pop();
+        continue;
+      }
+      // biome-ignore lint/style/noNonNullAssertion: the early-continue above guarantees frame.index < frame.outgoing.length here, so this is defined
+      const edge = frame.outgoing[frame.index++]!;
+      const v = edge.to;
+      const vColor = color.get(v);
+      if (vColor === GRAY) {
+        const cycle: string[] = [v];
+        let cur = frame.node;
+        while (cur !== v) {
+          cycle.push(cur);
+          cur = parentMap.get(cur) ?? v;
         }
+        cycle.reverse();
+        cycles.push(cycle);
+      } else if (vColor === WHITE) {
+        parentMap.set(v, frame.node);
+        pushFrame(v);
       }
     }
-
-    color.set(u, BLACK);
-  }
-
-  for (const node of graph.nodes) {
-    if (color.get(node) === WHITE) {
-      parentMap.set(node, null);
-      dfs(node);
-    }
   }
 
   return cycles;
@@ -410,23 +411,8 @@ export function detectOrphans(graph: MigrationGraph): readonly MigrationChainEnt
     }
   }
 
-  const queue = [...startNodes];
-  for (const hash of queue) {
-    reachable.add(hash);
-  }
-
-  while (queue.length > 0) {
-    const node = queue.shift();
-    if (node === undefined) break;
-    const outgoing = graph.forwardChain.get(node);
-    if (!outgoing) continue;
-
-    for (const migration of outgoing) {
-      if (!reachable.has(migration.to)) {
-        reachable.add(migration.to);
-        queue.push(migration.to);
-      }
-    }
+  for (const step of bfs(startNodes, (n) => forwardNeighbours(graph, n))) {
+    reachable.add(step.node);
   }
 
   const orphans: MigrationChainEntry[] = [];

package/src/errors.ts

@@ -84,6 +84,14 @@ export function errorInvalidSlug(slug: string): MigrationToolsError {
   });
 }
 
+export function errorInvalidDestName(destName: string): MigrationToolsError {
+  return new MigrationToolsError('MIGRATION.INVALID_DEST_NAME', 'Invalid copy destination name', {
+    why: `The destination name "${destName}" must be a single path segment (no ".." or directory separators).`,
+    fix: 'Use a simple file name such as "contract.json" for each destination in the copy list.',
+    details: { destName },
+  });
+}
+
 export function errorSameSourceAndTarget(dirName: string, hash: string): MigrationToolsError {
   return new MigrationToolsError(
     'MIGRATION.SAME_SOURCE_AND_TARGET',

package/src/exports/attestation.ts

@@ -1 +1,2 @@
-export { attestMigration, computeMigrationId, verifyMigration } from '../attestation';
+export type { VerifyResult } from '../attestation';
+export { computeMigrationId, verifyMigration, verifyMigrationBundle } from '../attestation';

package/src/exports/io.ts

@@ -1,5 +1,5 @@
 export {
-  copyContractToMigrationDir,
+  copyFilesWithRename,
   formatMigrationDirName,
   readMigrationPackage,
   readMigrationsDir,

package/src/exports/migration-ts.ts

@@ -1,3 +1,3 @@
-export { evaluateMigrationTs, hasMigrationTs, writeMigrationTs } from '../migration-ts';
+export { hasMigrationTs, writeMigrationTs } from '../migration-ts';
 export type { ScaffoldRuntime } from '../runtime-detection';
 export { detectScaffoldRuntime, shebangLineFor } from '../runtime-detection';

package/src/exports/migration.ts

@@ -1 +1,8 @@
-export { Migration, type MigrationMeta } from '../migration-base';
+export {
+  buildMigrationArtifacts,
+  isDirectEntrypoint,
+  Migration,
+  type MigrationArtifacts,
+  type MigrationMeta,
+  printMigrationHelp,
+} from '../migration-base';

package/src/exports/types.ts

@@ -1,16 +1,10 @@
 export { MigrationToolsError } from '../errors';
 export type {
-  AttestedMigrationBundle,
-  AttestedMigrationManifest,
-  BaseMigrationBundle,
-  BaseMigrationBundle as MigrationBundle,
-  BaseMigrationBundle as MigrationPackage,
-  DraftMigrationBundle,
-  DraftMigrationManifest,
+  MigrationBundle,
+  MigrationBundle as MigrationPackage,
   MigrationChainEntry,
   MigrationGraph,
   MigrationHints,
   MigrationManifest,
   MigrationOps,
 } from '../types';
-export { isAttested, isDraft } from '../types';

package/src/graph-ops.ts

@@ -0,0 +1,65 @@
+import { Queue } from './queue';
+
+/**
+ * One step of a BFS traversal.
+ *
+ * `parent` and `incomingEdge` are `null` for start nodes — they were not
+ * reached via any edge. For every other node they record the node and edge
+ * by which this node was first reached.
+ */
+export interface BfsStep<E> {
+  readonly node: string;
+  readonly parent: string | null;
+  readonly incomingEdge: E | null;
+}
+
+/**
+ * Generic breadth-first traversal.
+ *
+ * Direction (forward/reverse) is expressed by the caller's `neighbours`
+ * closure: return `{ next, edge }` pairs where `next` is the node to visit
+ * next and `edge` is the edge that connects them. Callers that don't need
+ * path reconstruction can ignore the `parent`/`incomingEdge` fields of each
+ * yielded step.
+ *
+ * Stops are intrinsic — callers `break` out of the `for..of` loop when
+ * they've found what they're looking for.
+ *
+ * `ordering`, if provided, controls the order in which neighbours of each
+ * node are enqueued. Only matters for path-finding: a deterministic ordering
+ * makes BFS return a deterministic shortest path when multiple exist.
+ */
+export function* bfs<E>(
+  starts: Iterable<string>,
+  neighbours: (node: string) => Iterable<{ next: string; edge: E }>,
+  ordering?: (items: readonly { next: string; edge: E }[]) => readonly { next: string; edge: E }[],
+): Generator<BfsStep<E>> {
+  const visited = new Set<string>();
+  const parentMap = new Map<string, { parent: string; edge: E }>();
+  const queue = new Queue<string>();
+  for (const start of starts) {
+    if (!visited.has(start)) {
+      visited.add(start);
+      queue.push(start);
+    }
+  }
+  while (!queue.isEmpty) {
+    const current = queue.shift();
+    const parentInfo = parentMap.get(current);
+    yield {
+      node: current,
+      parent: parentInfo?.parent ?? null,
+      incomingEdge: parentInfo?.edge ?? null,
+    };
+
+    const items = neighbours(current);
+    const toVisit = ordering ? ordering([...items]) : items;
+    for (const { next, edge } of toVisit) {
+      if (!visited.has(next)) {
+        visited.add(next);
+        parentMap.set(next, { parent: current, edge });
+        queue.push(next);
+      }
+    }
+  }
+}

package/src/io.ts

@@ -3,12 +3,13 @@ import { type } from 'arktype';
 import { basename, dirname, join } from 'pathe';
 import {
   errorDirectoryExists,
+  errorInvalidDestName,
   errorInvalidJson,
   errorInvalidManifest,
   errorInvalidSlug,
   errorMissingFile,
 } from './errors';
-import type { BaseMigrationBundle, MigrationManifest, MigrationOps } from './types';
+import type { MigrationBundle, MigrationManifest, MigrationOps } from './types';
 
 const MANIFEST_FILE = 'migration.json';
 const OPS_FILE = 'ops.json';
@@ -22,13 +23,12 @@ const MigrationHintsSchema = type({
   used: 'string[]',
   applied: 'string[]',
   plannerVersion: 'string',
-  planningStrategy: 'string',
 });
 
 const MigrationManifestSchema = type({
   from: 'string',
   to: 'string',
-  migrationId: 'string | null',
+  migrationId: 'string',
   kind: "'regular' | 'baseline'",
   fromContract: 'object | null',
   toContract: 'object',
@@ -75,27 +75,26 @@ export async function writeMigrationPackage(
 }
 
 /**
- * Copy the destination contract artifacts (`contract.json` and the
- * colocated `contract.d.ts`) into the migration package directory so
- * authors of the scaffolded `migration.ts` can import the typed
- * contract relative to the migration directory
- * (`import type { Contract } from './contract'`).
+ * Copy a list of files into `destDir`, optionally renaming each one.
  *
- * A missing `.d.ts` is tolerated (only the `.json` is required) so the
- * helper stays usable in tests that hand-roll a bare `contract.json`.
- * A missing `contract.json` — or any other I/O failure — throws.
+ * The destination directory is created (with `recursive: true`) if it
+ * does not already exist. Each source path is copied byte-for-byte into
+ * `destDir/<destName>`; missing sources throw `ENOENT`. The helper is
+ * intentionally generic: callers own the list of files (e.g. a contract
+ * emitter's emitted output) and the naming convention (e.g. renaming
+ * the destination contract to `end-contract.*` and the source contract
+ * to `start-contract.*`).
  */
-export async function copyContractToMigrationDir(
-  packageDir: string,
-  contractJsonPath: string,
+export async function copyFilesWithRename(
+  destDir: string,
+  files: readonly { readonly sourcePath: string; readonly destName: string }[],
 ): Promise<void> {
-  await copyFile(contractJsonPath, join(packageDir, 'contract.json'));
-  const dtsPath = `${contractJsonPath.slice(0, -'.json'.length)}.d.ts`;
-  try {
-    await copyFile(dtsPath, join(packageDir, 'contract.d.ts'));
-  } catch (error) {
-    if (hasErrnoCode(error, 'ENOENT')) return;
-    throw error;
+  await mkdir(destDir, { recursive: true });
+  for (const file of files) {
+    if (basename(file.destName) !== file.destName) {
+      throw errorInvalidDestName(file.destName);
+    }
+    await copyFile(file.sourcePath, join(destDir, file.destName));
   }
 }
 
@@ -110,7 +109,7 @@ export async function writeMigrationOps(dir: string, ops: MigrationOps): Promise
   await writeFile(join(dir, OPS_FILE), `${JSON.stringify(ops, null, 2)}\n`);
 }
 
-export async function readMigrationPackage(dir: string): Promise<BaseMigrationBundle> {
+export async function readMigrationPackage(dir: string): Promise<MigrationBundle> {
   const manifestPath = join(dir, MANIFEST_FILE);
   const opsPath = join(dir, OPS_FILE);
 
@@ -178,7 +177,7 @@ function validateOps(ops: unknown, filePath: string): asserts ops is MigrationOp
 
 export async function readMigrationsDir(
   migrationsRoot: string,
-): Promise<readonly BaseMigrationBundle[]> {
+): Promise<readonly MigrationBundle[]> {
   let entries: string[];
   try {
     entries = await readdir(migrationsRoot);
@@ -189,7 +188,7 @@ export async function readMigrationsDir(
     throw error;
   }
 
-  const packages: BaseMigrationBundle[] = [];
+  const packages: MigrationBundle[] = [];
 
   for (const entry of entries.sort()) {
     const entryPath = join(migrationsRoot, entry);