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

package/src/core/plan/sql-format/protect.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it } from "bun:test";
+import { DEFAULT_OPTIONS } from "./constants.ts";
+import { protectSegments, restorePlaceholders } from "./protect.ts";
+
+describe("protectSegments", () => {
+  it("protects function body after AS", () => {
+    const sql = "CREATE FUNCTION foo() RETURNS void AS $$ BEGIN NULL; END; $$";
+    const result = protectSegments(sql, DEFAULT_OPTIONS);
+    expect(result.text).toContain("__PGDELTA_PLACEHOLDER_");
+    expect(result.text).not.toContain("BEGIN NULL");
+    expect(result.placeholders.size).toBeGreaterThan(0);
+    expect(result.skipCasing).toBe(false);
+  });
+
+  it("protects view body after AS", () => {
+    const sql = "CREATE VIEW v AS SELECT 1";
+    const result = protectSegments(sql, DEFAULT_OPTIONS);
+    expect(result.text).toContain("__PGDELTA_PLACEHOLDER_");
+    expect(result.text).not.toContain("SELECT 1");
+  });
+
+  it("protects standalone dollar-quoted blocks", () => {
+    const sql = "SELECT $$hello world$$";
+    const result = protectSegments(sql, {
+      ...DEFAULT_OPTIONS,
+      preserveRoutineBodies: false,
+      preserveViewBodies: false,
+      preserveRuleBodies: false,
+    });
+    expect(result.text).toContain("__PGDELTA_PLACEHOLDER_");
+    expect(result.text).not.toContain("hello world");
+  });
+
+  it("protects COMMENT literal payloads and restores multiline text exactly", () => {
+    const sql = `COMMENT ON FUNCTION auth.can_project(bigint,bigint,text,auth.action,json,uuid) IS '
+Enhanced wrapper method for the primary auth.can() function. Utilize this wrapper to specifically check for project-related permissions.
+';`;
+    const result = protectSegments(sql, DEFAULT_OPTIONS);
+    expect(result.text).toContain("__PGDELTA_PLACEHOLDER_");
+    expect(result.text).not.toContain(
+      "Enhanced wrapper method for the primary auth.can() function.",
+    );
+    const restored = restorePlaceholders(result.text, result.placeholders);
+    expect(restored).toBe(sql);
+  });
+
+  it("preserves escaped quotes inside COMMENT literal payloads", () => {
+    const sql =
+      "COMMENT ON FUNCTION public.fn() IS E'it''s an ''exact'' payload';";
+    const result = protectSegments(sql, DEFAULT_OPTIONS);
+    expect(result.text).toContain("__PGDELTA_PLACEHOLDER_");
+    const restored = restorePlaceholders(result.text, result.placeholders);
+    expect(restored).toBe(sql);
+  });
+
+  it("preserves backslash-escaped quotes in E strings", () => {
+    const sql = "COMMENT ON FUNCTION public.fn() IS E'keep \\'quote\\' exact';";
+    const result = protectSegments(sql, DEFAULT_OPTIONS);
+    expect(result.text).toContain("__PGDELTA_PLACEHOLDER_");
+    const restored = restorePlaceholders(result.text, result.placeholders);
+    expect(restored).toBe(sql);
+    expect(result.skipCasing).toBe(false);
+  });
+
+  it("preserves U& strings using standard '' quoting (no backslash escaping)", () => {
+    const sql = "COMMENT ON FUNCTION public.fn() IS U&'keep ''quote'' exact';";
+    const result = protectSegments(sql, DEFAULT_OPTIONS);
+    expect(result.text).toContain("__PGDELTA_PLACEHOLDER_");
+    const restored = restorePlaceholders(result.text, result.placeholders);
+    expect(restored).toBe(sql);
+    expect(result.skipCasing).toBe(false);
+  });
+
+  it("flags malformed escape-string comments as unsafe for post-processing", () => {
+    const sql = "COMMENT ON FUNCTION public.fn() IS E'unterminated \\'";
+    const result = protectSegments(sql, DEFAULT_OPTIONS);
+    expect(result.text).toBe(sql);
+    expect(result.placeholders.size).toBe(0);
+    expect(result.skipCasing).toBe(true);
+  });
+
+  it("flags unterminated dollar-quoted content as unsafe for post-processing", () => {
+    const sql = "CREATE FUNCTION public.fn() RETURNS text AS $fn$select 1";
+    const result = protectSegments(sql, {
+      ...DEFAULT_OPTIONS,
+      preserveRoutineBodies: false,
+      preserveViewBodies: false,
+      preserveRuleBodies: false,
+    });
+    expect(result.skipCasing).toBe(true);
+  });
+
+  it("does not protect COMMENT ... IS NULL", () => {
+    const sql = "COMMENT ON FUNCTION public.fn() IS NULL;";
+    const result = protectSegments(sql, DEFAULT_OPTIONS);
+    expect(result.placeholders.size).toBe(0);
+    expect(result.text).toBe(sql);
+  });
+});
+
+describe("restorePlaceholders", () => {
+  it("restores placeholders to original values", () => {
+    const placeholders = new Map<string, string>();
+    placeholders.set("__PGDELTA_PLACEHOLDER_0__", "AS $$ body $$");
+    const text = "CREATE FUNCTION foo() __PGDELTA_PLACEHOLDER_0__";
+    const restored = restorePlaceholders(text, placeholders);
+    expect(restored).toMatchInlineSnapshot(
+      `"CREATE FUNCTION foo() AS $$ body $$"`,
+    );
+  });
+
+  it("correctly handles $ characters in restored values", () => {
+    const placeholders = new Map<string, string>();
+    placeholders.set("__PGDELTA_PLACEHOLDER_0__", "$$price$$");
+    const text = "SELECT __PGDELTA_PLACEHOLDER_0__";
+    const restored = restorePlaceholders(text, placeholders);
+    expect(restored).toMatchInlineSnapshot(`"SELECT $$price$$"`);
+  });
+
+  it("round-trips protect → restore to produce original text", () => {
+    const sql =
+      "CREATE FUNCTION add(a int, b int) RETURNS int AS $$ BEGIN RETURN a + b; END; $$ LANGUAGE plpgsql";
+    const result = protectSegments(sql, DEFAULT_OPTIONS);
+    const restored = restorePlaceholders(result.text, result.placeholders);
+    expect(restored).toBe(sql);
+  });
+});

package/src/core/plan/sql-format/protect.ts

@@ -0,0 +1,337 @@
+import { isEscapeStringQuoteStart, readDollarTag } from "./sql-scanner.ts";
+import { scanTokens } from "./tokenizer.ts";
+import type { NormalizedOptions, ProtectedSegments, Token } from "./types.ts";
+
+type ProtectState = {
+  placeholders: Map<string, string>;
+  noWrapPlaceholders: Set<string>;
+  counter: number;
+  skipCasing: boolean;
+};
+
+export function protectSegments(
+  statement: string,
+  options: NormalizedOptions,
+): ProtectedSegments {
+  let text = statement;
+  const placeholders = new Map<string, string>();
+  const noWrapPlaceholders = new Set<string>();
+  const state: ProtectState = {
+    placeholders,
+    noWrapPlaceholders,
+    counter: 0,
+    skipCasing: false,
+  };
+
+  if (options.preserveRoutineBodies) {
+    ({ text } = protectTailAfterAs(text, ["FUNCTION", "PROCEDURE"], state));
+  }
+
+  if (options.preserveViewBodies) {
+    ({ text } = protectTailAfterAs(text, ["VIEW"], state));
+  }
+
+  if (options.preserveRuleBodies) {
+    ({ text } = protectTailAfterAs(text, ["RULE"], state));
+  }
+
+  ({ text } = protectCommentLiteral(text, state));
+
+  ({ text } = protectDollarQuotes(text, state));
+
+  return {
+    text,
+    placeholders,
+    noWrapPlaceholders,
+    skipCasing: state.skipCasing,
+  };
+}
+
+function protectTailAfterAs(
+  text: string,
+  objectKeywords: string[],
+  state: ProtectState,
+): { text: string } {
+  const tokens = scanTokens(text);
+  if (tokens.length === 0) return { text };
+
+  for (let i = 0; i < tokens.length; i += 1) {
+    if (tokens[i].upper !== "CREATE") continue;
+
+    let cursor = i + 1;
+    if (
+      tokens[cursor]?.upper === "OR" &&
+      tokens[cursor + 1]?.upper === "REPLACE"
+    ) {
+      cursor += 2;
+    }
+
+    // Handle compound keywords: MATERIALIZED VIEW, FOREIGN TABLE, EVENT TRIGGER
+    if (
+      tokens[cursor]?.upper === "MATERIALIZED" ||
+      tokens[cursor]?.upper === "FOREIGN" ||
+      tokens[cursor]?.upper === "EVENT"
+    ) {
+      cursor += 1;
+    }
+
+    const objectToken = tokens[cursor];
+    if (!objectToken || !objectKeywords.includes(objectToken.upper)) {
+      continue;
+    }
+
+    const asToken = tokens
+      .slice(cursor + 1)
+      .find(
+        (token) =>
+          token.upper === "AS" &&
+          token.depth === 0 &&
+          isKeywordBoundary(text, token),
+      );
+
+    if (!asToken) continue;
+
+    const placeholder = makePlaceholder(state.counter);
+    state.counter += 1;
+    state.placeholders.set(placeholder, text.slice(asToken.start));
+    state.noWrapPlaceholders.add(placeholder);
+    const updated = `${text.slice(0, asToken.start)}${placeholder}`;
+    return { text: updated };
+  }
+
+  return { text };
+}
+
+function protectCommentLiteral(
+  text: string,
+  state: ProtectState,
+): { text: string } {
+  const tokens = scanTokens(text);
+  if (tokens.length < 4) return { text };
+  if (tokens[0].upper !== "COMMENT" || tokens[1].upper !== "ON") {
+    return { text };
+  }
+
+  const isToken = tokens
+    .slice(2)
+    .find((token) => token.depth === 0 && token.upper === "IS");
+  if (!isToken) return { text };
+
+  let literalStart = isToken.end;
+  while (literalStart < text.length && /\s/.test(text[literalStart])) {
+    literalStart += 1;
+  }
+  if (literalStart >= text.length) return { text };
+
+  if (/^NULL\b/i.test(text.slice(literalStart))) {
+    return { text };
+  }
+
+  const first = text[literalStart];
+  let quoteStart = -1;
+  let isEscapeString = false;
+  if (first === "'") {
+    quoteStart = literalStart;
+  } else if (
+    (first === "E" || first === "e") &&
+    text[literalStart + 1] === "'"
+  ) {
+    quoteStart = literalStart + 1;
+    isEscapeString = true;
+  } else if (
+    (first === "U" || first === "u") &&
+    text[literalStart + 1] === "&" &&
+    text[literalStart + 2] === "'"
+  ) {
+    quoteStart = literalStart + 2;
+  } else {
+    return { text };
+  }
+
+  let literalEnd = -1;
+  let cursor = quoteStart + 1;
+  while (cursor < text.length) {
+    if (isEscapeString && text[cursor] === "\\") {
+      const hasEscapedChar = cursor + 1 < text.length;
+      cursor += hasEscapedChar ? 2 : 1;
+      continue;
+    }
+    if (text[cursor] === "'") {
+      if (text[cursor + 1] === "'") {
+        cursor += 2;
+        continue;
+      }
+      literalEnd = cursor + 1;
+      break;
+    }
+    cursor += 1;
+  }
+  if (literalEnd === -1) {
+    state.skipCasing = true;
+    return { text };
+  }
+
+  const placeholder = makePlaceholder(state.counter);
+  state.counter += 1;
+  state.placeholders.set(placeholder, text.slice(literalStart, literalEnd));
+  const updated = `${text.slice(0, literalStart)}${placeholder}${text.slice(literalEnd)}`;
+  return { text: updated };
+}
+
+function protectDollarQuotes(
+  text: string,
+  state: ProtectState,
+): { text: string } {
+  let output = "";
+  let inSingleQuote = false;
+  let singleQuoteEscapeMode = false;
+  let inDoubleQuote = false;
+  let inLineComment = false;
+  let inBlockComment = false;
+  let i = 0;
+
+  while (i < text.length) {
+    const char = text[i];
+    const next = text[i + 1];
+
+    if (inLineComment) {
+      output += char;
+      if (char === "\n") {
+        inLineComment = false;
+      }
+      i += 1;
+      continue;
+    }
+
+    if (inBlockComment) {
+      if (char === "*" && next === "/") {
+        output += "*/";
+        inBlockComment = false;
+        i += 2;
+        continue;
+      }
+      output += char;
+      i += 1;
+      continue;
+    }
+
+    if (inSingleQuote) {
+      if (singleQuoteEscapeMode && char === "\\") {
+        if (next !== undefined) {
+          output += `\\${next}`;
+          i += 2;
+        } else {
+          output += char;
+          i += 1;
+        }
+        continue;
+      }
+      output += char;
+      if (char === "'") {
+        if (next === "'") {
+          output += next;
+          i += 2;
+          continue;
+        }
+        inSingleQuote = false;
+        singleQuoteEscapeMode = false;
+      }
+      i += 1;
+      continue;
+    }
+
+    if (inDoubleQuote) {
+      output += char;
+      if (char === '"') {
+        if (next === '"') {
+          output += next;
+          i += 2;
+          continue;
+        }
+        inDoubleQuote = false;
+      }
+      i += 1;
+      continue;
+    }
+
+    if (char === "-" && next === "-") {
+      output += "--";
+      inLineComment = true;
+      i += 2;
+      continue;
+    }
+
+    if (char === "/" && next === "*") {
+      output += "/*";
+      inBlockComment = true;
+      i += 2;
+      continue;
+    }
+
+    if (char === "'") {
+      inSingleQuote = true;
+      singleQuoteEscapeMode = isEscapeStringQuoteStart(text, i);
+      output += char;
+      i += 1;
+      continue;
+    }
+
+    if (char === '"') {
+      inDoubleQuote = true;
+      output += char;
+      i += 1;
+      continue;
+    }
+
+    if (char === "$") {
+      const tag = readDollarTag(text, i);
+      if (tag) {
+        const start = i;
+        const end = text.indexOf(tag, i + tag.length);
+        if (end !== -1) {
+          const placeholder = makePlaceholder(state.counter);
+          state.counter += 1;
+          state.placeholders.set(
+            placeholder,
+            text.slice(start, end + tag.length),
+          );
+          output += placeholder;
+          i = end + tag.length;
+          continue;
+        }
+        state.skipCasing = true;
+        output += char;
+        i += 1;
+        continue;
+      }
+    }
+
+    output += char;
+    i += 1;
+  }
+
+  return { text: output };
+}
+
+export function restorePlaceholders(
+  text: string,
+  placeholders: Map<string, string>,
+): string {
+  let output = text;
+  for (const [placeholder, value] of placeholders.entries()) {
+    output = output.replaceAll(placeholder, () => value);
+  }
+  return output;
+}
+
+function isKeywordBoundary(statement: string, token: Token): boolean {
+  const before = statement[token.start - 1];
+  const after = statement[token.end];
+  const isBoundary = (value: string | undefined) =>
+    value === undefined || !/[A-Za-z0-9_$.]/.test(value);
+  return isBoundary(before) && isBoundary(after);
+}
+
+function makePlaceholder(index: number): string {
+  return `__PGDELTA_PLACEHOLDER_${index}__`;
+}

package/src/core/plan/sql-format/sql-scanner.test.ts

@@ -0,0 +1,240 @@
+import { describe, expect, it } from "bun:test";
+import {
+  isEscapeStringQuoteStart,
+  isWordChar,
+  readDollarTag,
+  walkSql,
+} from "./sql-scanner.ts";
+
+describe("isWordChar", () => {
+  it("returns true for letters, digits, and underscore", () => {
+    for (const ch of ["a", "z", "A", "Z", "0", "9", "_"]) {
+      expect(isWordChar(ch)).toBe(true);
+    }
+  });
+
+  it("returns false for spaces, parens, and symbols", () => {
+    for (const ch of [" ", "(", ")", ",", ";", ".", "-", "+"]) {
+      expect(isWordChar(ch)).toBe(false);
+    }
+  });
+});
+
+describe("readDollarTag", () => {
+  it("reads $$ tag", () => {
+    expect(readDollarTag("$$body$$", 0)).toMatchInlineSnapshot(`"$$"`);
+  });
+
+  it("reads named tag like $fn$", () => {
+    expect(readDollarTag("$fn$body$fn$", 0)).toMatchInlineSnapshot(`"$fn$"`);
+  });
+
+  it("reads $body$ tag", () => {
+    expect(readDollarTag("$body$content$body$", 0)).toMatchInlineSnapshot(
+      `"$body$"`,
+    );
+  });
+
+  it("returns null for non-tag like $1+2", () => {
+    expect(readDollarTag("$1+2", 0)).toBeNull();
+  });
+
+  it("returns null when closing $ is missing", () => {
+    expect(readDollarTag("$abc", 0)).toBeNull();
+  });
+
+  it("returns null when char at start is not $", () => {
+    expect(readDollarTag("abc", 0)).toBeNull();
+  });
+});
+
+describe("isEscapeStringQuoteStart", () => {
+  it("detects E escape-string prefix", () => {
+    expect(isEscapeStringQuoteStart("E'abc'", 1)).toBe(true);
+    expect(isEscapeStringQuoteStart("e'abc'", 1)).toBe(true);
+  });
+
+  it("does not treat U& strings as escape strings", () => {
+    expect(isEscapeStringQuoteStart("U&'abc'", 2)).toBe(false);
+    expect(isEscapeStringQuoteStart("u&'abc'", 2)).toBe(false);
+  });
+
+  it("does not treat plain strings as escape strings", () => {
+    expect(isEscapeStringQuoteStart("'abc'", 0)).toBe(false);
+    expect(isEscapeStringQuoteStart("fooe'abc'", 4)).toBe(false);
+  });
+});
+
+describe("walkSql", () => {
+  it("skips single-quoted strings", () => {
+    const chars: string[] = [];
+    walkSql("a 'hello' b", (_, char) => {
+      chars.push(char);
+      return true;
+    });
+    expect(chars.join("")).toMatchInlineSnapshot(`"a  b"`);
+  });
+
+  it("skips single-quoted strings with '' escapes", () => {
+    const chars: string[] = [];
+    walkSql("a 'it''s' b", (_, char) => {
+      chars.push(char);
+      return true;
+    });
+    expect(chars.join("")).toMatchInlineSnapshot(`"a  b"`);
+  });
+
+  it("skips E strings with backslash-escaped quotes", () => {
+    const chars: string[] = [];
+    walkSql("a E'it\\'s still quoted' b", (_, char) => {
+      chars.push(char);
+      return true;
+    });
+    expect(chars.join("")).toMatchInlineSnapshot(`"a E b"`);
+  });
+
+  it("skips U& strings using standard '' quoting (no backslash escaping)", () => {
+    const chars: string[] = [];
+    walkSql("a U&'it''s ok' b", (_, char) => {
+      chars.push(char);
+      return true;
+    });
+    expect(chars.join("")).toMatchInlineSnapshot(`"a U& b"`);
+  });
+
+  it("skips double-quoted identifiers", () => {
+    const chars: string[] = [];
+    walkSql('a "col" b', (_, char) => {
+      chars.push(char);
+      return true;
+    });
+    expect(chars.join("")).toMatchInlineSnapshot(`"a  b"`);
+  });
+
+  it('skips double-quoted identifiers with "" escapes', () => {
+    const chars: string[] = [];
+    walkSql('a "col""name" b', (_, char) => {
+      chars.push(char);
+      return true;
+    });
+    expect(chars.join("")).toMatchInlineSnapshot(`"a  b"`);
+  });
+
+  it("skips line comments", () => {
+    const chars: string[] = [];
+    walkSql("a -- comment\nb", (_, char) => {
+      chars.push(char);
+      return true;
+    });
+    expect(chars.join("")).toMatchInlineSnapshot(`"a b"`);
+  });
+
+  it("skips block comments", () => {
+    const chars: string[] = [];
+    walkSql("a /* block */ b", (_, char) => {
+      chars.push(char);
+      return true;
+    });
+    expect(chars.join("")).toMatchInlineSnapshot(`"a  b"`);
+  });
+
+  it("skips dollar-quoted blocks", () => {
+    const chars: string[] = [];
+    walkSql("a $$body$$ b", (_, char) => {
+      chars.push(char);
+      return true;
+    });
+    expect(chars.join("")).toMatchInlineSnapshot(`"a  b"`);
+  });
+
+  it("tracks parenthesis depth correctly", () => {
+    const depths: [string, number][] = [];
+    walkSql(
+      "a(b(c)d)e",
+      (_, char, depth) => {
+        depths.push([char, depth]);
+        return true;
+      },
+      { trackDepth: true },
+    );
+    expect(depths).toMatchInlineSnapshot(`
+      [
+        [
+          "a",
+          0,
+        ],
+        [
+          "(",
+          0,
+        ],
+        [
+          "b",
+          1,
+        ],
+        [
+          "(",
+          1,
+        ],
+        [
+          "c",
+          2,
+        ],
+        [
+          ")",
+          1,
+        ],
+        [
+          "d",
+          1,
+        ],
+        [
+          ")",
+          0,
+        ],
+        [
+          "e",
+          0,
+        ],
+      ]
+    `);
+  });
+
+  it("respects startIndex option", () => {
+    const chars: string[] = [];
+    walkSql(
+      "abcde",
+      (_, char) => {
+        chars.push(char);
+        return true;
+      },
+      { startIndex: 2 },
+    );
+    expect(chars.join("")).toMatchInlineSnapshot(`"cde"`);
+  });
+
+  it("calls onSkipped for skipped content", () => {
+    const skipped: string[] = [];
+    walkSql("a 'x' b", () => true, {
+      onSkipped: (chunk) => {
+        skipped.push(chunk);
+      },
+    });
+    expect(skipped).toMatchInlineSnapshot(`
+      [
+        "'",
+        "x",
+        "'",
+      ]
+    `);
+  });
+
+  it("stops early when callback returns false", () => {
+    const chars: string[] = [];
+    walkSql("abcde", (_, char) => {
+      chars.push(char);
+      if (char === "c") return false;
+      return true;
+    });
+    expect(chars.join("")).toMatchInlineSnapshot(`"abc"`);
+  });
+});