@supabase/pg-delta 1.0.0-alpha.1 → 1.0.0-alpha.11

package/src/cli/utils/export-display.ts

@@ -0,0 +1,275 @@
+/**
+ * CLI helpers for declarative export: file tree, diff, and summary formatting.
+ */
+
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import chalk from "chalk";
+import type { FileEntry } from "../../core/export/types.ts";
+
+// ============================================================================
+// Path safety
+// ============================================================================
+
+/**
+ * Ensure a relative file path does not escape the output directory.
+ * Uses Node.js path.resolve + startsWith as the canonical traversal check.
+ */
+export function assertSafePath(filePath: string, outputDir: string): void {
+  const resolvedOutput = path.resolve(outputDir);
+  const resolvedFile = path.resolve(outputDir, filePath);
+  if (
+    resolvedFile !== resolvedOutput &&
+    !resolvedFile.startsWith(resolvedOutput + path.sep)
+  ) {
+    throw new Error(
+      `Export path traversal detected: '${filePath}' resolves outside output directory`,
+    );
+  }
+}
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface FileDiffResult {
+  created: string[];
+  updated: string[];
+  deleted: string[];
+  unchanged: string[];
+}
+
+// ============================================================================
+// File tree
+// ============================================================================
+
+interface BuildFileTreeOptions {
+  /** When provided, leaf paths are prefixed with + / ~ / - and colorized (created / updated / deleted). */
+  diff?: FileDiffResult;
+  /** When true, only paths that are created, updated, or deleted are shown; unchanged are omitted. Includes diff.deleted in the tree. */
+  diffFocus?: boolean;
+}
+
+type FileStatus = "created" | "updated" | "deleted" | "unchanged";
+
+function getFileStatus(path: string, diff: FileDiffResult): FileStatus {
+  if (diff.created.includes(path)) return "created";
+  if (diff.updated.includes(path)) return "updated";
+  if (diff.deleted.includes(path)) return "deleted";
+  return "unchanged";
+}
+
+function formatLeafSegment(segment: string, status: FileStatus): string {
+  switch (status) {
+    case "created":
+      return chalk.green(`+ ${segment}`);
+    case "updated":
+      return chalk.yellow(`~ ${segment}`);
+    case "deleted":
+      return chalk.red(`- ${segment}`);
+    default:
+      return chalk.dim(segment);
+  }
+}
+
+/**
+ * Build a directory tree string from file paths.
+ * Groups by directory, shows files as leaves with indentation.
+ * When options.diff is provided, leaf names are prefixed with + (created), ~ (updated), - (deleted) and colorized.
+ * When options.diffFocus is true, only changed paths (and their ancestors) are shown; unchanged files are omitted.
+ *
+ * @param files - Array of relative file paths (e.g. ["schemas/public/schema.sql", "schemas/public/tables/users.sql"])
+ * @param outputDir - Display name for the root (e.g. "declarative-schemas")
+ * @param options - Optional diff and diffFocus for symbols and filtering
+ */
+export function buildFileTree(
+  files: string[],
+  outputDir: string,
+  options?: BuildFileTreeOptions,
+): string {
+  const { diff, diffFocus } = options ?? {};
+  let pathsToShow = files;
+
+  if (diffFocus && diff) {
+    const changed = new Set<string>([
+      ...diff.created,
+      ...diff.updated,
+      ...diff.deleted,
+    ]);
+    pathsToShow = [...changed];
+    if (pathsToShow.length === 0) {
+      return chalk.dim("(no file changes)");
+    }
+  }
+
+  const tree = new Map<string, Set<string>>();
+
+  for (const filePath of pathsToShow) {
+    const segments = filePath.split("/");
+    let parent = "";
+    for (let i = 0; i < segments.length; i++) {
+      const segment = segments[i];
+      const fullPath = parent ? `${parent}/${segment}` : segment;
+      let children = tree.get(parent);
+      if (!children) {
+        children = new Set();
+        tree.set(parent, children);
+      }
+      children.add(fullPath);
+      parent = fullPath;
+    }
+  }
+
+  const lines: string[] = [];
+
+  function emit(relPath: string, indent: number, isLast: boolean): void {
+    const segment = relPath ? path.basename(relPath) : outputDir;
+    const prefix =
+      indent === 0 ? "" : "  ".repeat(indent) + (isLast ? "└── " : "├── ");
+    const isLeaf = !tree.has(relPath);
+    const displaySegment =
+      diff && isLeaf
+        ? formatLeafSegment(segment, getFileStatus(relPath, diff))
+        : segment;
+    lines.push(prefix + displaySegment);
+    const children = tree.get(relPath);
+    if (children) {
+      const sorted = [...children].sort((a, b) =>
+        path.basename(a).localeCompare(path.basename(b)),
+      );
+      for (let i = 0; i < sorted.length; i++) {
+        emit(sorted[i], indent + 1, i === sorted.length - 1);
+      }
+    }
+  }
+
+  emit("", 0, false);
+  return lines.join("\n");
+}
+
+// ============================================================================
+// File diff
+// ============================================================================
+
+/**
+ * Recursively collect relative paths of managed (.sql) files under a directory.
+ * Non-SQL files (README, .gitkeep, etc.) are intentionally excluded so they
+ * are never flagged as "deleted" during diff.
+ */
+async function collectExistingFiles(dir: string, base = ""): Promise<string[]> {
+  const entries = await readdir(path.join(dir, base), { withFileTypes: true });
+  const files: string[] = [];
+  for (const e of entries) {
+    const rel = base ? `${base}/${e.name}` : e.name;
+    if (e.isFile() && e.name.endsWith(".sql")) {
+      files.push(rel);
+    } else if (e.isDirectory()) {
+      files.push(...(await collectExistingFiles(dir, rel)));
+    }
+  }
+  return files;
+}
+
+/**
+ * Compare existing output directory with new file set.
+ * Returns created, updated, deleted, and unchanged paths.
+ */
+export async function computeFileDiff(
+  outputDir: string,
+  newFiles: FileEntry[],
+): Promise<FileDiffResult> {
+  const newPaths = new Set(newFiles.map((f) => f.path));
+  const newByPath = new Map(newFiles.map((f) => [f.path, f]));
+
+  let existingPaths: string[] = [];
+  try {
+    existingPaths = await collectExistingFiles(outputDir);
+  } catch {
+    // Directory doesn't exist or not readable
+    return {
+      created: [...newPaths],
+      updated: [],
+      deleted: [],
+      unchanged: [],
+    };
+  }
+
+  const existingSet = new Set(existingPaths);
+  const created: string[] = [];
+  const updated: string[] = [];
+  const deleted: string[] = [];
+  const unchanged: string[] = [];
+
+  for (const p of newPaths) {
+    if (!existingSet.has(p)) {
+      created.push(p);
+    } else {
+      const entry = newByPath.get(p);
+      if (!entry) continue;
+      try {
+        const existingContent = await readFile(
+          path.join(outputDir, p),
+          "utf-8",
+        );
+        if (existingContent.trim() !== entry.sql.trim()) {
+          updated.push(p);
+        } else {
+          unchanged.push(p);
+        }
+      } catch {
+        updated.push(p);
+      }
+    }
+  }
+
+  for (const p of existingPaths) {
+    if (!newPaths.has(p)) {
+      deleted.push(p);
+    }
+  }
+
+  return { created, updated, deleted, unchanged };
+}
+
+// ============================================================================
+// Summary formatting
+// ============================================================================
+
+/**
+ * Format the created/deleted/updated summary with colors.
+ * In dry-run mode, uses "would create/delete/update" phrasing.
+ */
+export function formatExportSummary(
+  diff: FileDiffResult,
+  dryRun: boolean,
+): string {
+  const lines: string[] = [];
+  const verb = dryRun ? "Would" : "";
+
+  if (diff.created.length > 0) {
+    lines.push(
+      chalk.green(
+        `${verb ? `${verb} create` : "Created"}: ${diff.created.length} file(s)`,
+      ),
+    );
+  }
+  if (diff.updated.length > 0) {
+    lines.push(
+      chalk.yellow(
+        `${verb ? `${verb} update` : "Updated"}: ${diff.updated.length} file(s)`,
+      ),
+    );
+  }
+  if (diff.deleted.length > 0) {
+    lines.push(
+      chalk.red(
+        `${verb ? `${verb} delete` : "Deleted"}: ${diff.deleted.length} file(s)`,
+      ),
+    );
+  }
+  if (diff.unchanged.length > 0 && !dryRun) {
+    lines.push(chalk.dim(`Unchanged: ${diff.unchanged.length} file(s)`));
+  }
+
+  return lines.length > 0 ? lines.join("\n") : "";
+}

package/src/cli/utils/integrations.test.ts

@@ -0,0 +1,251 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import type { FilterDSL } from "../../core/integrations/filter/dsl.ts";
+import type { SerializeDSL } from "../../core/integrations/serialize/dsl.ts";
+import {
+  loadIntegrationDSL,
+  resolveIntegrationOptions,
+} from "./integrations.ts";
+
+describe("loadIntegrationDSL", () => {
+  test("loads from .json file path", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "pgd-integration-"));
+    const jsonPath = path.join(dir, "custom.json");
+    try {
+      await writeFile(
+        jsonPath,
+        JSON.stringify({
+          filter: { "*/schema": "app" },
+        }),
+      );
+      const dsl = await loadIntegrationDSL(jsonPath);
+      expect(dsl).toBeDefined();
+      expect(dsl.filter).toEqual({ "*/schema": "app" });
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("loads core integration by name (supabase)", async () => {
+    const dsl = await loadIntegrationDSL("supabase");
+    expect(dsl).toBeDefined();
+    expect(dsl.filter).toBeDefined();
+    expect(dsl.serialize).toBeDefined();
+  });
+
+  test("fallback to file path when core module not found", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "pgd-integration-"));
+    const filePath = path.join(dir, "custom-dsl");
+    await writeFile(filePath, JSON.stringify({ serialize: [] }));
+    try {
+      const dsl = await loadIntegrationDSL(filePath);
+      expect(dsl).toEqual({ serialize: [] });
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("extends resolution", () => {
+  test('extends: "supabase" → resolves and merges successfully', async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "pgd-extends-"));
+    const jsonPath = path.join(dir, "custom.json");
+    try {
+      await writeFile(
+        jsonPath,
+        JSON.stringify({
+          extends: "supabase",
+          serialize: [
+            {
+              when: { objectType: "table" },
+              options: { skipAuthorization: true },
+            },
+          ],
+        }),
+      );
+      const dsl = await loadIntegrationDSL(jsonPath);
+      expect(dsl).toBeDefined();
+      // Should have the supabase filter merged in
+      expect(dsl.filter).toBeDefined();
+      // Should have both supabase serialize rules and our custom one
+      expect(dsl.serialize).toBeDefined();
+      expect(dsl.serialize?.length).toBeGreaterThan(1);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('extends: "./some-file.json" → throws error about core integrations only', async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "pgd-extends-"));
+    const filePath = path.join(dir, "child.json");
+    const parentPath = path.join(dir, "parent.json");
+    try {
+      await writeFile(
+        parentPath,
+        JSON.stringify({ filter: { "*/schema": "app" } }),
+      );
+      await writeFile(
+        filePath,
+        JSON.stringify({
+          extends: parentPath,
+          filter: { "*/schema": "public" },
+        }),
+      );
+      expect(loadIntegrationDSL(filePath)).rejects.toThrow(
+        /extends only supports core integration names/,
+      );
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('extends: "nonexistent" → throws error about unknown core integration', async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "pgd-extends-"));
+    const jsonPath = path.join(dir, "custom.json");
+    try {
+      await writeFile(jsonPath, JSON.stringify({ extends: "nonexistent" }));
+      expect(loadIntegrationDSL(jsonPath)).rejects.toThrow(
+        /Unknown core integration: "nonexistent"/,
+      );
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("resolveIntegrationOptions", () => {
+  test("no integration, no CLI flags → all undefined", async () => {
+    const result = await resolveIntegrationOptions({});
+    expect(result).toEqual({
+      filter: undefined,
+      serialize: undefined,
+    });
+  });
+
+  test("CLI flags only → passed through unchanged", async () => {
+    const filter: FilterDSL = { "*/schema": "public" };
+    const serialize: SerializeDSL = [
+      { when: { objectType: "schema" }, options: { skipAuthorization: true } },
+    ];
+    const result = await resolveIntegrationOptions({ filter, serialize });
+    expect(result.filter).toEqual(filter);
+    expect(result.serialize).toEqual(serialize);
+    expect(result.emptyCatalog).toBeUndefined();
+  });
+
+  test("integration only → integration values returned", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "pgd-resolve-"));
+    const jsonPath = path.join(dir, "int.json");
+    try {
+      await writeFile(
+        jsonPath,
+        JSON.stringify({
+          filter: { "*/schema": "app" },
+          serialize: [{ when: { objectType: "table" }, options: {} }],
+        }),
+      );
+      const result = await resolveIntegrationOptions({
+        integration: jsonPath,
+      });
+      expect(result.filter).toEqual({ "*/schema": "app" });
+      expect(result.serialize).toEqual([
+        { when: { objectType: "table" }, options: {} },
+      ]);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("both filter + integration filter → AND-combined", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "pgd-resolve-"));
+    const jsonPath = path.join(dir, "int.json");
+    try {
+      await writeFile(
+        jsonPath,
+        JSON.stringify({
+          filter: { "*/schema": "app" },
+        }),
+      );
+      const cliFilter: FilterDSL = { objectType: "table" };
+      const result = await resolveIntegrationOptions({
+        filter: cliFilter,
+        integration: jsonPath,
+      });
+      expect(result.filter).toEqual({
+        and: [{ "*/schema": "app" }, { objectType: "table" }],
+      });
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("both serialize + integration serialize → concatenated (integration first)", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "pgd-resolve-"));
+    const jsonPath = path.join(dir, "int.json");
+    try {
+      const intSerialize: SerializeDSL = [
+        {
+          when: { objectType: "schema" },
+          options: { skipAuthorization: true },
+        },
+      ];
+      const cliSerialize: SerializeDSL = [
+        { when: { objectType: "table" }, options: {} },
+      ];
+      await writeFile(jsonPath, JSON.stringify({ serialize: intSerialize }));
+      const result = await resolveIntegrationOptions({
+        serialize: cliSerialize,
+        integration: jsonPath,
+      });
+      expect(result.serialize).toEqual([...intSerialize, ...cliSerialize]);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("emptyCatalog returned from integration", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "pgd-resolve-"));
+    const jsonPath = path.join(dir, "int.json");
+    try {
+      const emptyCatalog = {
+        version: 1,
+        currentUser: "postgres",
+        aggregates: {},
+        collations: {},
+        compositeTypes: {},
+        domains: {},
+        enums: {},
+        extensions: {},
+        procedures: {},
+        indexes: {},
+        materializedViews: {},
+        subscriptions: {},
+        publications: {},
+        rlsPolicies: {},
+        roles: {},
+        schemas: {},
+        sequences: {},
+        tables: {},
+        triggers: {},
+        eventTriggers: {},
+        rules: {},
+        ranges: {},
+        views: {},
+        foreignDataWrappers: {},
+        servers: {},
+        userMappings: {},
+        foreignTables: {},
+        depends: [],
+      };
+      await writeFile(jsonPath, JSON.stringify({ emptyCatalog }));
+      const result = await resolveIntegrationOptions({
+        integration: jsonPath,
+      });
+      expect(result.emptyCatalog).toEqual(emptyCatalog);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/cli/utils/integrations.ts

@@ -0,0 +1,170 @@
+/**
+ * Utilities for loading integrations from files.
+ */
+
+import { readFile } from "node:fs/promises";
+import type { CatalogSnapshot } from "../../core/catalog.snapshot.ts";
+import type { FilterDSL } from "../../core/integrations/filter/dsl.ts";
+import type { IntegrationDSL } from "../../core/integrations/integration-dsl.ts";
+import { mergeIntegrations } from "../../core/integrations/merge.ts";
+import type { SerializeDSL } from "../../core/integrations/serialize/dsl.ts";
+
+/**
+ * Load a raw integration DSL from a file or core integration (without resolving extends).
+ *
+ * @param nameOrPath - Integration name (e.g., "supabase") or file path (e.g., "./my-integration.json")
+ * @returns The loaded IntegrationDSL (unresolved)
+ */
+async function loadRawIntegrationDSL(
+  nameOrPath: string,
+): Promise<IntegrationDSL> {
+  // If path ends with .json, treat it as a JSON file path directly
+  if (nameOrPath.endsWith(".json")) {
+    const content = await readFile(nameOrPath, "utf-8");
+    return JSON.parse(content) as IntegrationDSL;
+  }
+
+  // Try loading from core integrations (TypeScript) first
+  try {
+    const module = await import(`../../core/integrations/${nameOrPath}.ts`);
+    // Core integrations export using the integration name directly (e.g., "supabase")
+    const integrationName = nameOrPath;
+    if (integrationName in module) {
+      return module[integrationName] as IntegrationDSL;
+    }
+    // If no matching export, fall through to JSON file loading
+  } catch {
+    // Module not found or not a core integration, fall through to JSON file loading
+  }
+
+  // Fallback to treating as JSON file path
+  const content = await readFile(nameOrPath, "utf-8");
+  return JSON.parse(content) as IntegrationDSL;
+}
+
+/**
+ * Load a core integration DSL by name only (no file path fallback).
+ *
+ * Used for resolving `extends` chains, which only support core integration names
+ * (e.g., "supabase"), not file paths.
+ *
+ * @param name - Core integration name (e.g., "supabase")
+ * @returns The loaded IntegrationDSL (unresolved)
+ */
+async function loadCoreIntegrationDSL(name: string): Promise<IntegrationDSL> {
+  try {
+    const module = await import(`../../core/integrations/${name}.ts`);
+    if (name in module) {
+      return module[name] as IntegrationDSL;
+    }
+  } catch {
+    // Module not found
+  }
+  throw new Error(
+    `Unknown core integration: "${name}". extends only supports core integration names (e.g., "supabase").`,
+  );
+}
+
+/**
+ * Load an integration DSL, recursively resolving `extends` chains.
+ *
+ * When an integration has `extends`, the referenced integration(s) are loaded
+ * and merged: filters are AND-combined, serialize rules concatenated (base first),
+ * and emptyCatalog uses the most-specific value.
+ *
+ * Circular extends are detected and rejected with a descriptive error.
+ *
+ * @param nameOrPath - Integration name (e.g., "supabase") or file path
+ * @returns The fully resolved IntegrationDSL
+ */
+export async function loadIntegrationDSL(
+  nameOrPath: string,
+): Promise<IntegrationDSL> {
+  return resolveIntegration(nameOrPath, new Set());
+}
+
+async function resolveIntegration(
+  nameOrPath: string,
+  visited: Set<string>,
+  preloadedRaw?: IntegrationDSL,
+): Promise<IntegrationDSL> {
+  if (visited.has(nameOrPath)) {
+    throw new Error(
+      `Circular extends detected: ${[...visited, nameOrPath].join(" → ")}`,
+    );
+  }
+  visited.add(nameOrPath);
+
+  const raw = preloadedRaw ?? (await loadRawIntegrationDSL(nameOrPath));
+
+  if (!raw.extends) {
+    return raw;
+  }
+
+  // Resolve base integrations (extends only supports core integration names)
+  const extendsArray = Array.isArray(raw.extends) ? raw.extends : [raw.extends];
+
+  const baseIntegrations: IntegrationDSL[] = [];
+  for (const baseName of extendsArray) {
+    const baseRaw = await loadCoreIntegrationDSL(baseName);
+    baseIntegrations.push(
+      await resolveIntegration(baseName, new Set(visited), baseRaw),
+    );
+  }
+
+  // Remove extends from the current integration before merging
+  const { extends: _, ...current } = raw;
+
+  // Merge: bases first (higher priority serialize), then current (most-specific)
+  return mergeIntegrations([...baseIntegrations, current]);
+}
+
+interface ResolvedIntegrationOptions {
+  filter?: FilterDSL;
+  serialize?: SerializeDSL;
+  emptyCatalog?: CatalogSnapshot;
+}
+
+/**
+ * Load an integration (if provided) and merge its filter/serialize with CLI flags.
+ *
+ * - Filters are AND-combined (integration ∧ CLI flag)
+ * - Serialize rules are concatenated (integration first = higher priority)
+ * - emptyCatalog is extracted from the integration
+ */
+export async function resolveIntegrationOptions(options: {
+  filter?: FilterDSL;
+  serialize?: SerializeDSL;
+  integration?: string;
+}): Promise<ResolvedIntegrationOptions> {
+  if (!options.integration) {
+    return {
+      filter: options.filter,
+      serialize: options.serialize,
+    };
+  }
+
+  const integrationDSL = await loadIntegrationDSL(options.integration);
+
+  // AND-combine integration filter with CLI --filter
+  let filter: FilterDSL | undefined;
+  if (integrationDSL.filter && options.filter) {
+    filter = { and: [integrationDSL.filter, options.filter] };
+  } else {
+    filter = options.filter ?? integrationDSL.filter;
+  }
+
+  // Concatenate serialize rules (integration first = higher priority)
+  let serialize: SerializeDSL | undefined;
+  if (integrationDSL.serialize && options.serialize) {
+    serialize = [...integrationDSL.serialize, ...options.serialize];
+  } else {
+    serialize = options.serialize ?? integrationDSL.serialize;
+  }
+
+  return {
+    filter,
+    serialize,
+    emptyCatalog: integrationDSL.emptyCatalog,
+  };
+}