feat(plpgsql-deparser): add hydratePlpgsqlAst for parsing embedded SQL expressions

[pyramation]

feat(plpgsql-deparser): add hydratePlpgsqlAst for parsing embedded SQL expressions

Summary

Adds a new hydratePlpgsqlAst() function that walks PL/pgSQL ASTs and parses the embedded SQL expression strings (PLpgSQL_expr.query) into full SQL AST nodes. This enables downstream tooling to work with structured SQL ASTs instead of opaque strings.

The implementation uses a discriminated union type system with four expression kinds:

• raw - fallback for unparseable expressions
• sql-expr - expressions parsed via SELECT <expr> wrapper (parseMode 2)
• sql-stmt - full SQL statements (parseMode 0)
• assign - PL/pgSQL assignments split into target/value with parsed ASTs (parseMode 3)

Key features:

• Uses the tokenizer (scanSync) to safely split assignments on := while respecting nesting
• Best-effort parsing with error capture - unparseable expressions fall back to raw kind
• Returns hydration stats for debugging (total/parsed/failed counts)
• Utility functions: isHydratedExpr() type guard and getOriginalQuery() helper

Updates since last revision

• Deparser pretty printing for CREATE FUNCTION - Added context.isPretty() checks in CreateFunctionStmt handler to format function parameters and RETURNS TABLE columns on separate lines in pretty mode. This is a change to the core pgsql-deparser package.

• Workspace dependency - plpgsql-deparser now uses workspace:* for pgsql-deparser dependency to ensure it uses the local workspace version during development.

• Creative lowercase naming - Demo uses realistic name transformations instead of _MODIFIED suffixes:

  • Function: big_kitchen_sink → order_rollup_calculator
  • Variables: v_discount → v_rebate, v_tax → v_levy
  • Default values: 0 → 42

• Full CREATE FUNCTION support - The demo test parses the full SQL statement and outputs the complete CREATE OR REPLACE FUNCTION declaration including RETURNS TABLE clause, parameters, and language specification.

• dehydratePlpgsqlAst() - Converts hydrated AST back to canonical string format for deparsing. For assign kind, reconstructs the string from target and value fields, enabling AST-level modifications to be reflected in the output.

Review & Testing Checklist for Human

• Verify deparser pretty printing behavior - The CreateFunctionStmt changes affect ALL functions in pretty mode. Review the updated snapshots in packages/deparser/__tests__/pretty/__snapshots__/ to ensure the new multiline format is acceptable.
• Check workspace dependency for publishing - The workspace:* dependency in plpgsql-deparser/package.json should be transformed to a version number during publish. Verify this works correctly with your publish workflow.
• Review PL/pgSQL body formatting - The snapshot shows formatting quirks (e.g., END IF; placement, inconsistent whitespace). The PL/pgSQL body formatting is not as clean as the SQL wrapper.
• Verify partial renaming is intentional - Only the first occurrences of v_discount and v_tax assignments are renamed. Other references still use original names.

Recommended test plan:

1. Run npm test in packages/deparser - verify 7 pre-existing failures, no new failures
2. Run npm test in packages/plpgsql-deparser - all 23 tests should pass with 9 snapshots
3. Review the snapshot files to verify the pretty-printed CREATE FUNCTION output looks correct

Notes

• This is a standalone utility - it doesn't modify the deparser behavior yet
• The hydrated AST is a separate tree from the canonical AST (preserves original for round-trip)
• Dehydration is required before deparsing since the deparser expects string queries
• Requested by Dan Lynch (@pyramation)
• Link to Devin run: https://app.devin.ai/sessions/50192c7bb0454b26845853867bd795ce

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring