feat: initial plan
This commit is contained in:
Hein
@@ -0,0 +1,124 @@
|
||||
## Project Overview
|
||||
|
||||
**PgTidy** is a PostgreSQL-focused linter and formatter written in Go. It enforces a
|
||||
consistent SQL style, detects PostgreSQL-specific issues, and formats migrations, schemas,
|
||||
functions, procedures, triggers, and related database code. The primary day-one use case is
|
||||
formatting PL/pgSQL stored procedures to a defined house style.
|
||||
|
||||
It ships as a CLI, an LSP server, a VSCode extension, and (later) a DataGrip integration.
|
||||
|
||||
# Agent Rules
|
||||
|
||||
Keep your answers short. Question everything, never assume or guess. Ask the user if you are
|
||||
unsure about anything.
|
||||
|
||||
# Architecture
|
||||
|
||||
PgTidy uses a **hybrid** strategy:
|
||||
|
||||
- **Formatting** is driven by a custom **lossless lexer + CST** (concrete syntax tree) that
|
||||
preserves every comment and whitespace span, so formatting can round-trip safely.
|
||||
- **Linting** (later milestones) is driven by the real PostgreSQL grammar via
|
||||
`go-pgquery` (libpg_query compiled to WASM with wazero — no cgo), which yields an accurate
|
||||
AST for deep semantic rules.
|
||||
|
||||
A single Go core backs every frontend (CLI, LSP, editors) and shares one `diagnostics` type.
|
||||
|
||||
```
|
||||
cmd/pgtidy/ — CLI entry; subcommands: fmt, lint (v2), lsp (v3), version
|
||||
pkg/lexer/ — lossless lexer: tokens + trivia (comments/whitespace) attached
|
||||
pkg/cst/ — concrete syntax tree (round-trippable node model)
|
||||
pkg/parser/ — recursive-descent parser → CST (DML + DDL + PL/pgSQL)
|
||||
pkg/format/ — Doc-IR printer (Wadler/Prettier-style) + style application
|
||||
pkg/config/ — .pgtidy.yaml discovery/merge: style + rule config
|
||||
pkg/diagnostics/ — shared diagnostic type (CLI + LSP)
|
||||
pkg/pgast/ — go-pgquery wrapper: SQL → real PG AST (lint, v2)
|
||||
pkg/lint/ — rule engine + rule packs (v2)
|
||||
pkg/lsp/ — LSP server (v3)
|
||||
editors/vscode/ — VSCode extension (v3)
|
||||
editors/datagrip/ — LSP4IJ integration (v4)
|
||||
testdata/corpus/ — real-world .pgsql procedures used as the safety/idempotence harness
|
||||
```
|
||||
|
||||
## Why this architecture
|
||||
|
||||
- **No cgo** (WASM-embedded libpg_query) keeps cross-compilation trivial and lets us bundle a
|
||||
single static binary per platform inside the VSCode extension.
|
||||
- **Formatting needs a lossless CST** — libpg_query drops comments and whitespace, so it cannot
|
||||
be the sole basis for a formatter. We build our own lexer/CST so the formatter never loses a
|
||||
comment.
|
||||
- **Deep lint needs an accurate AST** — go-pgquery gives the real PostgreSQL parse tree.
|
||||
- **One core, many frontends** — CLI, LSP, VSCode, and DataGrip all reuse the same engine and
|
||||
the same `diagnostics` type.
|
||||
|
||||
## Core invariants (the formatter must never violate these)
|
||||
|
||||
1. **Lossless lex**: `emit(lex(src)) == src` byte-for-byte. The lexer keeps all trivia.
|
||||
2. **Semantic equivalence**: formatting only changes trivia/layout. Verify by re-lexing the
|
||||
output and comparing the non-trivia token stream against the input.
|
||||
3. **Idempotence**: `fmt(fmt(x)) == fmt(x)`.
|
||||
4. **Graceful degradation**: any span the parser cannot handle is passed through verbatim
|
||||
rather than corrupted.
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
go build ./cmd/pgtidy # Build the binary
|
||||
go test ./... # Run all tests (incl. corpus safety harness)
|
||||
go vet ./... # Static analysis
|
||||
go fmt ./... # Format Go code
|
||||
```
|
||||
|
||||
## House style (formatter defaults; all configurable via .pgtidy.yaml)
|
||||
|
||||
- Keywords UPPERCASE; data types lowercase; identifiers lowercase snake_case.
|
||||
- Indent: 2 spaces per level.
|
||||
- Leading-comma style, one item per line, for SELECT column lists and function params.
|
||||
- Function headers: params one-per-line in parens; LANGUAGE / SECURITY / volatility each on
|
||||
their own line; `AS` then `$$` on its own line; body; closing `$$;` on its own line.
|
||||
- PL/pgSQL: `DECLARE` alone, vars 2-space indented; `--Block--` comment markers preserved;
|
||||
`BEGIN`/`END` at body level; IF/ELSIF/ELSE/END IF, loops, CASE indent their bodies.
|
||||
- Spacing: spaces around binary operators (`=`, `<>`, `||`, …) and `:=`; no space around
|
||||
`::`, `->`, `->>`, array `[...]`, or before a call's `(`.
|
||||
- Dollar-quote tags preserved verbatim (`$$`, `$S$`, `$Z$`, …).
|
||||
|
||||
## Milestones
|
||||
|
||||
### V1 — Formatter + CLI (current priority)
|
||||
1. **Lexer** (`pkg/lexer`): full PG token coverage incl. dollar-quoted strings, `--` and
|
||||
`/* */` comments, operators. Comments + whitespace as leading/trailing trivia on tokens.
|
||||
Acceptance: `emit(lex(src)) == src` byte-for-byte across the corpus.
|
||||
2. **CST + parser** (`pkg/cst`, `pkg/parser`): recursive descent for DML (SELECT/INSERT/
|
||||
UPDATE/DELETE/CTE), DDL (CREATE FUNCTION/PROCEDURE/TABLE/INDEX/TRIGGER, ALTER, DO).
|
||||
3. **PL/pgSQL body parser**: DECLARE/BEGIN/END, IF/CASE/LOOP, assignments, nested SQL.
|
||||
4. **Printer** (`pkg/format`): Doc-IR (group/indent/line/softline) driven by `style` config.
|
||||
Graceful degradation — unparsed spans pass through verbatim.
|
||||
5. **CLI** (`cmd/pgtidy fmt`): `--check`, `--write`/`-w`, stdin→stdout, `--diff`; config
|
||||
discovery walking up to `.pgtidy.yaml`; CI-friendly exit codes.
|
||||
6. **Config** (`pkg/config`): load/merge style config; defaults = house style above.
|
||||
|
||||
### V2 — Linter
|
||||
- `pkg/pgast` go-pgquery (WASM) wrapper; `pkg/lint` rule engine (rule ID, severity, config).
|
||||
- Rule packs: style/consistency, migration safety (ACCESS EXCLUSIVE locks, unsafe ALTER/ADD
|
||||
COLUMN, non-CONCURRENTLY index builds, blocking constraints), naming conventions,
|
||||
correctness/anti-patterns (SELECT *, missing WHERE on UPDATE/DELETE). Emit `diagnostics`.
|
||||
- `pgtidy lint` subcommand; `--fix` for autofixable rules.
|
||||
|
||||
### V3 — LSP + VSCode
|
||||
- `pkg/lsp`: `textDocument/formatting` + range formatting, `publishDiagnostics`, `codeAction`
|
||||
quick-fixes — all reusing the core.
|
||||
- `editors/vscode`: TS extension using `vscode-languageclient`, launches bundled `pgtidy lsp`.
|
||||
Per-platform VSIX (`win32/linux/darwin × x64/arm64`) built in CI matrix.
|
||||
|
||||
### V4 — DataGrip
|
||||
- `editors/datagrip`: integrate via LSP4IJ (free, works across JetBrains editions incl.
|
||||
DataGrip). No core changes expected.
|
||||
|
||||
## Verification
|
||||
- **Formatter:** `go test ./...` runs golden-file tests + corpus harness asserting idempotence
|
||||
and token-stream equality before/after (no semantic change).
|
||||
- **CLI:** `pgtidy fmt --check` returns non-zero on unformatted input, zero when clean.
|
||||
- **Lint (v2):** fixture SQL with known violations → assert expected diagnostics; `--fix`
|
||||
round-trips.
|
||||
- **LSP/VSCode (v3):** load a `.sql` file in a dev-host VSCode, confirm format-on-save and
|
||||
live diagnostics via the bundled binary.
|
||||
Reference in New Issue
Block a user