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

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

@@ -0,0 +1,319 @@
+/**
+ * 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 { tryBreakCycleByChangeInjection } from "./cycle-breakers.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";
+
+// `sortPhaseChanges` caps the change-injection breaker at one round per
+// node in the initial phase: there can never be more disjoint unbreakable
+// cycles than there are change nodes (each cycle has ≥ 2 distinct nodes).
+// The cap exists only to surface a buggy breaker as `CycleError` instead
+// of an infinite loop — the actual loop-protection guarantee comes from
+// `breakerRoundSignatures`, which throws the moment the same cycle
+// reappears after a break.
+
+/**
+ * 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];
+}
+
+/**
+ * Normalize a cycle by rotating it to start with the smallest node index, so
+ * cycles that loop through the same nodes in the same direction compare equal
+ * regardless of where DFS happened to enter them.
+ */
+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(",");
+}
+
+type SortRoundResult =
+  | { kind: "sorted"; sorted: Change[] }
+  | {
+      kind: "unbreakable";
+      cycleNodeIndexes: number[];
+      cycleEdges: ReturnType<typeof getEdgesInCycle>;
+    };
+
+/**
+ * One attempt at sorting `phaseChanges`. Builds the graph from scratch,
+ * runs the iterative edge-removal cycle handler, and either returns a
+ * topologically sorted list or reports an unbreakable cycle so the caller
+ * can decide whether to dispatch a change-injection breaker.
+ *
+ * Algorithm:
+ * 1. Build graph data (change sets and reverse indexes).
+ * 2. Convert all sources to Constraints (catalog, explicit, custom).
+ * 3. Convert Constraints to edges.
+ * 4. Iteratively detect and break cycles by removing weak edges.
+ * 5. Perform stable topological sort on the acyclic graph.
+ *
+ * In DROP phase, edges are inverted so drops run in reverse dependency
+ * order.
+ */
+function attemptSortRound(
+  phaseChanges: Change[],
+  dependencyRows: PgDependRow[],
+  options: PhaseSortOptions,
+): SortRoundResult {
+  // 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 by edge filtering.
+  // We loop until no cycles remain OR we see the same cycle twice — the
+  // latter signals that edge filtering exhausted itself. At that point
+  // the caller may dispatch a change-injection breaker; if no breaker
+  // matches, the original throw path runs.
+  const seenCycles = new Set<string>();
+
+  while (true) {
+    const edgePairs = edgesToPairs(edges);
+    const cycleNodeIndexes = findCycle(phaseChanges.length, edgePairs);
+
+    if (!cycleNodeIndexes) break;
+
+    const cycleSignature = normalizeCycle(cycleNodeIndexes);
+    if (seenCycles.has(cycleSignature)) {
+      // Edge filtering can't break this cycle. Report it back to the
+      // caller so it can try change-injection before throwing.
+      return {
+        kind: "unbreakable",
+        cycleNodeIndexes,
+        cycleEdges: getEdgesInCycle(cycleNodeIndexes, edges),
+      };
+    }
+    seenCycles.add(cycleSignature);
+
+    edges = filterEdgesForCycleBreaking(
+      edges,
+      cycleNodeIndexes,
+      phaseChanges,
+      graphData,
+    );
+  }
+
+  const finalEdgePairs = edgesToPairs(edges);
+
+  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 {
+    kind: "sorted",
+    sorted: topologicalOrder.map((changeIndex) => phaseChanges[changeIndex]),
+  };
+}
+
+/**
+ * Sort changes within a phase. Tries `attemptSortRound`; on an unbreakable
+ * cycle, dispatches to `tryBreakCycleByChangeInjection`, retries with the
+ * rewritten changes, and bails after `MAX_CYCLE_BREAKER_ROUNDS` to surface
+ * a buggy breaker as `CycleError` instead of an infinite loop.
+ *
+ * Best case (no cycles, the vast majority of plans): one round, no
+ * change-injection breaker code runs at all.
+ */
+function sortPhaseChanges(
+  initialPhaseChanges: Change[],
+  dependencyRows: PgDependRow[],
+  options: PhaseSortOptions = {},
+): Change[] {
+  if (initialPhaseChanges.length <= 1) return initialPhaseChanges;
+
+  let phaseChanges = initialPhaseChanges;
+  const breakerRoundSignatures = new Set<string>();
+
+  // `attemptSortRound` returns at most one unbreakable cycle per call,
+  // so a phase with K independent unbreakable cycles needs K+1 rounds.
+  // Every cycle contains ≥ 2 distinct change nodes, so the maximum
+  // possible value of K is `floor(initialPhaseChanges.length / 2)` —
+  // using `initialPhaseChanges.length` itself is therefore a real upper
+  // bound with one round of slack (and matches the early-return guard
+  // above, which already excluded length-0 and length-1 phases).
+  const maxRounds = initialPhaseChanges.length;
+
+  for (let round = 0; round <= maxRounds; round++) {
+    const result = attemptSortRound(phaseChanges, dependencyRows, options);
+    if (result.kind === "sorted") return result.sorted;
+
+    // Edge filtering hit an unbreakable cycle. Try the change-injection
+    // breakers (FK pattern, publication↔column pattern). If none matches,
+    // throw with the same diagnostic the original code emitted.
+    const broken = tryBreakCycleByChangeInjection(
+      result.cycleNodeIndexes,
+      phaseChanges,
+    );
+    if (broken === null) {
+      throw new Error(
+        formatCycleError(
+          result.cycleNodeIndexes,
+          phaseChanges,
+          result.cycleEdges,
+        ),
+      );
+    }
+
+    // Loop guard: if the same cycle node-set re-appears after a break,
+    // the breaker isn't making progress. Throw with full context.
+    const signature = normalizeCycle(result.cycleNodeIndexes);
+    if (breakerRoundSignatures.has(signature)) {
+      throw new Error(
+        formatCycleError(
+          result.cycleNodeIndexes,
+          phaseChanges,
+          result.cycleEdges,
+        ),
+      );
+    }
+    breakerRoundSignatures.add(signature);
+
+    phaseChanges = broken;
+  }
+
+  throw new Error(
+    `CycleError: change-injection breaker exceeded ${maxRounds} rounds (one per node in the phase) — likely a buggy breaker rule`,
+  );
+}

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");
+  });
+});