4.6 KiB
ADR 0003: LSP framework and protocol contract
- Status: accepted, amended by Milestone 19
- Date: 2026-09-29
Context
John Slop needs a small stdio language server that reuses the validated
replacement configuration and exact TextEdits from the library. Implementing
JSON-RPC framing and the Language Server Protocol state machine locally would
add protocol risk without improving detection. The original tower-lsp crate's
latest release is 0.20.0, while its maintained community continuation publishes
the same Tower-oriented API as tower-lsp-server.
The dependency review compared the crates' published metadata, documentation,
runtime features, and minimum Rust versions. tower-lsp-server 0.23.0 is the
latest stable release; 0.24.0-rc.1 is a prerelease. Version 0.23.0 requires Rust
1.85, below this project's Rust 1.98.1 baseline, and provides the Tokio stdio
transport, generated LSP types, client notifications, and in-process service
interface needed by the milestone. Its MIT OR Apache-2.0 licensing is compatible
with this project.
Decision
Use tower-lsp-server 0.23 and its Tokio runtime feature. Use Tokio directly
only for the stdio runtime and synchronized in-memory document state. Do not
enable proposed LSP extensions or an alternate URI implementation.
The initial server targets stable LSP 3.17 behavior with these assumptions:
- transport is stdio only, with protocol bytes reserved for stdout;
- document positions are zero-based UTF-16 code-unit offsets;
- clients send full-document synchronization, simplifying authoritative version handling while replacement behavior is established;
- the server owns snapshots of open documents only and never writes their URIs;
- diagnostics and quick fixes cover configured ASCII replacements, not heuristic authorship or aggregate heuristic findings;
- quick fixes use versioned workspace edits and are rejected when the request refers to a stale or unknown document version;
workspace/didChangeConfigurationreloads the same layered configuration used by the CLI and formatter, then republishes diagnostics for open snapshots;- malformed messages and invalid URIs are protocol/input errors, never panics.
Consequences
- The replacement engine remains the single source of edit ranges and text.
- A tested line index converts canonical UTF-8 byte offsets to LSP UTF-16 positions at the adapter boundary.
- Protocol tests can drive
LspServicein process without launching a child process, while a small stdio smoke test protects stream purity. - Incremental synchronization may be added later, but must preserve version and stale-result guarantees before it is advertised.
- Upgrading to the 0.24 line waits for a stable release and a separate API and minimum-Rust review.
Amendment: full heuristic diagnostics
On 2026-09-29, Milestone 19 superseded the initial replacement-only diagnostic limit after the core detector and configuration contracts had stabilized. The server now compiles the same detector as the CLI once per resolved configuration and publishes every applicable finding for each open snapshot.
This amendment does not broaden mutation behavior:
- safe configured replacements remain the only findings with quick fixes;
- style, prompt-leakage, and source-code review findings are diagnostic-only;
- stable heuristic IDs replace replacement-entry IDs as published diagnostic codes, avoiding duplicate typography diagnostics;
- configured advice, warning, and error severities map to LSP information, warning, and error respectively;
- file URI paths retain extension and path-scope behavior, while editor language IDs determine prose/source applicability for untitled or extensionless buffers; and
- configuration reload atomically swaps the validated configuration and compiled detector before open documents are republished.
The original full-snapshot synchronization, UTF-16 conversion, version checks, stdio purity, no-write boundary, and stale-action guarantees remain unchanged.
Amendment: document formatting parity
Milestone 21 adds the standard textDocument/formatting capability. The server
plans edits from its current open-document snapshot with the same resolved
configuration and core replacement planner used by john-slop-fmt, then
converts only the edit coordinates from UTF-8 bytes to LSP UTF-16 positions.
Formatting remains limited to configured safe ASCII replacements; the server
does not write files, infer formatting from diagnostics, or apply broader
Unicode review findings. Protocol tests compare the result of an actual
formatting request with the standalone formatter contract, including Unicode,
CRLF, no-op, and configuration-reload cases.