john-slop/docs/decisions/0003-lsp-framework-and-prot...

5.2 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/didChangeConfiguration reloads 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 LspService in 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: quiet diagnostic publication

On 2026-09-30, Milestone 26 changed the presentation default without changing the shared detector. The LSP now publishes only Unicode findings unless it is started with --all-diagnostics or --minimum-diagnostic-weight WEIGHT. Minimum-weight mode always retains Unicode findings and filters only the other categories. This makes exact, fixable problems the quiet editor default while keeping the full catalog easy to exercise in tests. Filtering occurs after analysis, so CLI results, evidence scores, formatting, configuration reload, and the core finding contract 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.