@supabase/pg-delta 1.0.0-alpha.10 → 1.0.0-alpha.12

package/src/cli/commands/plan.ts

@@ -4,14 +4,13 @@
 
 import { writeFile } from "node:fs/promises";
 import { buildCommand, type CommandContext } from "@stricli/core";
+import { deserializeCatalog } from "../../core/catalog.snapshot.ts";
 import type { FilterDSL } from "../../core/integrations/filter/dsl.ts";
-import type { ChangeFilter } from "../../core/integrations/filter/filter.types.ts";
 import type { SerializeDSL } from "../../core/integrations/serialize/dsl.ts";
-import type { ChangeSerializer } from "../../core/integrations/serialize/serialize.types.ts";
 import { createPlan } from "../../core/plan/index.ts";
 import type { SqlFormatOptions } from "../../core/plan/sql-format.ts";
 import { setCommandExitCode } from "../exit-code.ts";
-import { loadIntegrationDSL } from "../utils/integrations.ts";
+import { resolveIntegrationOptions } from "../utils/integrations.ts";
 import { isPostgresUrl, loadCatalogFromFile } from "../utils/resolve-input.ts";
 import { formatPlanForDisplay } from "../utils.ts";
 
@@ -138,27 +137,22 @@ json/sql outputs are available for artifacts or piping.
       "sql-format-options"?: SqlFormatOptions;
     },
   ) {
-    let filterOption: FilterDSL | ChangeFilter | undefined = flags.filter;
-    let serializeOption: SerializeDSL | ChangeSerializer | undefined =
-      flags.serialize;
-    let integrationEmptyCatalog:
-      | import("../../core/catalog.snapshot.ts").CatalogSnapshot
-      | undefined;
-    if (flags.integration) {
-      const integrationDSL = await loadIntegrationDSL(flags.integration);
-      filterOption = filterOption ?? integrationDSL.filter;
-      serializeOption = serializeOption ?? integrationDSL.serialize;
-      integrationEmptyCatalog = integrationDSL.emptyCatalog;
-    }
+    const {
+      filter,
+      serialize,
+      emptyCatalog: integrationEmptyCatalog,
+    } = await resolveIntegrationOptions({
+      filter: flags.filter,
+      serialize: flags.serialize,
+      integration: flags.integration,
+    });
 
     const resolvedSource = flags.source
       ? isPostgresUrl(flags.source)
         ? flags.source
         : await loadCatalogFromFile(flags.source)
       : integrationEmptyCatalog
-        ? (await import("../../core/catalog.snapshot.ts")).deserializeCatalog(
-            integrationEmptyCatalog,
-          )
+        ? deserializeCatalog(integrationEmptyCatalog)
         : null;
 
     const resolvedTarget = isPostgresUrl(flags.target)
@@ -167,8 +161,8 @@ json/sql outputs are available for artifacts or piping.
 
     const planResult = await createPlan(resolvedSource, resolvedTarget, {
       role: flags.role,
-      filter: filterOption,
-      serialize: serializeOption,
+      filter,
+      serialize,
     });
     if (!planResult) {
       this.process.stdout.write("No changes detected.\n");

package/src/cli/commands/sync.ts

@@ -4,12 +4,10 @@
 
 import { buildCommand, type CommandContext } from "@stricli/core";
 import type { FilterDSL } from "../../core/integrations/filter/dsl.ts";
-import type { ChangeFilter } from "../../core/integrations/filter/filter.types.ts";
 import type { SerializeDSL } from "../../core/integrations/serialize/dsl.ts";
-import type { ChangeSerializer } from "../../core/integrations/serialize/serialize.types.ts";
 import { applyPlan } from "../../core/plan/apply.ts";
 import { createPlan } from "../../core/plan/index.ts";
-import { loadIntegrationDSL } from "../utils/integrations.ts";
+import { resolveIntegrationOptions } from "../utils/integrations.ts";
 import {
   formatPlanForDisplay,
   handleApplyResult,
@@ -120,22 +118,17 @@ Exit codes:
       integration?: string;
     },
   ) {
-    // Load integration if provided and extract filter/serialize DSL
-    let filterOption: FilterDSL | ChangeFilter | undefined = flags.filter;
-    let serializeOption: SerializeDSL | ChangeSerializer | undefined =
-      flags.serialize;
-    if (flags.integration) {
-      const integrationDSL = await loadIntegrationDSL(flags.integration);
-      // Use integration DSL if explicit flags not provided
-      filterOption = filterOption ?? integrationDSL.filter;
-      serializeOption = serializeOption ?? integrationDSL.serialize;
-    }
+    const { filter, serialize } = await resolveIntegrationOptions({
+      filter: flags.filter,
+      serialize: flags.serialize,
+      integration: flags.integration,
+    });
 
     // 1. Create the plan
     const planResult = await createPlan(flags.source, flags.target, {
       role: flags.role,
-      filter: filterOption,
-      serialize: serializeOption,
+      filter,
+      serialize,
     });
     if (!planResult) {
       this.process.stdout.write("No changes detected.\n");

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

@@ -2,7 +2,12 @@ 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 { loadIntegrationDSL } from "./integrations.ts";
+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 () => {
@@ -12,12 +17,12 @@ describe("loadIntegrationDSL", () => {
       await writeFile(
         jsonPath,
         JSON.stringify({
-          filter: { schema: "app" },
+          filter: { "*/schema": "app" },
         }),
       );
       const dsl = await loadIntegrationDSL(jsonPath);
       expect(dsl).toBeDefined();
-      expect(dsl.filter).toEqual({ schema: "app" });
+      expect(dsl.filter).toEqual({ "*/schema": "app" });
     } finally {
       await rm(dir, { recursive: true, force: true });
     }
@@ -42,3 +47,205 @@ describe("loadIntegrationDSL", () => {
     }
   });
 });
+
+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

@@ -3,18 +3,19 @@
  */
 
 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 an integration DSL from a file or core integration.
- * If the path ends with .json, treats it as a JSON file path directly.
- * Otherwise, tries to load from core integrations (TypeScript) first,
- * then falls back to treating as a JSON file path.
+ * 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
+ * @returns The loaded IntegrationDSL (unresolved)
  */
-export async function loadIntegrationDSL(
+async function loadRawIntegrationDSL(
   nameOrPath: string,
 ): Promise<IntegrationDSL> {
   // If path ends with .json, treat it as a JSON file path directly
@@ -40,3 +41,130 @@ export async function loadIntegrationDSL(
   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,
+  };
+}

package/src/core/catalog.snapshot.test.ts

@@ -452,7 +452,11 @@ describe("catalog snapshot serde", () => {
 
     // Filter out auth schema (no cascade): procedure is excluded but policy stays
     const resultNoCascade = await createPlan(null, target, {
-      filter: { not: { schema: ["auth"] } },
+      filter: {
+        not: {
+          or: [{ "*/schema": ["auth"] }, { "schema/name": ["auth"] }],
+        },
+      },
     });
     expect(resultNoCascade).not.toBeNull();
     if (resultNoCascade) {
@@ -464,7 +468,12 @@ describe("catalog snapshot serde", () => {
 
     // Filter out auth schema with cascade: true: policy is also excluded (depends on auth.uid())
     const resultCascade = await createPlan(null, target, {
-      filter: { not: { schema: ["auth"] }, cascade: true },
+      filter: {
+        not: {
+          or: [{ "*/schema": ["auth"] }, { "schema/name": ["auth"] }],
+        },
+        cascade: true,
+      },
     });
     expect(resultCascade).not.toBeNull();
     if (resultCascade) {

package/src/core/change-utils.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+import type { Change } from "./change.types.ts";
+import { getSchema } from "./change-utils.ts";
+
+describe("getSchema", () => {
+  test("returns schema for table", () => {
+    const change = {
+      objectType: "table",
+      table: { schema: "public" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBe("public");
+  });
+
+  test("returns schema for view", () => {
+    const change = {
+      objectType: "view",
+      view: { schema: "app" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBe("app");
+  });
+
+  test("returns schema for enum", () => {
+    const change = {
+      objectType: "enum",
+      enum: { schema: "types" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBe("types");
+  });
+
+  test("returns schema.name for schema type", () => {
+    const change = {
+      objectType: "schema",
+      schema: { name: "auth" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBe("auth");
+  });
+
+  test("returns null for role", () => {
+    const change = {
+      objectType: "role",
+      role: { name: "admin" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBeNull();
+  });
+
+  test("returns null for publication", () => {
+    const change = {
+      objectType: "publication",
+      publication: { name: "pub1" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBeNull();
+  });
+
+  test("returns null for language", () => {
+    const change = {
+      objectType: "language",
+      language: { name: "plpgsql" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBeNull();
+  });
+});

package/src/core/change-utils.ts

@@ -0,0 +1,73 @@
+import type { Change } from "./change.types.ts";
+
+/**
+ * Extract the schema name from a Change using the model sub-object.
+ *
+ * This is a convenience function used by the filter DSL (for schema
+ * normalization) and the sort module. It reads the `schema` (or `name`
+ * for schema objectType) from the model sub-object.
+ */
+export function getSchema(change: Change): string | null {
+  if (change.scope === "default_privilege") {
+    return change.inSchema;
+  }
+  switch (change.objectType) {
+    case "aggregate":
+      return change.aggregate.schema;
+    case "collation":
+      return change.collation.schema;
+    case "composite_type":
+      return change.compositeType.schema;
+    case "domain":
+      return change.domain.schema;
+    case "enum":
+      return change.enum.schema;
+    case "event_trigger":
+      return change.eventTrigger.function_schema;
+    case "extension":
+      return change.extension.schema;
+    case "index":
+      return change.index.schema;
+    case "language":
+      return null;
+    case "materialized_view":
+      return change.materializedView.schema;
+    case "procedure":
+      return change.procedure.schema;
+    case "publication":
+      return null;
+    case "range":
+      return change.range.schema;
+    case "rls_policy":
+      return change.policy.schema;
+    case "role":
+      return null;
+    case "rule":
+      return change.rule.schema;
+    case "schema":
+      return change.schema.name;
+    case "sequence":
+      return change.sequence.schema;
+    case "subscription":
+      return null;
+    case "table":
+      return change.table.schema;
+    case "trigger":
+      return change.trigger.schema;
+    case "view":
+      return change.view.schema;
+    case "foreign_data_wrapper":
+      return null;
+    case "server":
+      return null;
+    case "user_mapping":
+      return null;
+    case "foreign_table":
+      return change.foreignTable.schema;
+    default: {
+      // exhaustiveness check
+      const _exhaustive: never = change;
+      return _exhaustive;
+    }
+  }
+}