@supabase/pg-delta 1.0.0-alpha.2 → 1.0.0-alpha.20

package/src/core/sort/sort-changes.ts

@@ -0,0 +1,234 @@
+/**
+ * Phased dependency-graph sort for ordered schema changes.
+ *
+ * Changes are split into two execution phases:
+ * - `drop`: Destructive operations (executed first, in reverse dependency order)
+ * - `create_alter_object`: All remaining changes (executed second, in forward dependency order)
+ *
+ * Within each phase, changes are sorted using Constraints derived from:
+ * - Catalog dependencies (from pg_depend)
+ * - Explicit requirements (from Change.requires)
+ * - Custom constraints (change-to-change ordering rules)
+ */
+
+import debug from "debug";
+import type { Catalog } from "../catalog.model.ts";
+import type { Change } from "../change.types.ts";
+import { generateCustomConstraints } from "./custom-constraints.ts";
+import { printDebugGraph } from "./debug-visualization.ts";
+
+const debugGraph = debug("pg-delta:graph");
+
+import {
+  filterEdgesForCycleBreaking,
+  getEdgesInCycle,
+} from "./dependency-filter.ts";
+import {
+  buildGraphData,
+  convertCatalogDependenciesToConstraints,
+  convertConstraintsToEdges,
+  convertExplicitRequirementsToConstraints,
+  edgesToPairs,
+} from "./graph-builder.ts";
+import { dedupeEdges } from "./graph-utils.ts";
+import { logicalSort } from "./logical-sort.ts";
+import {
+  findCycle,
+  formatCycleError,
+  performStableTopologicalSort,
+} from "./topological-sort.ts";
+import type { PgDependRow, PhaseSortOptions } from "./types.ts";
+import { getExecutionPhase, type Phase } from "./utils.ts";
+
+/**
+ * Sort changes using dependency information from catalogs and custom constraints.
+ *
+ * First applies logical pre-sorting to group related changes together,
+ * then applies dependency-based topological sorting to ensure correct execution order.
+ *
+ * @param catalogs - Main and branch catalogs containing dependency information
+ * @param changes - List of Change objects to order
+ * @returns Ordered list of Change objects
+ */
+export function sortChanges(
+  catalogs: { mainCatalog: Catalog; branchCatalog: Catalog },
+  changes: Change[],
+): Change[] {
+  // Step 1: Apply logical pre-sorting to group changes by object type, stable ID, and scope
+  const logicallySorted = logicalSort(changes);
+
+  // Step 2: Apply dependency-based topological sorting
+  return sortChangesByPhasedGraph(
+    {
+      mainCatalog: { depends: catalogs.mainCatalog.depends },
+      branchCatalog: { depends: catalogs.branchCatalog.depends },
+    },
+    logicallySorted,
+  );
+}
+
+/**
+ * Sort changes by phases, using dependency information in each phase.
+ *
+ * @param catalogContext - pg_depend rows from the main and branch catalogs
+ * @param changeList - list of Change objects to order
+ * @returns ordered list of Change objects
+ */
+function sortChangesByPhasedGraph(
+  catalogContext: {
+    mainCatalog: { depends: PgDependRow[] };
+    branchCatalog: { depends: PgDependRow[] };
+  },
+  changeList: Change[],
+): Change[] {
+  const changesByPhase: Record<Phase, Change[]> = {
+    drop: [],
+    create_alter_object: [],
+  };
+
+  // Partition changes into execution phases
+  for (const changeItem of changeList) {
+    const phase = getExecutionPhase(changeItem);
+    changesByPhase[phase].push(changeItem);
+  }
+
+  // Sort DROP phase: reverse dependency order using main catalog dependencies
+  const sortedDropPhase = sortPhaseChanges(
+    changesByPhase.drop,
+    catalogContext.mainCatalog.depends,
+    { invert: true },
+  );
+
+  // Sort CREATE/ALTER phase: forward dependency order using branch catalog dependencies
+  const sortedCreateAlterPhase = sortPhaseChanges(
+    changesByPhase.create_alter_object,
+    catalogContext.branchCatalog.depends,
+    {},
+  );
+
+  return [...sortedDropPhase, ...sortedCreateAlterPhase];
+}
+
+/**
+ * Sort changes within a phase using Constraints derived from all dependency sources.
+ *
+ * Algorithm:
+ * 1. Build graph data (change sets and reverse indexes)
+ * 2. Convert all sources to Constraints (catalog, explicit, custom constraints)
+ * 3. Convert Constraints to edges
+ * 4. Iteratively detect and break cycles (deduplicate edges, detect cycles, filter problematic edges)
+ * 5. Perform stable topological sort on the acyclic graph
+ *
+ * In DROP phase, edges are inverted so drops run in reverse dependency order.
+ */
+function sortPhaseChanges(
+  phaseChanges: Change[],
+  dependencyRows: PgDependRow[],
+  options: PhaseSortOptions = {},
+): Change[] {
+  if (phaseChanges.length <= 1) return phaseChanges;
+
+  // Step 1: Build graph data structures
+  const graphData = buildGraphData(phaseChanges, options);
+
+  // Step 2: Convert all sources to Constraints
+  const catalogConstraints = convertCatalogDependenciesToConstraints(
+    dependencyRows,
+    graphData,
+  );
+  const explicitConstraints = convertExplicitRequirementsToConstraints(
+    phaseChanges,
+    graphData,
+  );
+  const customConstraintObjects = generateCustomConstraints(phaseChanges);
+  const allConstraints = [
+    ...catalogConstraints,
+    ...explicitConstraints,
+    ...customConstraintObjects,
+  ];
+
+  // Step 3: Convert constraints to edges and deduplicate immediately
+  let edges = dedupeEdges(convertConstraintsToEdges(allConstraints, options));
+
+  // Step 4: Iteratively detect and break cycles
+  // Track cycles we've seen to detect when filtering fails to break a cycle.
+  // The only way we loop indefinitely is if we encounter a cycle we've already seen,
+  // which means filtering didn't break it. Otherwise, we continue until all cycles are broken.
+  const seenCycles = new Set<string>();
+
+  /**
+   * Normalize a cycle by rotating it to start with the smallest node index.
+   * This allows us to compare cycles regardless of where they start.
+   */
+  function normalizeCycle(cycleNodeIndexes: number[]): string {
+    if (cycleNodeIndexes.length === 0) return "";
+    const minIndex = Math.min(...cycleNodeIndexes);
+    const minIndexPos = cycleNodeIndexes.indexOf(minIndex);
+    const rotated = [
+      ...cycleNodeIndexes.slice(minIndexPos),
+      ...cycleNodeIndexes.slice(0, minIndexPos),
+    ];
+    return rotated.join(",");
+  }
+
+  while (true) {
+    // Edge deduplication moved outside loop
+    const edgePairs = edgesToPairs(edges);
+
+    // Detect cycles
+    const cycleNodeIndexes = findCycle(phaseChanges.length, edgePairs);
+
+    if (!cycleNodeIndexes) {
+      // No cycles found, we're done
+      break;
+    }
+
+    // Normalize cycle to check if we've seen it before
+    const cycleSignature = normalizeCycle(cycleNodeIndexes);
+    if (seenCycles.has(cycleSignature)) {
+      // We've seen this cycle before - filtering didn't break it
+      // Get edges involved in the cycle for detailed error message
+      const cycleEdges = getEdgesInCycle(cycleNodeIndexes, edges);
+      throw new Error(
+        formatCycleError(cycleNodeIndexes, phaseChanges, cycleEdges),
+      );
+    }
+
+    // Track this cycle
+    seenCycles.add(cycleSignature);
+
+    // Filter only edges involved in the cycle to break it
+    edges = filterEdgesForCycleBreaking(
+      edges,
+      cycleNodeIndexes,
+      phaseChanges,
+      graphData,
+    );
+  }
+
+  const finalEdgePairs = edgesToPairs(edges);
+
+  // Debug visualization
+  if (debugGraph.enabled) {
+    printDebugGraph(
+      phaseChanges,
+      graphData,
+      finalEdgePairs,
+      dependencyRows,
+      allConstraints,
+    );
+  }
+
+  // Step 5: Perform stable topological sort (no cycles, so this will succeed)
+  const topologicalOrder = performStableTopologicalSort(
+    phaseChanges.length,
+    finalEdgePairs,
+  );
+
+  if (!topologicalOrder || topologicalOrder.length !== phaseChanges.length) {
+    // This should never happen if findCycle returned null, but guard anyway
+    throw new Error("CycleError: dependency graph contains a cycle");
+  }
+
+  return topologicalOrder.map((changeIndex) => phaseChanges[changeIndex]);
+}

package/src/core/sort/topological-sort.test.ts

@@ -0,0 +1,275 @@
+import { describe, expect, test } from "bun:test";
+import type { Change } from "../change.types.ts";
+import {
+  findCycle,
+  formatCycleError,
+  performStableTopologicalSort,
+} from "./topological-sort.ts";
+import type { Constraint } from "./types.ts";
+
+function mockChange(name: string, creates: string[] = []): Change {
+  const change = {
+    objectType: "table",
+    operation: "create" as const,
+    scope: "object",
+    creates,
+    drops: [],
+    requires: [],
+    serialize: () => "",
+  };
+  Object.defineProperty(change, "constructor", { value: { name } });
+  return change as unknown as Change;
+}
+
+describe("performStableTopologicalSort", () => {
+  test("no edges returns identity order", () => {
+    const result = performStableTopologicalSort(3, []);
+    expect(result).toEqual([0, 1, 2]);
+  });
+
+  test("linear chain produces correct order", () => {
+    const result = performStableTopologicalSort(3, [
+      [0, 1],
+      [1, 2],
+    ]);
+    expect(result).toEqual([0, 1, 2]);
+  });
+
+  test("reversed linear chain reorders correctly", () => {
+    const result = performStableTopologicalSort(3, [
+      [2, 1],
+      [1, 0],
+    ]);
+    expect(result).toEqual([2, 1, 0]);
+  });
+
+  test("diamond dependency resolves correctly", () => {
+    const result = performStableTopologicalSort(4, [
+      [0, 1],
+      [0, 2],
+      [1, 3],
+      [2, 3],
+    ]);
+    expect(result).toEqual([0, 1, 2, 3]);
+  });
+
+  test("cycle returns null", () => {
+    const result = performStableTopologicalSort(2, [
+      [0, 1],
+      [1, 0],
+    ]);
+    expect(result).toBeNull();
+  });
+
+  test("stable ordering among unconstrained nodes", () => {
+    const result = performStableTopologicalSort(5, [[3, 4]]);
+    expect(result).toEqual([0, 1, 2, 3, 4]);
+  });
+
+  test("duplicate edges are handled", () => {
+    const result = performStableTopologicalSort(2, [
+      [0, 1],
+      [0, 1],
+    ]);
+    expect(result).toEqual([0, 1]);
+  });
+
+  test("single node returns identity", () => {
+    const result = performStableTopologicalSort(1, []);
+    expect(result).toEqual([0]);
+  });
+});
+
+describe("findCycle", () => {
+  test("no edges means no cycle", () => {
+    expect(findCycle(3, [])).toBeNull();
+  });
+
+  test("linear chain has no cycle", () => {
+    expect(
+      findCycle(3, [
+        [0, 1],
+        [1, 2],
+      ]),
+    ).toBeNull();
+  });
+
+  test("simple cycle is detected", () => {
+    const cycle = findCycle(2, [
+      [0, 1],
+      [1, 0],
+    ]);
+    expect(cycle).not.toBeNull();
+    expect(cycle?.length).toBeGreaterThanOrEqual(2);
+  });
+
+  test("three-node cycle is detected", () => {
+    const cycle = findCycle(3, [
+      [0, 1],
+      [1, 2],
+      [2, 0],
+    ]);
+    expect(cycle).not.toBeNull();
+    expect(cycle?.length).toBe(3);
+  });
+
+  test("self-loop is detected", () => {
+    const cycle = findCycle(1, [[0, 0]]);
+    expect(cycle).not.toBeNull();
+  });
+
+  test("cycle in subgraph is found", () => {
+    const cycle = findCycle(4, [
+      [0, 1],
+      [2, 3],
+      [3, 2],
+    ]);
+    expect(cycle).not.toBeNull();
+    expect(cycle).toContain(2);
+    expect(cycle).toContain(3);
+  });
+});
+
+describe("formatCycleError", () => {
+  test("basic format without cycleEdges", () => {
+    const changes = [
+      mockChange("CreateTable", ["table:public.a"]),
+      mockChange("CreateTable", ["table:public.b"]),
+    ];
+
+    const message = formatCycleError([0, 1], changes);
+    expect(message).toContain("CycleError");
+    expect(message).toContain("2 changes");
+    expect(message).toContain("CreateTable");
+    expect(message).toContain("table:public.a");
+    expect(message).toContain("table:public.b");
+    expect(message).toContain("circular dependency");
+    expect(message).not.toContain("Cycle path");
+  });
+
+  test("catalog source with dependentStableId", () => {
+    const changes = [
+      mockChange("CreateTable", ["table:public.a"]),
+      mockChange("CreateView", ["view:public.v"]),
+    ];
+
+    const constraint: Constraint = {
+      sourceChangeIndex: 0,
+      targetChangeIndex: 1,
+      source: "catalog",
+      reason: {
+        dependentStableId: "view:public.v",
+        referencedStableId: "table:public.a",
+      },
+    };
+
+    const message = formatCycleError([0, 1], changes, [
+      { sourceIndex: 0, targetIndex: 1, constraint },
+    ]);
+    expect(message).toContain("Cycle path");
+    expect(message).toContain("source: catalog");
+    expect(message).toContain("Dependency: view:public.v → table:public.a");
+    expect(message).toContain("Cycle-breaking filter did not match");
+    expect(message).toContain("cycle-breaking filters were unable");
+  });
+
+  test("explicit source without dependentStableId", () => {
+    const changes = [
+      mockChange("CreateTable"),
+      mockChange("CreateView", ["view:public.v"]),
+    ];
+
+    const constraint: Constraint = {
+      sourceChangeIndex: 0,
+      targetChangeIndex: 1,
+      source: "explicit",
+      reason: {
+        referencedStableId: "table:public.a",
+      },
+    };
+
+    const message = formatCycleError([0, 1], changes, [
+      { sourceIndex: 0, targetIndex: 1, constraint },
+    ]);
+    expect(message).toContain("source: explicit");
+    expect(message).toContain("Requires: table:public.a");
+    expect(message).toContain(
+      "Explicit requirement without created IDs (not filtered)",
+    );
+  });
+
+  test("custom source constraint", () => {
+    const changes = [
+      mockChange("CreateTable", ["table:public.a"]),
+      mockChange("CreateTable", ["table:public.b"]),
+    ];
+
+    const constraint: Constraint = {
+      sourceChangeIndex: 0,
+      targetChangeIndex: 1,
+      source: "custom",
+    };
+
+    const message = formatCycleError([0, 1], changes, [
+      { sourceIndex: 0, targetIndex: 1, constraint },
+    ]);
+    expect(message).toContain("source: custom");
+    expect(message).toContain("Custom constraint (never filtered)");
+  });
+
+  test("edge not found in cycleEdges", () => {
+    const changes = [
+      mockChange("CreateTable", ["table:public.a"]),
+      mockChange("CreateTable", ["table:public.b"]),
+      mockChange("CreateView", ["view:public.v"]),
+    ];
+
+    const unrelatedConstraint: Constraint = {
+      sourceChangeIndex: 2,
+      targetChangeIndex: 0,
+      source: "custom",
+    };
+
+    const message = formatCycleError([0, 1], changes, [
+      { sourceIndex: 2, targetIndex: 0, constraint: unrelatedConstraint },
+    ]);
+    expect(message).toContain("(edge not found)");
+  });
+
+  test("explicit source with dependentStableId uses filter message", () => {
+    const changes = [
+      mockChange("CreateTable", ["table:public.a"]),
+      mockChange("CreateView", ["view:public.v"]),
+    ];
+
+    const constraint: Constraint = {
+      sourceChangeIndex: 0,
+      targetChangeIndex: 1,
+      source: "explicit",
+      reason: {
+        dependentStableId: "view:public.v",
+        referencedStableId: "table:public.a",
+      },
+    };
+
+    const message = formatCycleError([0, 1], changes, [
+      { sourceIndex: 0, targetIndex: 1, constraint },
+    ]);
+    expect(message).toContain("Dependency: view:public.v → table:public.a");
+    expect(message).toContain("Cycle-breaking filter did not match");
+  });
+
+  test("change with many creates truncates", () => {
+    const changes = [
+      mockChange("CreateTable", [
+        "table:public.a",
+        "table:public.b",
+        "table:public.c",
+      ]),
+    ];
+
+    const message = formatCycleError([0], changes);
+    expect(message).toContain("table:public.a, table:public.b...");
+    expect(message).not.toContain("table:public.c");
+  });
+});

package/src/core/sort/topological-sort.ts

@@ -0,0 +1,184 @@
+import type { Change } from "../change.types.ts";
+import type { Constraint } from "./types.ts";
+
+/**
+ * Stable topological sort. If multiple zero-indegree nodes exist, picks the
+ * smallest original index first to preserve input order among unconstrained items.
+ * Returns null on cycles.
+ */
+export function performStableTopologicalSort(
+  nodeCount: number,
+  edges: Array<[number, number]>,
+): number[] | null {
+  const adjacencyList: Array<Set<number>> = Array.from(
+    { length: nodeCount },
+    () => new Set<number>(),
+  );
+  const inDegreeCounts = new Array<number>(nodeCount).fill(0);
+
+  for (const [sourceIndex, targetIndex] of edges) {
+    if (!adjacencyList[sourceIndex].has(targetIndex)) {
+      adjacencyList[sourceIndex].add(targetIndex);
+      inDegreeCounts[targetIndex]++;
+    }
+  }
+
+  const candidateQueue: number[] = [];
+  for (let nodeIndex = 0; nodeIndex < nodeCount; nodeIndex++) {
+    if (inDegreeCounts[nodeIndex] === 0) candidateQueue.push(nodeIndex);
+  }
+  candidateQueue.sort((left, right) => left - right);
+
+  const orderedNodeIndexes: number[] = [];
+  while (candidateQueue.length > 0) {
+    const nodeIndex = candidateQueue.shift() as number;
+    orderedNodeIndexes.push(nodeIndex);
+    for (const neighborIndex of adjacencyList[nodeIndex]) {
+      inDegreeCounts[neighborIndex]--;
+      if (inDegreeCounts[neighborIndex] === 0) {
+        let inserted = false;
+        for (
+          let queuePosition = 0;
+          queuePosition < candidateQueue.length;
+          queuePosition++
+        ) {
+          if (neighborIndex < candidateQueue[queuePosition]) {
+            candidateQueue.splice(queuePosition, 0, neighborIndex);
+            inserted = true;
+            break;
+          }
+        }
+        if (!inserted) candidateQueue.push(neighborIndex);
+      }
+    }
+  }
+
+  if (orderedNodeIndexes.length !== nodeCount) return null; // cycle detected
+  return orderedNodeIndexes;
+}
+
+/**
+ * Find one cycle (if any) and return its node indices in order.
+ */
+export function findCycle(
+  nodeCount: number,
+  edges: Array<[number, number]>,
+): number[] | null {
+  const adjacencyList: Array<number[]> = Array.from(
+    { length: nodeCount },
+    () => [],
+  );
+  for (const [sourceIndex, targetIndex] of edges) {
+    adjacencyList[sourceIndex].push(targetIndex);
+  }
+
+  // 0 = unvisited, 1 = visiting, 2 = completed
+  const visitState = new Array<number>(nodeCount).fill(0);
+  const pathStack: number[] = [];
+  let cycleNodeIndexes: number[] | null = null;
+
+  const depthFirstSearch = (nodeIndex: number) => {
+    if (cycleNodeIndexes) return;
+    visitState[nodeIndex] = 1;
+    pathStack.push(nodeIndex);
+
+    for (const neighborIndex of adjacencyList[nodeIndex]) {
+      if (visitState[neighborIndex] === 0) {
+        depthFirstSearch(neighborIndex);
+      } else if (visitState[neighborIndex] === 1) {
+        const cycleStartIndex = pathStack.lastIndexOf(neighborIndex);
+        if (cycleStartIndex !== -1) {
+          cycleNodeIndexes = pathStack.slice(cycleStartIndex);
+        }
+        return;
+      }
+      if (cycleNodeIndexes) return;
+    }
+
+    pathStack.pop();
+    visitState[nodeIndex] = 2;
+  };
+
+  for (
+    let nodeIndex = 0;
+    nodeIndex < nodeCount && !cycleNodeIndexes;
+    nodeIndex++
+  ) {
+    if (visitState[nodeIndex] === 0) depthFirstSearch(nodeIndex);
+  }
+
+  return cycleNodeIndexes;
+}
+
+/**
+ * Format a cycle error message with details about the changes involved and the edges forming the cycle.
+ */
+export function formatCycleError(
+  cycleNodeIndexes: number[],
+  phaseChanges: Change[],
+  cycleEdges?: Array<{
+    sourceIndex: number;
+    targetIndex: number;
+    constraint: Constraint;
+  }>,
+): string {
+  const cycleChanges = cycleNodeIndexes.map((idx) => phaseChanges[idx]);
+  const changeDescriptions = cycleChanges.map((change, i) => {
+    const className = change?.constructor?.name ?? "Change";
+    const creates = change.creates.slice(0, 2).join(", ");
+    return `  ${i + 1}. [${cycleNodeIndexes[i]}] ${className}${creates ? ` (creates: ${creates}${change.creates.length > 2 ? "..." : ""})` : ""}`;
+  });
+
+  let message = `CycleError: dependency graph contains a cycle involving ${cycleNodeIndexes.length} changes:\n${changeDescriptions.join("\n")}`;
+
+  // Add cycle path information if edges are provided
+  if (cycleEdges && cycleEdges.length > 0) {
+    message += `\n\nCycle path (edges forming the cycle):`;
+    for (let i = 0; i < cycleNodeIndexes.length; i++) {
+      const sourceIndex = cycleNodeIndexes[i];
+      const targetIndex = cycleNodeIndexes[(i + 1) % cycleNodeIndexes.length];
+      const edge = cycleEdges.find(
+        (e) => e.sourceIndex === sourceIndex && e.targetIndex === targetIndex,
+      );
+
+      if (edge) {
+        const constraint = edge.constraint;
+        let edgeInfo = `\n  [${sourceIndex}] → [${targetIndex}] (source: ${constraint.source})`;
+
+        if (
+          constraint.source === "catalog" ||
+          constraint.source === "explicit"
+        ) {
+          if (constraint.reason.dependentStableId) {
+            edgeInfo += `\n    Dependency: ${constraint.reason.dependentStableId} → ${constraint.reason.referencedStableId}`;
+          } else {
+            edgeInfo += `\n    Requires: ${constraint.reason.referencedStableId}`;
+          }
+        }
+
+        // Add why it wasn't filtered
+        if (constraint.source === "custom") {
+          edgeInfo += `\n    Reason: Custom constraint (never filtered)`;
+        } else if (
+          constraint.source === "explicit" &&
+          !constraint.reason.dependentStableId
+        ) {
+          edgeInfo += `\n    Reason: Explicit requirement without created IDs (not filtered)`;
+        } else {
+          edgeInfo += `\n    Reason: Cycle-breaking filter did not match (edge preserved)`;
+        }
+
+        message += edgeInfo;
+      } else {
+        message += `\n  [${sourceIndex}] → [${targetIndex}] (edge not found)`;
+      }
+    }
+  }
+
+  message += `\n\nThis usually indicates a circular dependency in the schema changes that cannot be resolved.`;
+  if (cycleEdges && cycleEdges.length > 0) {
+    message += `\nThe cycle-breaking filters were unable to break this cycle.`;
+  }
+
+  return message;
+}