|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +This is a Postgres Language Server implementation providing LSP features for SQL development, including autocompletion, syntax error highlighting, type-checking, and linting. The project is built in Rust using a modular crate architecture and includes TypeScript packages for editor integrations. |
| 8 | + |
| 9 | +## Key Commands |
| 10 | + |
| 11 | +### Development Setup |
| 12 | +```bash |
| 13 | +# Install development tools |
| 14 | +just install-tools |
| 15 | + |
| 16 | +# Start database for schema introspection |
| 17 | +docker-compose up -d |
| 18 | + |
| 19 | +# For Nix users |
| 20 | +nix develop && docker-compose up -d |
| 21 | +``` |
| 22 | + |
| 23 | +### Building and Testing |
| 24 | +```bash |
| 25 | +# Run all tests |
| 26 | +just test |
| 27 | +# or: cargo test run --no-fail-fast |
| 28 | + |
| 29 | +# Test specific crate |
| 30 | +just test-crate pgt_lsp |
| 31 | + |
| 32 | +# Run doc tests |
| 33 | +just test-doc |
| 34 | +``` |
| 35 | + |
| 36 | +### Code Quality |
| 37 | +```bash |
| 38 | +# Format all code (Rust, TOML, JS/TS) |
| 39 | +just format |
| 40 | + |
| 41 | +# Lint entire codebase |
| 42 | +just lint |
| 43 | +# or: cargo clippy && cargo run -p rules_check && bun biome lint |
| 44 | + |
| 45 | +# Fix linting issues |
| 46 | +just lint-fix |
| 47 | + |
| 48 | +# Full ready check (run before committing) |
| 49 | +just ready |
| 50 | +``` |
| 51 | + |
| 52 | +### Code Generation |
| 53 | +```bash |
| 54 | +# Generate linter code and configuration |
| 55 | +just gen-lint |
| 56 | + |
| 57 | +# Create new lint rule |
| 58 | +just new-lintrule <group> <rulename> [severity] |
| 59 | + |
| 60 | +# Create new crate |
| 61 | +just new-crate <name> |
| 62 | +``` |
| 63 | + |
| 64 | +### CLI Usage |
| 65 | +The main CLI binary is `postgrestools`: |
| 66 | +```bash |
| 67 | +cargo run -p pgt_cli -- check file.sql |
| 68 | +# or after building: |
| 69 | +./target/release/postgrestools check file.sql |
| 70 | +``` |
| 71 | + |
| 72 | +## Architecture |
| 73 | + |
| 74 | +### Crate Structure |
| 75 | +The project uses a modular Rust workspace with crates prefixed with `pgt_`: |
| 76 | + |
| 77 | +**Core Infrastructure:** |
| 78 | +- `pgt_workspace` - Main API and workspace management |
| 79 | +- `pgt_lsp` - Language Server Protocol implementation |
| 80 | +- `pgt_cli` - Command-line interface |
| 81 | +- `pgt_fs` - Virtual file system abstraction |
| 82 | +- `pgt_configuration` - Configuration management |
| 83 | + |
| 84 | +**Parser and Language Processing:** |
| 85 | +- `pgt_query` - Postgres query parsing (wraps libpg_query) |
| 86 | +- `pgt_lexer` - SQL tokenizer with whitespace handling |
| 87 | +- `pgt_statement_splitter` - Splits source into individual statements |
| 88 | +- `pgt_treesitter` - Tree-sitter integration for additional parsing |
| 89 | + |
| 90 | +**Features:** |
| 91 | +- `pgt_completions` - Autocompletion engine |
| 92 | +- `pgt_hover` - Hover information provider |
| 93 | +- `pgt_analyser` & `pgt_analyse` - Linting and analysis framework |
| 94 | +- `pgt_typecheck` - Type checking via EXPLAIN |
| 95 | +- `pgt_schema_cache` - In-memory database schema representation |
| 96 | + |
| 97 | +**Utilities:** |
| 98 | +- `pgt_diagnostics` - Error and warning reporting |
| 99 | +- `pgt_console` - Terminal output and formatting |
| 100 | +- `pgt_text_edit` - Text manipulation utilities |
| 101 | +- `pgt_suppressions` - Rule suppression handling |
| 102 | + |
| 103 | +### TypeScript Packages |
| 104 | +Located in `packages/` and `editors/`: |
| 105 | +- VSCode extension in `editors/code/` |
| 106 | +- Backend JSON-RPC bridge in `packages/@postgrestools/backend-jsonrpc/` |
| 107 | +- Main TypeScript package in `packages/@postgrestools/postgrestools/` |
| 108 | + |
| 109 | +### Database Integration |
| 110 | +The server connects to a Postgres database to build an in-memory schema cache containing tables, columns, functions, and type information. This enables accurate autocompletion and type checking. |
| 111 | + |
| 112 | +### Statement Processing Flow |
| 113 | +1. Input source code is split into individual SQL statements |
| 114 | +2. Each statement is parsed using libpg_query (via `pgt_query`) |
| 115 | +3. Statements are analyzed against the schema cache |
| 116 | +4. Results are cached and updated incrementally on file changes |
| 117 | + |
| 118 | +## Testing |
| 119 | + |
| 120 | +### Test Data Location |
| 121 | +- SQL test cases: `crates/pgt_statement_splitter/tests/data/` |
| 122 | +- Analyzer test specs: `crates/pgt_analyser/tests/specs/` |
| 123 | +- Example SQL files: `example/`, `test.sql` |
| 124 | + |
| 125 | +### Snapshot Testing |
| 126 | +The project uses `insta` for snapshot testing. Update snapshots with: |
| 127 | +```bash |
| 128 | +cargo insta review |
| 129 | +``` |
| 130 | + |
| 131 | +## Configuration Files |
| 132 | + |
| 133 | +### Rust Configuration |
| 134 | +- `Cargo.toml` - Workspace definition with all crate dependencies |
| 135 | +- `rust-toolchain.toml` - Rust version specification |
| 136 | +- `rustfmt.toml` - Code formatting configuration |
| 137 | +- `clippy.toml` - Clippy linting configuration |
| 138 | + |
| 139 | +### Other Tools |
| 140 | +- `biome.jsonc` - Biome formatter/linter configuration for JS/TS |
| 141 | +- `taplo.toml` - TOML formatting configuration |
| 142 | +- `justfile` - Task runner with all development commands |
| 143 | +- `docker-compose.yml` - Database setup for testing |
| 144 | + |
| 145 | +## Development Notes |
| 146 | + |
| 147 | +### Code Generation |
| 148 | +Many parser structures are generated from PostgreSQL's protobuf definitions using procedural macros in `pgt_query_macros`. Run `just gen-lint` after modifying analyzer rules or configurations. |
| 149 | + |
| 150 | +### Database Schema |
| 151 | +The `pgt_schema_cache` crate contains SQL queries in `src/queries/` that introspect the database schema to build the in-memory cache. |
| 152 | + |
| 153 | +### Multi-Platform Support |
| 154 | +The project includes platform-specific allocators and build configurations for Windows, macOS, and Linux. |
| 155 | +- Seeing the Treesitter tree for an SQL query can be helpful to debug and implement features. To do this, create a file with an SQL query, and run `just tree-print <file.sql>`. |
0 commit comments