test: add fixture-based round-trip CST tests

7 SQL fixture files covering:
- PGPM headers with deploy/requires comments
- Multi-statement schema setup (CREATE TABLE, INSERT)
- RLS policies and GRANT statements
- PL/pgSQL functions with dollar-quoted bodies
- Views and triggers
- ALTER/DROP statements
- Edge cases (trailing comments, adjacent comments, dollar-quoted internals)

Each fixture verifies:
1. parse→deparse→parse→deparse idempotency (CST round trip)
2. All top-level -- comments preserved
3. All SQL statements survive
4. CST node ordering matches source order

56 total tests (28 existing + 28 new).

Author: pyramation

packages/parse/__tests__/fixtures/alter-and-drop.sql

@@ -0,0 +1,12 @@
+-- Add columns to existing table
+ALTER TABLE app.users ADD COLUMN bio text;
+ALTER TABLE app.users ADD COLUMN avatar_url text;
+
+-- Rename a column
+ALTER TABLE app.users RENAME COLUMN username TO display_name;
+
+-- Drop unused objects
+DROP INDEX IF EXISTS app.idx_old_index;
+
+-- Recreate with new definition
+CREATE INDEX idx_users_display_name ON app.users (display_name);

packages/parse/__tests__/fixtures/edge-cases.sql

@@ -0,0 +1,24 @@
+-- Comments with special characters: don't break "parsing"
+SELECT 1;
+
+-- Inline comment after statement
+SELECT 2; -- trailing note
+
+-- Adjacent comments with no blank line
+-- first line
+-- second line
+SELECT 3;
+
+-- Dollar-quoted body with internal comments (should NOT be extracted)
+CREATE FUNCTION app.noop() RETURNS void AS $$
+BEGIN
+  -- this comment is inside the function body
+  NULL;
+END;
+$$ LANGUAGE plpgsql;
+
+-- String that looks like a comment
+SELECT '-- not a comment' AS val;
+
+-- Empty statement list edge
+SELECT 4;

packages/parse/__tests__/fixtures/grants-and-policies.sql

@@ -0,0 +1,19 @@
+-- RLS policies for the users table
+ALTER TABLE app.users ENABLE ROW LEVEL SECURITY;
+
+-- Admins can see all rows
+CREATE POLICY admin_all ON app.users
+  FOR ALL
+  TO admin_role
+  USING (true);
+
+-- Users can only see their own row
+CREATE POLICY own_row ON app.users
+  FOR SELECT
+  TO authenticated
+  USING (id = current_setting('app.current_user_id')::integer);
+
+-- Grant basic access
+GRANT USAGE ON SCHEMA app TO authenticated;
+GRANT SELECT ON app.users TO authenticated;
+GRANT ALL ON app.users TO admin_role;

packages/parse/__tests__/fixtures/multi-statement.sql

@@ -0,0 +1,25 @@
+-- Schema setup
+CREATE SCHEMA IF NOT EXISTS app;
+
+-- Users table
+CREATE TABLE app.users (
+  id serial PRIMARY KEY,
+  username text NOT NULL,
+  created_at timestamptz DEFAULT now()
+);
+
+-- Roles table
+CREATE TABLE app.roles (
+  id serial PRIMARY KEY,
+  name text UNIQUE NOT NULL
+);
+
+-- Junction table
+CREATE TABLE app.user_roles (
+  user_id integer REFERENCES app.users (id),
+  role_id integer REFERENCES app.roles (id),
+  PRIMARY KEY (user_id, role_id)
+);
+
+-- Seed default roles
+INSERT INTO app.roles (name) VALUES ('admin'), ('viewer');

packages/parse/__tests__/fixtures/pgpm-header.sql

@@ -0,0 +1,16 @@
+-- Deploy schemas/my-app/tables/users to pg
+-- requires: schemas/my-app/schema
+
+BEGIN;
+
+-- Create the main users table
+CREATE TABLE my_app.users (
+  id serial PRIMARY KEY,
+  name text NOT NULL,
+  email text UNIQUE
+);
+
+-- Add an index for fast lookups
+CREATE INDEX idx_users_email ON my_app.users (email);
+
+COMMIT;

packages/parse/__tests__/fixtures/plpgsql-function.sql

@@ -0,0 +1,21 @@
+-- Deploy schemas/app/functions/get_user to pg
+-- requires: schemas/app/tables/users
+
+BEGIN;
+
+-- Function to get a user by ID
+CREATE FUNCTION app.get_user(p_id integer)
+RETURNS TABLE (id integer, username text, created_at timestamptz) AS $$
+BEGIN
+  -- Return the matching user
+  RETURN QUERY
+  SELECT u.id, u.username, u.created_at
+  FROM app.users u
+  WHERE u.id = p_id;
+END;
+$$ LANGUAGE plpgsql STABLE;
+
+-- Grant execute to authenticated users
+GRANT EXECUTE ON FUNCTION app.get_user(integer) TO authenticated;
+
+COMMIT;

packages/parse/__tests__/fixtures/views-and-triggers.sql

@@ -0,0 +1,20 @@
+-- Active users view
+CREATE VIEW app.active_users AS
+  SELECT id, username, created_at
+  FROM app.users
+  WHERE created_at > now() - interval '90 days';
+
+-- Audit trigger function
+CREATE FUNCTION app.audit_trigger() RETURNS trigger AS $$
+BEGIN
+  INSERT INTO app.audit_log (table_name, action, row_id)
+  VALUES (TG_TABLE_NAME, TG_OP, NEW.id);
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Attach trigger to users table
+CREATE TRIGGER users_audit
+  AFTER INSERT OR UPDATE ON app.users
+  FOR EACH ROW
+  EXECUTE FUNCTION app.audit_trigger();

packages/parse/__tests__/roundtrip.test.ts

@@ -0,0 +1,125 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import {
+  parseSync,
+  deparseEnhanced,
+  isRawComment,
+  isRawWhitespace,
+  isRawStmt,
+  loadModule,
+} from '../src';
+
+const FIXTURES_DIR = path.join(__dirname, 'fixtures');
+
+const fixtures = fs.readdirSync(FIXTURES_DIR)
+  .filter(f => f.endsWith('.sql'))
+  .sort()
+  .map(f => ({
+    name: f.replace('.sql', ''),
+    sql: fs.readFileSync(path.join(FIXTURES_DIR, f), 'utf-8'),
+  }));
+
+beforeAll(async () => {
+  await loadModule();
+});
+
+describe('fixture round-trip (CST)', () => {
+  for (const { name, sql } of fixtures) {
+    describe(name, () => {
+      it('parse→deparse→parse→deparse is idempotent', () => {
+        // First round trip
+        const result1 = parseSync(sql);
+        const output1 = deparseEnhanced(result1);
+
+        // Second round trip
+        const result2 = parseSync(output1);
+        const output2 = deparseEnhanced(result2);
+
+        // The two deparses must produce identical output
+        expect(output2).toBe(output1);
+      });
+
+      it('preserves all -- comments from the original', () => {
+        const result = parseSync(sql);
+        const output = deparseEnhanced(result);
+
+        // Extract expected comments: lines starting with -- that are NOT
+        // inside dollar-quoted blocks
+        const expectedComments = extractTopLevelComments(sql);
+
+        for (const comment of expectedComments) {
+          expect(output).toContain(comment);
+        }
+      });
+
+      it('preserves all SQL statements from the original', () => {
+        const result = parseSync(sql);
+        const stmts = result.stmts.filter(isRawStmt);
+
+        // Should have at least one real statement
+        expect(stmts.length).toBeGreaterThan(0);
+
+        // Deparse should produce valid SQL for each statement
+        const output = deparseEnhanced(result);
+        expect(output.length).toBeGreaterThan(0);
+      });
+
+      it('CST node ordering matches source order', () => {
+        const result = parseSync(sql);
+        const types = result.stmts.map(s => {
+          if (isRawComment(s)) return 'comment';
+          if (isRawWhitespace(s)) return 'whitespace';
+          if (isRawStmt(s)) return 'stmt';
+          return 'unknown';
+        });
+
+        // No unknown node types
+        expect(types).not.toContain('unknown');
+
+        // Should have at least one statement
+        expect(types).toContain('stmt');
+      });
+    });
+  }
+});
+
+/**
+ * Extract top-level -- comments from SQL source, skipping any
+ * that appear inside dollar-quoted strings.
+ */
+function extractTopLevelComments(sql: string): string[] {
+  const comments: string[] = [];
+  let inDollarQuote = false;
+  let dollarTag = '';
+
+  const lines = sql.split('\n');
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Check for dollar-quote boundaries
+    const dollarMatch = trimmed.match(/\$([a-zA-Z_]*)\$/);
+    if (dollarMatch) {
+      const tag = dollarMatch[0];
+      if (!inDollarQuote) {
+        // Check if this line also closes the dollar quote
+        const firstIdx = trimmed.indexOf(tag);
+        const secondIdx = trimmed.indexOf(tag, firstIdx + tag.length);
+        if (secondIdx === -1) {
+          inDollarQuote = true;
+          dollarTag = tag;
+        }
+        // If both open and close on same line, not entering a block
+      } else if (tag === dollarTag) {
+        inDollarQuote = false;
+        dollarTag = '';
+      }
+      continue;
+    }
+
+    if (!inDollarQuote && trimmed.startsWith('--')) {
+      comments.push(trimmed);
+    }
+  }
+
+  return comments;
+}