docs(lsp): add capability inventory, gaps, and next steps (issue #3)

.gitea/workflows/release.yml

@@ -365,6 +365,12 @@ jobs:
         with:
           version: latest
 
+      - name: Set version from tag
+        working-directory: editors/vscode
+        run: |
+          TAG="${{ github.event.inputs.tag || github.ref_name }}"
+          npm pkg set version="${TAG#v}"
+
       - name: Install and package
         working-directory: editors/vscode
         run: |
@@ -402,6 +408,12 @@ jobs:
           distribution: temurin
           java-version: '21'
 
+      - name: Set version from tag
+        working-directory: editors/datagrip
+        run: |
+          TAG="${{ github.event.inputs.tag || github.ref_name }}"
+          sed -i "s/^pluginVersion=.*/pluginVersion=${TAG#v}/" gradle.properties
+
       - name: Build plugin
         working-directory: editors/datagrip
         run: ./gradlew buildPlugin

.github/workflows/release.yml

@@ -44,6 +44,10 @@ jobs:
           cache: npm
           cache-dependency-path: editors/vscode/package-lock.json
 
+      - name: Set version from tag
+        working-directory: editors/vscode
+        run: npm pkg set version="${GITHUB_REF_NAME#v}"
+
       - name: Install and package
         working-directory: editors/vscode
         run: |
@@ -73,6 +77,10 @@ jobs:
       - name: Setup Gradle
         uses: gradle/actions/setup-gradle@v4
 
+      - name: Set version from tag
+        working-directory: editors/datagrip
+        run: sed -i "s/^pluginVersion=.*/pluginVersion=${GITHUB_REF_NAME#v}/" gradle.properties
+
       - name: Build plugin
         working-directory: editors/datagrip
         run: ./gradlew buildPlugin

AGENTS.md

@@ -59,6 +59,14 @@ testdata/corpus/   — real-world .pgsql procedures used as the safety/idempoten
 3. **Idempotence**: `fmt(fmt(x)) == fmt(x)`.
 4. **Graceful degradation**: any span the parser cannot handle is passed through verbatim
    rather than corrupted.
+5. **Runtime safety gate**: every frontend (CLI `fmt`, LSP `textDocument/formatting` and
+   `rangeFormatting`) calls `format.SemanticallyEqual(src, out)` before writing or returning
+   formatted output. It re-lexes both sides and compares non-trivia token streams
+   (case-insensitive for identifiers/keywords, exact otherwise, recursing into dollar-quoted
+   bodies). If it ever returns false, the formatter has a bug — the caller must refuse to
+   write/emit the result and keep the original source, never guess or best-effort it. This is
+   not just a test assertion (`pkg/format/format_test.go`); it is enforced at runtime so a
+   formatter bug can never silently drop or alter code.
 
 ## Commands
 

cmd/pgtidy/fmt.go

@@ -63,6 +63,10 @@ func cmdFmt(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 			return 2
 		}
 		out := format.File(parser.Parse(string(src)), st)
+		if !format.SemanticallyEqual(string(src), out) {
+			_, _ = fmt.Fprintln(stderr, "pgtidy: refusing to format stdin: formatter safety check failed (output would change code content)")
+			return 2
+		}
 		switch {
 		case check:
 			if out != string(src) {
@@ -86,6 +90,11 @@ func cmdFmt(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 			continue
 		}
 		out := format.File(parser.Parse(string(src)), st)
+		if !format.SemanticallyEqual(string(src), out) {
+			_, _ = fmt.Fprintf(stderr, "pgtidy: refusing to format %s: formatter safety check failed (output would change code content)\n", path)
+			exit = 2
+			continue
+		}
 		changed := out != string(src)
 		if changed {
 			anyDiff = true

docs/lsp-status.md

@@ -0,0 +1,116 @@
+# PgTidy LSP Status & Roadmap
+
+This document describes the current state of the PgTidy LSP server (`pkg/lsp`,
+`cmd/pgtidy/lsp.go`), what it actually provides today, and concrete next steps.
+It was written as part of issue #3 ("See what we can provide for LSP").
+
+> Note: The V3 milestone is already implemented and shipping (`docs/todo.md` marks
+> V3 done), so this is an inventory + gap analysis, not a greenfield proposal.
+
+## What the server provides today
+
+Verified by hand against the built binary (`pgtidy lsp`, JSON-RPC 2.0 over stdio,
+`Content-Length` framing) — no external LSP library, all wire types hand-rolled.
+
+### Advertised capabilities (`initialize` → `capabilities`)
+
+| Capability | Value | Where |
+|---|---|---|
+| `textDocumentSync` | `1` (full sync) | `serverCaps` |
+| `documentFormattingProvider` | `true` | `handle("initialize")` |
+| `documentRangeFormattingProvider` | `true` | `handle("initialize")` |
+| `codeActionProvider` | `true` | `handle("initialize")` |
+
+### Supported methods
+
+| Method | Direction | Behavior |
+|---|---|---|
+| `initialize` / `shutdown` / `exit` / `initialized` | req/resp + notif | Lifecycle. `exit`/`shutdown` acknowledged with `null` result. |
+| `textDocument/didOpen` | notif | Stores document text; triggers `publishDiagnostics`. |
+| `textDocument/didChange` | notif | Stores latest content version; triggers `publishDiagnostics`. |
+| `textDocument/didClose` | notif | Drops text + fix cache; clears diagnostics with empty list. |
+| `textDocument/formatting` | req/resp | Full-doc format via `pkg/format`; returns one `fullReplace` `TextEdit`. |
+| `textDocument/rangeFormatting` | req/resp | Formats doc, returns minimal edit over the selected line range. |
+| `textDocument/codeAction` | req/resp | Returns quick-fix `WorkspaceEdit`s for fixable diagnostics overlapping the range. |
+| `textDocument/publishDiagnostics` | notif | Sent on every open/change; diagnostic code = `RuleID`, source = `pgtidy`. |
+| `$/cancelRequest` | req | Ignored (per LSP, no response). |
+| unknown | req/resp | `-32601 method not found` (when the request has an `id`). |
+
+### Verified at runtime (e2e smoke test)
+
+- `initialize` returns the capability block above.
+- `didOpen` on `select * from t;` → `publishDiagnostics` with `COR001`
+  ("SELECT * is fragile…", severity 4 = hint, code `COR001`).
+- `textDocument/formatting` on that input → edit replacing with
+  `SELECT *\nFROM t;\n` (keyword casing + clause-per-line applied).
+- `textDocument/hover` → `-32601 method not found` (not implemented — correct).
+
+## What the server does NOT provide (gaps)
+
+These are the most useful, well-scoped gaps to fill next. None are blockers for the
+current shipping state.
+
+1. **No `hover`.** `textDocument/hover` is unimplemented and returns `-32601`.
+   A natural first add: return the `RuleID` + a short explanation for diagnostics
+   on the hovered range, or a keyword/type doc for `hover` on SQL identifiers.
+2. **No `documentSymbol` / `documentLink`.** No outline/symbol tree. For a formatter
+   that already parses `CREATE FUNCTION`/`PROCEDURE` headers into a CST, a symbol
+   provider listing functions/procedures would be low-cost and high-value in large
+   schema files.
+3. **`hover`-style diagnostics shape.** Diagnostics currently use a `Range` whose
+   `end.character` is `start.character + 1` (a 1-char caret), not the actual
+   offending span. A real highlight range would improve editor UX.
+4. **`textDocument/willSave` / `willSaveWaitUntil` / `didSave`.** No save hooks —
+   "format-on-save" must currently be driven by the client binding
+   `textDocument/formatting` to the editor's save event. A `willSaveWaitUntil`
+   handler would let the server own format-on-save.
+5. **No `completion`.** `textDocument/completion` is not implemented. Not urgent for
+   a formatter/linter, but relevant if PL/pgSQL autocompletion (keywords, types) is
+   ever in scope.
+6. **No diagnostics debounce/coalescing beyond full-sync.** Every `didChange`
+   re-runs the full lint engine. Fine for now; a debounce + incremental re-check
+   becomes relevant on large files.
+7. **`initializationOptions` / workspace config.** `initialize` params are parsed
+   nowhere — no way to pass style overrides or a config path over the protocol.
+8. **No `textDocument/prepareRename`, `rename`, `references`, `foldingRange`.**
+   Low priority; would be natural extensions once symbol info exists.
+
+## Conventions to keep consistent
+
+- **One core, many frontends.** The LSP reuses `pkg/diagnostics.Diagnostic` and
+  `pkg/lint` directly — no parallel diagnostic model. New LSP features should reuse
+  these, not fork them.
+- **Safety gate is non-negotiable.** Both `formatting` and `rangeFormatting` call
+  `format.SemanticallyEqual(src, out)` before returning edits; on failure they return
+  an empty edit (keep original). Any new code path that formats must honor this
+  invariant (invariant #5 in `AGENTS.md`).
+- **No new external deps.** The wire layer is intentionally dependency-free. New
+  protocol types should be added as local structs, not pulled in from an LSP library.
+
+## Concrete next steps (recommended, smallest-first)
+
+Ranked by effort/value for the smallest useful delta:
+
+1. **Add a real diagnostic highlight range** (swap the 1-char caret for the actual
+   offending span) — ~1 file, no new method, immediate UX win. Reuses existing
+   `RuleID`/severity data.
+2. **Add `textDocument/hover`** returning the rule explanation for the hovered
+   diagnostic, or a keyword/type glossary. Reuses `pkg/lint` rule metadata.
+3. **Add `documentSymbol`** listing `CREATE FUNCTION`/`PROCEDURE` signatures.
+   Reuses the existing CST header parse in `pkg/format`.
+4. **Add `willSaveWaitUntil`** to own format-on-save instead of relying on client
+   binding.
+
+> Do NOT: expand the LSP surface into a broad design (workspace features,
+   incremental parsing, custom `textDocument/*` extensions) as part of this issue.
+   Keep any change scoped to the above and evidence-backed by a `pkg/lsp` test
+   (see `server_test.go` for the framed-request/response harness).
+
+## Verification
+
+- `go build ./cmd/pgtidy` succeeds.
+- `go test ./...` passes (LSP unit tests in `pkg/lsp/server_test.go` exercise
+  `initialize`, formatting, range formatting, `didClose` diagnostics clearing).
+- Runtime e2e smoke test (framed JSON-RPC over stdio) confirmed `initialize`
+  capabilities, `COR001` diagnostics, and a formatting edit; `hover` correctly
+  returns `-32601`.

docs/todo.md

@@ -119,6 +119,7 @@ Legend: ✅ done · 🚧 in progress · ⬜ not started
 - `cmd/pgtidy/lsp.go`: `pgtidy lsp` subcommand; config discovered from cwd.
 - `editors/vscode/`: TS extension using `vscode-languageclient`; launches `pgtidy lsp` via stdio; `.pgsql` mapped to `sql` language; `pgtidy.path` / `pgtidy.enable` settings.
 - _Range formatting: future._
+- Full capability inventory, runtime-verified gaps, and ranked next steps in `docs/lsp-status.md` (issue #3).
 
 ## ✅ V4 — DataGrip
 - `editors/datagrip/`: Gradle-based JetBrains plugin targeting DataGrip 2024.3+ via LSP4IJ.

linux/arch/PKGBUILD

@@ -1,6 +1,6 @@
 # Maintainer: Hein (Warky Devs) <hein@warky.dev>
 pkgname=pgtidy-bin
-pkgver=0.0.6
+pkgver=0.0.7
 pkgrel=1
 pkgdesc="PostgreSQL SQL formatter and linter"
 arch=('x86_64' 'aarch64')

linux/centos/pgtidy.spec

@@ -1,5 +1,5 @@
 Name:           pgtidy
-Version:        0.0.6
+Version:        0.0.7
 Release:        1%{?dist}
 Summary:        PostgreSQL SQL formatter and linter
 

pkg/format/format_test.go

@@ -7,7 +7,6 @@ import (
 	"testing"
 
 	"git.warky.dev/wdevs/pgtidy/pkg/config"
-	"git.warky.dev/wdevs/pgtidy/pkg/lexer"
 	"git.warky.dev/wdevs/pgtidy/pkg/parser"
 )
 
@@ -199,48 +198,7 @@ func TestCorpusIdempotentAndSafe(t *testing.T) {
 	t.Logf("formatted %d corpus files (idempotent + semantically equal)", seen)
 }
 
-// semanticallyEqual compares the non-trivia token streams of two sources,
-// treating unquoted identifiers/keywords case-insensitively and everything
-// else (strings, numbers, operators, punctuation) exactly. Dollar-quoted body
-// tokens are compared recursively so body whitespace normalization does not
-// trigger a false failure.
+// semanticallyEqual is a test-local alias for the exported safety check.
 func semanticallyEqual(a, b string) bool {
-	ta := significant(a)
-	tb := significant(b)
-	if len(ta) != len(tb) {
-		return false
-	}
-	for i := range ta {
-		if ta[i].Kind != tb[i].Kind {
-			return false
-		}
-		switch ta[i].Kind {
-		case lexer.Ident:
-			if !strings.EqualFold(ta[i].Text, tb[i].Text) {
-				return false
-			}
-		case lexer.DollarString:
-			_, innerA, _, okA := splitDollarQuote(ta[i].Text)
-			_, innerB, _, okB := splitDollarQuote(tb[i].Text)
-			if okA != okB || (okA && !semanticallyEqual(innerA, innerB)) {
-				return false
-			}
-		default:
-			if ta[i].Text != tb[i].Text {
-				return false
-			}
-		}
-	}
-	return true
-}
-
-func significant(src string) []lexer.Token {
-	var out []lexer.Token
-	for _, t := range lexer.Lex(src) {
-		if t.Kind == lexer.EOF || t.IsTrivia() {
-			continue
-		}
-		out = append(out, t)
-	}
-	return out
+	return SemanticallyEqual(a, b)
 }

pkg/format/safety.go

@@ -0,0 +1,61 @@
+package format
+
+import (
+	"strings"
+
+	"git.warky.dev/wdevs/pgtidy/pkg/lexer"
+)
+
+// SemanticallyEqual reports whether a and b have the same non-trivia token
+// stream, i.e. formatting may only ever change whitespace/comment trivia and
+// layout — it must never add, remove, or alter a token of actual code.
+// Unquoted identifiers/keywords compare case-insensitively (casing is a
+// style choice); everything else (strings, numbers, operators, punctuation)
+// must match exactly. Dollar-quoted body tokens are compared recursively so
+// that independent body reformatting doesn't trigger a false failure.
+//
+// The CLI and LSP must call this before ever writing or emitting formatted
+// output: if it returns false, the formatter has a bug and the original
+// source must be kept, never the (corrupting) formatted output.
+func SemanticallyEqual(a, b string) bool {
+	ta := significantTokens(a)
+	tb := significantTokens(b)
+	if len(ta) != len(tb) {
+		return false
+	}
+	for i := range ta {
+		if ta[i].Kind != tb[i].Kind {
+			return false
+		}
+		switch ta[i].Kind {
+		case lexer.Ident:
+			if !strings.EqualFold(ta[i].Text, tb[i].Text) {
+				return false
+			}
+		case lexer.DollarString:
+			_, innerA, _, okA := splitDollarQuote(ta[i].Text)
+			_, innerB, _, okB := splitDollarQuote(tb[i].Text)
+			if okA != okB || (okA && !SemanticallyEqual(innerA, innerB)) {
+				return false
+			}
+		default:
+			if ta[i].Text != tb[i].Text {
+				return false
+			}
+		}
+	}
+	return true
+}
+
+// significantTokens lexes src and returns its tokens excluding EOF and trivia
+// (whitespace/comments).
+func significantTokens(src string) []lexer.Token {
+	var out []lexer.Token
+	for _, t := range lexer.Lex(src) {
+		if t.Kind == lexer.EOF || t.IsTrivia() {
+			continue
+		}
+		out = append(out, t)
+	}
+	return out
+}

pkg/lsp/server.go

@@ -124,6 +124,10 @@ func (s *server) handle(raw []byte) bool {
 			s.reply(req.ID, []textEdit{})
 			return false
 		}
+		if !format.SemanticallyEqual(text, formatted) {
+			s.reply(req.ID, []textEdit{})
+			return false
+		}
 		s.reply(req.ID, []textEdit{fullReplace(text, formatted)})
 	case "textDocument/rangeFormatting":
 		var p rangeFormattingParams
@@ -224,6 +228,9 @@ func (s *server) rangeFormat(text string, r lspRange) []textEdit {
 	if formatted == text {
 		return nil
 	}
+	if !format.SemanticallyEqual(text, formatted) {
+		return nil
+	}
 
 	// Split both versions into lines, keeping the trailing newline attached to
 	// each element so that joining them reconstructs the original string.