@supabase/pg-delta 1.0.0-alpha.3 → 1.0.0-alpha.4

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

@@ -0,0 +1,252 @@
+/**
+ * Unified SQL scanner that handles quote/comment/dollar-tag state machines.
+ */
+
+/**
+ * Callback invoked for each character that is NOT inside a quoted string,
+ * comment, or dollar-quoted block.
+ *
+ * @param index - position in the text
+ * @param char - the character at that position
+ * @param depth - current parenthesis depth (only tracked when `trackDepth` is true, else always 0)
+ * @returns `false` to stop walking early; `true` to continue
+ */
+type WalkCallback = (index: number, char: string, depth: number) => boolean;
+
+type WalkSqlOptions = {
+  /** Track parenthesis depth and pass it to the callback. Default: false */
+  trackDepth?: boolean;
+  /** Start scanning from this index. Default: 0 */
+  startIndex?: number;
+  /**
+   * Called for characters/sequences inside quoted strings, comments, and
+   * dollar-quoted blocks (i.e., characters the walker "skips" over).
+   * Also called for quote/comment opener sequences (e.g., `--`, `/*`, `'`, `"`).
+   *
+   * NOT called for top-level characters — those go only to `onTopLevel`.
+   *
+   * For multi-char sequences (block comment open/close, dollar tags, escaped quotes),
+   * called once with the full sequence.
+   */
+  onSkipped?: (chunk: string) => void;
+};
+
+/**
+ * Fast character-code check: A-Z, a-z, 0-9, _
+ */
+export function isWordChar(char: string): boolean {
+  const c = char.charCodeAt(0);
+  return (
+    (c >= 65 && c <= 90) ||
+    (c >= 97 && c <= 122) ||
+    (c >= 48 && c <= 57) ||
+    c === 95
+  );
+}
+
+/**
+ * Return true when the single quote at `quoteIndex` starts a PostgreSQL
+ * escape string literal (`E'...'`). Only E-strings use backslash escaping;
+ * U&-strings use standard '' quoting (backslash is for Unicode escapes only).
+ */
+export function isEscapeStringQuoteStart(
+  text: string,
+  quoteIndex: number,
+): boolean {
+  if (text[quoteIndex] !== "'") return false;
+
+  const prev = text[quoteIndex - 1];
+  const prev2 = text[quoteIndex - 2];
+
+  if (
+    (prev === "E" || prev === "e") &&
+    (prev2 === undefined || !isWordChar(prev2))
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Read a dollar-quote tag starting at `start` (which must be `$`).
+ * Returns the full tag including both `$` delimiters, e.g. `$$` or `$fn$`.
+ */
+export function readDollarTag(text: string, start: number): string | null {
+  if (text[start] !== "$") return null;
+  let i = start + 1;
+  while (i < text.length && isWordChar(text[i])) {
+    i += 1;
+  }
+  if (text[i] === "$") {
+    return text.slice(start, i + 1);
+  }
+  return null;
+}
+
+/**
+ * Walk through SQL text, calling `onTopLevel` for each character that is
+ * outside of quotes, comments, and dollar-quoted blocks.
+ *
+ * The walker handles:
+ * - Single-quoted strings (with '' escaping)
+ * - Double-quoted identifiers (with "" escaping)
+ * - Line comments (--)
+ * - Block comments (/* ... * /)
+ * - Dollar-quoted strings ($tag$...$tag$)
+ * - Parenthesis depth tracking (optional)
+ */
+export function walkSql(
+  text: string,
+  onTopLevel: WalkCallback,
+  options?: WalkSqlOptions,
+): void {
+  const trackDepth = options?.trackDepth ?? false;
+  const startIndex = options?.startIndex ?? 0;
+  const onSkipped = options?.onSkipped;
+
+  let inSingleQuote = false;
+  let singleQuoteEscapeMode = false;
+  let inDoubleQuote = false;
+  let inLineComment = false;
+  let inBlockComment = false;
+  let dollarTag: string | null = null;
+  let depth = 0;
+
+  let i = startIndex;
+  while (i < text.length) {
+    const char = text[i];
+    const next = text[i + 1];
+
+    // --- Inside line comment ---
+    if (inLineComment) {
+      onSkipped?.(char);
+      if (char === "\n") inLineComment = false;
+      i += 1;
+      continue;
+    }
+
+    // --- Inside block comment ---
+    if (inBlockComment) {
+      if (char === "*" && next === "/") {
+        onSkipped?.("*/");
+        inBlockComment = false;
+        i += 2;
+        continue;
+      }
+      onSkipped?.(char);
+      i += 1;
+      continue;
+    }
+
+    // --- Inside dollar-quoted string ---
+    if (dollarTag) {
+      if (text.startsWith(dollarTag, i)) {
+        onSkipped?.(dollarTag);
+        i += dollarTag.length;
+        dollarTag = null;
+        continue;
+      }
+      onSkipped?.(char);
+      i += 1;
+      continue;
+    }
+
+    // --- Inside single-quoted string ---
+    if (inSingleQuote) {
+      if (singleQuoteEscapeMode && char === "\\") {
+        if (next !== undefined) {
+          onSkipped?.(`\\${next}`);
+          i += 2;
+        } else {
+          onSkipped?.(char);
+          i += 1;
+        }
+        continue;
+      }
+      if (char === "'") {
+        if (next === "'") {
+          onSkipped?.("''");
+          i += 2;
+          continue;
+        }
+        inSingleQuote = false;
+        singleQuoteEscapeMode = false;
+      }
+      onSkipped?.(char);
+      i += 1;
+      continue;
+    }
+
+    // --- Inside double-quoted identifier ---
+    if (inDoubleQuote) {
+      if (char === '"') {
+        if (next === '"') {
+          onSkipped?.('""');
+          i += 2;
+          continue;
+        }
+        inDoubleQuote = false;
+      }
+      onSkipped?.(char);
+      i += 1;
+      continue;
+    }
+
+    // --- Top-level: check for quote/comment openers ---
+    if (char === "-" && next === "-") {
+      onSkipped?.("--");
+      inLineComment = true;
+      i += 2;
+      continue;
+    }
+    if (char === "/" && next === "*") {
+      onSkipped?.("/*");
+      inBlockComment = true;
+      i += 2;
+      continue;
+    }
+    if (char === "'") {
+      inSingleQuote = true;
+      singleQuoteEscapeMode = isEscapeStringQuoteStart(text, i);
+      onSkipped?.(char);
+      i += 1;
+      continue;
+    }
+    if (char === '"') {
+      inDoubleQuote = true;
+      onSkipped?.(char);
+      i += 1;
+      continue;
+    }
+    if (char === "$") {
+      const tag = readDollarTag(text, i);
+      if (tag) {
+        dollarTag = tag;
+        onSkipped?.(tag);
+        i += tag.length;
+        continue;
+      }
+    }
+
+    // --- Depth tracking ---
+    if (trackDepth) {
+      if (char === "(") {
+        depth += 1;
+        if (onTopLevel(i, char, depth - 1) === false) return;
+        i += 1;
+        continue;
+      }
+      if (char === ")") {
+        depth = Math.max(0, depth - 1);
+        if (onTopLevel(i, char, depth) === false) return;
+        i += 1;
+        continue;
+      }
+    }
+
+    // --- Top-level character: invoke callback ---
+    if (onTopLevel(i, char, depth) === false) return;
+    i += 1;
+  }
+}

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

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "bun:test";
+import { findTopLevelParen, scanTokens, splitByCommas } from "./tokenizer.ts";
+
+describe("scanTokens", () => {
+  it("extracts word tokens with positions and upper-cased values", () => {
+    const tokens = scanTokens("CREATE TABLE foo");
+    expect(tokens).toEqual([
+      { value: "CREATE", upper: "CREATE", start: 0, end: 6, depth: 0 },
+      { value: "TABLE", upper: "TABLE", start: 7, end: 12, depth: 0 },
+      { value: "foo", upper: "FOO", start: 13, end: 16, depth: 0 },
+    ]);
+  });
+
+  it("tracks depth for tokens inside parentheses", () => {
+    const tokens = scanTokens("fn(a, b)");
+    const inner = tokens.filter((t) => t.depth > 0);
+    expect(inner.length).toBe(2);
+    expect(inner[0].value).toBe("a");
+    expect(inner[0].depth).toBe(1);
+    expect(inner[1].value).toBe("b");
+    expect(inner[1].depth).toBe(1);
+  });
+
+  it("ignores content in quotes, comments, and dollar-quotes", () => {
+    const tokens = scanTokens("SELECT 'hello' -- comment\n FROM $$body$$ tbl");
+    const uppers = tokens.map((t) => t.upper);
+    expect(uppers).toContain("SELECT");
+    expect(uppers).toContain("FROM");
+    expect(uppers).toContain("TBL");
+    expect(uppers).not.toContain("HELLO");
+    expect(uppers).not.toContain("COMMENT");
+    expect(uppers).not.toContain("BODY");
+  });
+});
+
+describe("findTopLevelParen", () => {
+  it("finds matching () at depth 0", () => {
+    const result = findTopLevelParen("CREATE TABLE foo (a int)", 0);
+    expect(result).toEqual({ open: 17, close: 23 });
+  });
+
+  it("skips nested parentheses", () => {
+    const result = findTopLevelParen("fn((a, b), c)", 0);
+    expect(result).toEqual({ open: 2, close: 12 });
+  });
+
+  it("returns null when no match found", () => {
+    const result = findTopLevelParen("no parens here", 0);
+    expect(result).toBeNull();
+  });
+});
+
+describe("splitByCommas", () => {
+  it("splits basic comma-separated items", () => {
+    const items = splitByCommas("a, b, c");
+    expect(items).toEqual(["a", "b", "c"]);
+  });
+
+  it("preserves commas inside parentheses", () => {
+    const items = splitByCommas("a, fn(b, c), d");
+    expect(items).toEqual(["a", "fn(b, c)", "d"]);
+  });
+
+  it("preserves commas inside quotes", () => {
+    const items = splitByCommas("a, 'b,c', d");
+    expect(items).toEqual(["a", "'b,c'", "d"]);
+  });
+});

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

@@ -0,0 +1,152 @@
+import { isWordChar, walkSql } from "./sql-scanner.ts";
+import type { Token } from "./types.ts";
+
+export function scanTokens(statement: string): Token[] {
+  const tokens: Token[] = [];
+  let skipUntil = -1;
+
+  walkSql(
+    statement,
+    (index, char, depth) => {
+      if (index < skipUntil) return true;
+      if (char === "(" || char === ")") return true;
+      if (isWordChar(char)) {
+        let end = index + 1;
+        while (end < statement.length && isWordChar(statement[end])) {
+          end += 1;
+        }
+        const value = statement.slice(index, end);
+        tokens.push({
+          value,
+          upper: value.toUpperCase(),
+          start: index,
+          end,
+          depth,
+        });
+        skipUntil = end;
+      }
+      return true;
+    },
+    { trackDepth: true },
+  );
+
+  return tokens;
+}
+
+export function findTopLevelParen(
+  statement: string,
+  startIndex: number,
+): { open: number; close: number } | null {
+  let result: { open: number; close: number } | null = null;
+  let openIndex: number | null = null;
+
+  walkSql(
+    statement,
+    (index, char, depth) => {
+      if (char === "(") {
+        if (depth === 0) {
+          openIndex = index;
+        }
+        return true;
+      }
+      if (char === ")") {
+        if (depth === 0 && openIndex !== null) {
+          result = { open: openIndex, close: index };
+          return false;
+        }
+      }
+      return true;
+    },
+    { trackDepth: true, startIndex },
+  );
+
+  return result;
+}
+
+/**
+ * Collect the starting positions of top-level clause keywords in a token list.
+ * Returns a sorted array of character offsets (Token.start values).
+ */
+export function findClausePositions(
+  tokens: Token[],
+  keywords: Set<string>,
+): number[] {
+  const positions: number[] = [];
+  for (let i = 0; i < tokens.length; i += 1) {
+    if (tokens[i].depth !== 0) continue;
+    if (keywords.has(tokens[i].upper)) {
+      positions.push(tokens[i].start);
+    }
+  }
+  positions.sort((a, b) => a - b);
+  return positions;
+}
+
+/**
+ * Advance a cursor past a possibly schema-qualified name (e.g. `public.my_table`).
+ * Returns the new cursor position (pointing to the first token after the name).
+ */
+export function skipQualifiedName(
+  statement: string,
+  tokens: Token[],
+  cursor: number,
+): number {
+  let c = cursor + 1;
+  while (
+    c < tokens.length &&
+    tokens[c].start === tokens[c - 1].end + 1 &&
+    statement[tokens[c - 1].end] === "."
+  ) {
+    c += 1;
+  }
+  return c;
+}
+
+/**
+ * Slice a text into clause strings given sorted clause-start positions.
+ * Returns trimmed, non-empty clause strings.
+ */
+export function sliceClauses(text: string, positions: number[]): string[] {
+  const clauses: string[] = [];
+  for (let i = 0; i < positions.length; i += 1) {
+    const start = positions[i];
+    const end = positions[i + 1] ?? text.length;
+    const clause = text.slice(start, end).trim();
+    if (clause.length > 0) clauses.push(clause);
+  }
+  return clauses;
+}
+
+export function splitByCommas(content: string): string[] {
+  const items: string[] = [];
+  let buffer = "";
+
+  walkSql(
+    content,
+    (_index, char, depth) => {
+      if (char === "(" || char === ")") {
+        buffer += char;
+        return true;
+      }
+      if (char === "," && depth === 0) {
+        items.push(buffer);
+        buffer = "";
+        return true;
+      }
+      buffer += char;
+      return true;
+    },
+    {
+      trackDepth: true,
+      onSkipped: (chunk) => {
+        buffer += chunk;
+      },
+    },
+  );
+
+  if (buffer.length > 0) {
+    items.push(buffer);
+  }
+
+  return items.map((item) => item.trim()).filter((item) => item.length > 0);
+}

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

@@ -0,0 +1,31 @@
+type KeywordCase = "upper" | "lower" | "preserve";
+export type CommaStyle = "trailing" | "leading";
+
+export type SqlFormatOptions = {
+  keywordCase?: KeywordCase;
+  indent?: number;
+  maxWidth?: number;
+  commaStyle?: CommaStyle;
+  alignColumns?: boolean;
+  alignKeyValues?: boolean;
+  preserveRoutineBodies?: boolean;
+  preserveViewBodies?: boolean;
+  preserveRuleBodies?: boolean;
+};
+
+export type NormalizedOptions = Required<SqlFormatOptions>;
+
+export type Token = {
+  value: string;
+  upper: string;
+  start: number;
+  end: number;
+  depth: number;
+};
+
+export type ProtectedSegments = {
+  text: string;
+  placeholders: Map<string, string>;
+  noWrapPlaceholders: Set<string>;
+  skipCasing: boolean;
+};

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

@@ -0,0 +1,119 @@
+import { describe, expect, it } from "bun:test";
+import { DEFAULT_OPTIONS } from "./constants.ts";
+import type { NormalizedOptions } from "./types.ts";
+import { wrapStatement } from "./wrap.ts";
+
+const opts: NormalizedOptions = { ...DEFAULT_OPTIONS, maxWidth: 40 };
+const noWrap = new Set<string>();
+
+describe("wrapStatement", () => {
+  it("keeps short lines unwrapped", () => {
+    const result = wrapStatement("SELECT 1", opts, noWrap);
+    expect(result).toBe("SELECT 1");
+  });
+
+  it("wraps long lines at whitespace before maxWidth", () => {
+    const long = "SELECT column_a, column_b, column_c, column_d FROM my_table";
+    const result = wrapStatement(long, opts, noWrap);
+    const lines = result.split("\n");
+    expect(lines.length).toBeGreaterThan(1);
+    expect(lines[0].length).toBeLessThanOrEqual(40);
+  });
+
+  it("does not wrap comment lines regardless of length", () => {
+    const comment =
+      "-- this is a very long comment that exceeds the maximum line width significantly";
+    const result = wrapStatement(comment, opts, noWrap);
+    expect(result).toBe(comment);
+  });
+
+  it("does not wrap lines containing noWrap placeholders", () => {
+    const placeholder = "__PGDELTA_PLACEHOLDER_0__";
+    const noWrapSet = new Set([placeholder]);
+    const long = `CREATE FUNCTION foo() ${placeholder}`;
+    const result = wrapStatement(long, { ...opts, maxWidth: 20 }, noWrapSet);
+    expect(result.split("\n").length).toBe(1);
+  });
+
+  it("adds proper continuation indentation", () => {
+    const long = "SELECT column_a, column_b, column_c, column_d FROM my_table";
+    const result = wrapStatement(long, opts, noWrap);
+    const lines = result.split("\n");
+    if (lines.length > 1) {
+      expect(lines[1]).toMatch(/^\s+/);
+    }
+  });
+
+  it("prefers breaking before SQL keywords over arbitrary whitespace", () => {
+    // With maxWidth=60, the line must wrap. The keyword-aware logic should prefer
+    // to break before MATCH, FOREIGN, CHECK, ON, etc. rather than at any space.
+    const line =
+      "ADD CONSTRAINT fk_ref FOREIGN KEY (ref_id) REFERENCES tbl(id) MATCH FULL ON DELETE CASCADE";
+    const result = wrapStatement(line, { ...opts, maxWidth: 70 }, noWrap);
+    const lines = result.split("\n");
+    expect(lines.length).toBeGreaterThan(1);
+    // The second line should start with a keyword like MATCH or ON
+    const secondLineTrimmed = lines[1].trim();
+    expect(secondLineTrimmed).toMatch(
+      /^(MATCH|ON|FOREIGN|CHECK|REFERENCES|DEFERRABLE|INITIALLY)/,
+    );
+  });
+
+  it("falls back to whitespace when no keyword boundary found", () => {
+    const line =
+      "this_is_a very_long_line that_has no_sql_keywords at_all_inside";
+    const result = wrapStatement(line, { ...opts, maxWidth: 30 }, noWrap);
+    const lines = result.split("\n");
+    expect(lines.length).toBeGreaterThan(1);
+  });
+
+  it("does not break between CREATE and PUBLICATION", () => {
+    const line =
+      "CREATE PUBLICATION pub_custom FOR TABLE public.articles_with_a_very_long_name (id, title) WHERE (published = true)";
+    const result = wrapStatement(line, { ...opts, maxWidth: 70 }, noWrap);
+    const lines = result.split("\n");
+    expect(lines[0]).toContain("CREATE PUBLICATION");
+    expect(lines[0]).not.toBe("CREATE");
+  });
+
+  it("does not break between COMMENT and ON", () => {
+    const line =
+      "COMMENT ON FUNCTION public.calculate_metrics(text,text,integer) IS 'Calculate metrics for a given table'";
+    const result = wrapStatement(line, { ...opts, maxWidth: 60 }, noWrap);
+    const lines = result.split("\n");
+    expect(lines[0]).toContain("COMMENT ON");
+    expect(lines[0]).not.toBe("COMMENT");
+  });
+
+  it("does not break between GRANT/REVOKE ALL and ON", () => {
+    const line =
+      "GRANT ALL ON FUNCTION public.calculate_metrics_for_analytics_dashboard_with_extended_name(text, text, integer) TO app_user";
+    const result = wrapStatement(line, { ...opts, maxWidth: 60 }, noWrap);
+    const lines = result.split("\n");
+    expect(lines[0]).toContain("GRANT ALL ON");
+    expect(lines[0]).not.toBe("GRANT ALL");
+  });
+
+  it("never produces blank lines from breaking within leading indent", () => {
+    // Simulate a continuation line starting with "  ON ..." — should not break before ON within the indent
+    const line =
+      "  ON FUNCTION public.calculate_metrics_for_analytics_dashboard_with_extended_name(text,text,integer) IS 'Calculate metrics'";
+    const result = wrapStatement(line, { ...opts, maxWidth: 60 }, noWrap);
+    const lines = result.split("\n");
+    // No line should be empty (the blank-line bug)
+    for (const l of lines) {
+      expect(l.trim().length).toBeGreaterThan(0);
+    }
+    // First line should keep "ON FUNCTION" together
+    expect(lines[0].trim()).toMatch(/^ON FUNCTION/);
+  });
+
+  it("breaks after commas when within maxWidth (one clause per line)", () => {
+    // No parentheses: "a, b" with narrow width breaks after the comma
+    const result = wrapStatement("a, b", { ...opts, maxWidth: 3 }, noWrap);
+    const lines = result.split("\n");
+    expect(lines.length).toBe(2);
+    expect(lines[0].trimEnd()).toBe("a,");
+    expect(lines[1].trim()).toBe("b");
+  });
+});