102 lines
5.2 KiB
Markdown
102 lines
5.2 KiB
Markdown
# 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 `TextEdit`s 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.
|