feat: add pgsql-parse package with comment and whitespace preservation

[pyramation]

Summary

Adds a new self-contained packages/parse/ package that preserves SQL comments (-- line and /* */ block) and vertical whitespace (blank lines) through parse→deparse round trips. No existing packages are modified.

How it works:

1. A pure TypeScript scanner (scanner.ts) extracts comment and whitespace tokens with byte positions from the raw SQL text, handling string literals, dollar-quoted strings, escape strings, and nested block comments.
2. Enhanced parse/parseSync call the standard libpg-query parser, then interleave synthetic RawComment and RawWhitespace nodes into the stmts array based on byte position.
3. deparseEnhanced() dispatches on node type — real RawStmt entries go through the standard deparser, while synthetic nodes emit their comment text or blank lines directly.

Key design decisions:

• interleave() uses a unified sort with priority levels (comment < whitespace < statement) to handle ties when stmt_location overlaps with preceding comments
• findActualSqlStart() iteratively skips whitespace and scanned elements within a statement's stmt_location range to find the actual SQL keyword position — needed because PostgreSQL's parser includes preceding stripped content in stmt_location
• 36 tests across scanner (18) and integration (18) suites, including an idempotency test (parse→deparse→parse→deparse = identical output)

Updates since last revision

• Added README.md for the package — the makage assets build step requires it (was causing all 7 parser-tests CI jobs to fail)

Review & Testing Checklist for Human

• CI does not run this package's tests: The CI test matrix (run-tests.yaml) does not include pgsql-parse. The 7 parser-tests jobs passed because the package builds successfully, but the 36 Jest tests are not executed in CI. Consider adding pgsql-parse to the matrix before merging, or verify locally.
• Scanner edge cases: scanner.ts is a pure TypeScript reimplementation of comment boundary detection — it does NOT use PostgreSQL's actual lexer. It must correctly skip comments inside single-quoted strings, double-quoted identifiers, dollar-quoted strings (including custom tags like $tag$...$tag$), and E'...' escape strings. A bug here silently corrupts output. Test with SQL containing $$, $fn$, nested /* */, and mixed quote styles.
• findActualSqlStart() correctness (parse.ts:12-44): This function walks forward from stmt_location skipping whitespace and scanned elements. Verify it handles: multiple adjacent comments before a statement, a comment immediately followed by a statement with no whitespace, and the first statement at position 0.
• Idempotency with complex SQL: The test uses one PGPM-style fixture. Try round-tripping SQL with: inline comments after statements on the same line (SELECT 1; -- inline), comments between clauses of a multi-line statement, trailing comments after the last statement with no newline, and empty input.
• Lockfile review: The pnpm-lock.yaml diff is large but mostly quoting style changes ("@scope/pkg" → '@scope/pkg'). Verify the only substantive change is adding the new packages/parse workspace entry and its dev dependencies.

Suggested test plan: Clone the branch, run cd packages/parse && npx jest to verify 36/36 pass. Then try parsing your own SQL files with comments through parseSync → deparseEnhanced and inspect the output for correctness, especially files with PGPM headers and PL/pgSQL function bodies containing comments.

Notes

• The scanner is a pure TypeScript implementation rather than using libpg-query's scan() from the full build. This was a deliberate choice to avoid requiring the heavier WASM binary, but it means comment detection is not using PostgreSQL's actual lexer — edge cases in exotic string literals could diverge.
• Inline comments (comments on the same line after a statement, e.g. SELECT 1; -- note) are extracted by the scanner but will be repositioned to their own line after deparsing, since the deparser emits statements without trailing content.
• The package depends on workspace packages (pgsql-parser, pgsql-deparser, @pgsql/types) via workspace:* protocol. tsconfig.test.json has path mappings so tests resolve TypeScript source directly without requiring a build step.

Link to Devin session: https://app.devin.ai/sessions/67facbcfe0ae424bad3eafb4e6ca9059
Requested by: @pyramation

[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