feat: Add comprehensive documentation for @pgsql/transform package

[pyramation]

feat: Add comprehensive documentation for @pgsql/transform package

Summary

This PR adds comprehensive documentation for the @pgsql/transform package, which enables transformation of PostgreSQL ASTs between different PostgreSQL versions (13→17). The package serves as a crucial component for building a single source of truth deparser that maintains backward compatibility with legacy SQL code.

Key changes:

• Added transform package entry to main README packages table with brief description
• Completely rewrote packages/transform/README.md (was incorrectly describing @pgsql/types instead of transform functionality)
• Created detailed documentation covering core use cases, limitations, usage examples, and architecture
• Documented both incremental (13→14→15→16→17) and direct (13→17) transformation patterns
• Added integration examples showing how transform works with parser and deparser packages

Note: Initially added extensive documentation to main README, but per feedback, moved detailed content to package README and kept only brief highlight in main README.

Review & Testing Checklist for Human

🔴 Critical (4 items)

• Verify all code examples actually work - Test the TypeScript imports and method calls to ensure they match the actual API (I didn't run these examples)
• Check package installation - Confirm that npm install @pgsql/transform works or determine the correct installation method
• Validate technical accuracy - Verify that the transformation chain description (PG13→PG14→PG15→PG16→PG17) matches actual implementation
• Test API examples - Check that exported classes like ASTTransformer, PG13ToPG17Transformer actually exist and have the documented methods

🟡 Important (2 items)

• Review "Key Limitation" accuracy - Confirm that the constraint about "only PG17-parseable SQL" is correctly stated
• Test integration examples - Validate that the multi-package examples (parser + transform + deparser) represent realistic usage

Recommended test plan:

1. Install the transform package and verify imports work
2. Try running the provided code examples in a test environment
3. Test a simple transformation with an actual AST from an older PostgreSQL version
4. Check that the documentation renders properly in GitHub

---

Diagram

%%{ init : { "theme" : "default" }}%%
graph TD
    MainREADME["README.md"]:::minor-edit
    TransformREADME["packages/transform/README.md"]:::major-edit
    TransformSrc["packages/transform/src/"]:::context
    MultiVersionTransformer["src/multi-version-transformer.ts"]:::context
    DirectTransformers["src/transformers-direct/"]:::context
    V13ToV14["src/transformers/v13-to-v14.ts"]:::context
    
    MainREADME --> |"Added packages table entry"| TransformPackage["@pgsql/transform package"]
    TransformREADME --> |"Complete rewrite with correct docs"| TransformPackage
    
    TransformSrc --> MultiVersionTransformer
    TransformSrc --> DirectTransformers  
    TransformSrc --> V13ToV14
    
    TransformPackage --> |"Documents"| MultiVersionTransformer
    TransformPackage --> |"Documents"| DirectTransformers
    
    subgraph Legend
        L1["Major Edit"]:::major-edit
        L2["Minor Edit"]:::minor-edit  
        L3["Context/No Edit"]:::context
    end
    
    classDef major-edit fill:#90EE90
    classDef minor-edit fill:#87CEEB
    classDef context fill:#FFFFFF

Loading

Notes

• Documentation source: Created by exploring transform package source code to understand architecture and functionality
• Previous issue: packages/transform/README.md was incorrectly describing @pgsql/types instead of transform functionality
• Key insight: Transform package appears to be critical but under-documented component of pgsql-parser ecosystem
• Session info: Requested by Dan Lynch (@pyramation) - Link to Devin run: https://app.devin.ai/sessions/5d3c2c917dda42169770d94202c4a518
• Risk: Code examples written based on source exploration but not tested - human verification essential

[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