docs: select LSP framework

This commit is contained in:
Dandaedre 2026-09-29 16:57:21 +02:00
parent 033be96d79
commit 837b1fce55
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
5 changed files with 364 additions and 2 deletions

305
Cargo.lock generated
View File

@ -92,6 +92,12 @@ dependencies = [
"zeroize",
]
[[package]]
name = "borrow-or-share"
version = "0.2.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "dc0b364ead1874514c8c2855ab558056ebfeb775653e7ae45ff72f28f8f3166c"
[[package]]
name = "bstr"
version = "1.13.1"
@ -114,6 +120,12 @@ version = "1.25.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "95832e849adfb21180ccb6826a99da14e5d266ae5c2e668e1602cf234f153797"
[[package]]
name = "bytes"
version = "1.12.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
[[package]]
name = "bzip2"
version = "0.6.1"
@ -232,6 +244,12 @@ dependencies = [
"cfg-if",
]
[[package]]
name = "crossbeam-utils"
version = "0.8.23"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a31eee39dddec8330830986fcd7625edb5a24ec90ea038215273bbc3adb08ac6"
[[package]]
name = "crypto-common"
version = "0.2.2"
@ -250,6 +268,20 @@ dependencies = [
"cmov",
]
[[package]]
name = "dashmap"
version = "6.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e6361d5c062261c78a176addb82d4c821ae42bed6089de0e12603cd25de2059c"
dependencies = [
"cfg-if",
"crossbeam-utils",
"hashbrown 0.14.5",
"lock_api",
"once_cell",
"parking_lot_core",
]
[[package]]
name = "deflate64"
version = "0.1.12"
@ -357,12 +389,70 @@ dependencies = [
"zlib-rs",
]
[[package]]
name = "fluent-uri"
version = "0.4.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "bc74ac4d8359ae70623506d512209619e5cf8f347124910440dbc221714b328e"
dependencies = [
"borrow-or-share",
"ref-cast",
"serde",
]
[[package]]
name = "futures"
version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9a31d2a3fbaaeb2af2368bbdd904aa8e812d3c04a1ee10d3171f52d556e5d0a3"
dependencies = [
"futures-channel",
"futures-core",
"futures-io",
"futures-sink",
"futures-task",
"futures-util",
]
[[package]]
name = "futures-channel"
version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b1f9e3d69d39e4862ffed03ed071a76f9a13ba1d9109d355b0f0aa6b15e393c4"
dependencies = [
"futures-core",
"futures-sink",
]
[[package]]
name = "futures-core"
version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e"
[[package]]
name = "futures-io"
version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "53c0fa8157de1303bfffdaa1cc2a673bfffb60102f76b0ef4441659124373fed"
[[package]]
name = "futures-macro"
version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9fb9654ba8355388abeb8dcb4fc62f511300867002afc858860463bdd9fe0c44"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.6",
]
[[package]]
name = "futures-sink"
version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1944426bf7d03f1d14f708785e4b33efd750b36d48a157b836b3efc15ede8e1d"
[[package]]
name = "futures-task"
version = "0.3.34"
@ -375,8 +465,13 @@ version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc"
dependencies = [
"futures-channel",
"futures-core",
"futures-io",
"futures-macro",
"futures-sink",
"futures-task",
"memchr",
"pin-project-lite",
"slab",
]
@ -412,6 +507,12 @@ dependencies = [
"regex-syntax",
]
[[package]]
name = "hashbrown"
version = "0.14.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1"
[[package]]
name = "hashbrown"
version = "0.17.1"
@ -433,6 +534,12 @@ dependencies = [
"digest",
]
[[package]]
name = "httparse"
version = "1.10.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"
[[package]]
name = "hybrid-array"
version = "0.4.15"
@ -536,7 +643,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cc4e190f5d26ca7051642629da2c52fc03bde85a03197c99408dcd291734c855"
dependencies = [
"equivalent",
"hashbrown",
"hashbrown 0.17.1",
]
[[package]]
@ -597,7 +704,9 @@ dependencies = [
"similar",
"tempfile",
"thiserror",
"tokio",
"toml 1.1.6+spec-1.1.0",
"tower-lsp-server",
"walkdir",
"zip",
]
@ -646,12 +755,34 @@ version = "0.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "47d9d19d1d6efa0109d2f65ff4c85cddd50bd572e5a00127ab10987290bcefae"
[[package]]
name = "lock_api"
version = "0.4.14"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "224399e74b87b5f3557511d98dff8b14089b3dadafcab6bb93eab67d3aace965"
dependencies = [
"scopeguard",
]
[[package]]
name = "log"
version = "0.4.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f9f8bd3e56ce4dfc153cf470fffbfa98c7620958b312ca5c3a4b8d5181fd13c6"
[[package]]
name = "ls-types"
version = "0.0.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "896e16b8e17d8732b9efe4d5b66cb0cc162b3023a2d8122f2aea6f7f185e0a67"
dependencies = [
"bitflags",
"fluent-uri",
"percent-encoding",
"serde",
"serde_json",
]
[[package]]
name = "lzma-rust2"
version = "0.16.5"
@ -739,6 +870,19 @@ version = "4.4.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "13c45bb4a6ae1280ec0803b1ef9d3455eb50f01efbbe1447ab020f1d54fba9d8"
[[package]]
name = "parking_lot_core"
version = "0.9.12"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1"
dependencies = [
"cfg-if",
"libc",
"redox_syscall",
"smallvec",
"windows-link",
]
[[package]]
name = "pbkdf2"
version = "0.13.0"
@ -749,6 +893,12 @@ dependencies = [
"hmac",
]
[[package]]
name = "percent-encoding"
version = "2.3.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
[[package]]
name = "pin-project-lite"
version = "0.2.17"
@ -808,6 +958,15 @@ version = "6.0.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
[[package]]
name = "redox_syscall"
version = "0.5.18"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
dependencies = [
"bitflags",
]
[[package]]
name = "redox_users"
version = "0.5.3"
@ -818,6 +977,26 @@ dependencies = [
"thiserror",
]
[[package]]
name = "ref-cast"
version = "1.0.27"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7e440fb4e4b4147295338efb76001ab9e4efc0e5839df2c47fc5ac2381d365c3"
dependencies = [
"ref-cast-impl",
]
[[package]]
name = "ref-cast-impl"
version = "1.0.27"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "92ecd8964f8453721699a1ed72037b0db49ce2f5a5138486ee89bed6f67cdf3a"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.6",
]
[[package]]
name = "regex"
version = "1.13.1"
@ -881,6 +1060,12 @@ dependencies = [
"winapi-util",
]
[[package]]
name = "scopeguard"
version = "1.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
[[package]]
name = "serde"
version = "1.0.229"
@ -1049,6 +1234,12 @@ dependencies = [
"unicode-ident",
]
[[package]]
name = "sync_wrapper"
version = "1.0.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0bf256ce5efdfa370213c1dabab5935a12e49f2c58d15e9eac2870d3b4f27263"
[[package]]
name = "synstructure"
version = "0.14.0"
@ -1144,6 +1335,41 @@ dependencies = [
"zerovec",
]
[[package]]
name = "tokio"
version = "1.53.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "202caea871b69668250d242070849eb495be178ed697a3e98aebce5bc81a0bed"
dependencies = [
"pin-project-lite",
"tokio-macros",
]
[[package]]
name = "tokio-macros"
version = "2.7.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "78773a2a397f451582ce068015985c33193cf6dea8b74d2a639fe457b2f07b0e"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.6",
]
[[package]]
name = "tokio-util"
version = "0.7.19"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "494815d09bf52b5548659851081238f0ca39ff638363907596da739561c62c52"
dependencies = [
"bytes",
"futures-core",
"futures-sink",
"libc",
"pin-project-lite",
"tokio",
]
[[package]]
name = "toml"
version = "0.8.23"
@ -1224,6 +1450,83 @@ version = "1.1.2+spec-1.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7d56353a2a665ad0f41a421187180aab746c8c325620617ad883a99a1cbe66d2"
[[package]]
name = "tower"
version = "0.5.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ebe5ef63511595f1344e2d5cfa636d973292adc0eec1f0ad45fae9f0851ab1d4"
dependencies = [
"futures-core",
"futures-util",
"pin-project-lite",
"sync_wrapper",
"tower-layer",
"tower-service",
]
[[package]]
name = "tower-layer"
version = "0.3.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "121c2a6cda46980bb0fcd1647ffaf6cd3fc79a013de288782836f6df9c48780e"
[[package]]
name = "tower-lsp-server"
version = "0.23.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2f0e711655c89181a6bc6a2cc348131fcd9680085f5b06b6af13427a393a6e72"
dependencies = [
"bytes",
"dashmap",
"futures",
"httparse",
"ls-types",
"memchr",
"serde",
"serde_json",
"tokio",
"tokio-util",
"tower",
"tracing",
]
[[package]]
name = "tower-service"
version = "0.3.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8df9b6e13f2d32c91b9bd719c00d1958837bc7dec474d94952798cc8e69eeec3"
[[package]]
name = "tracing"
version = "0.1.44"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
dependencies = [
"pin-project-lite",
"tracing-attributes",
"tracing-core",
]
[[package]]
name = "tracing-attributes"
version = "0.1.31"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.119",
]
[[package]]
name = "tracing-core"
version = "0.1.36"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
dependencies = [
"once_cell",
]
[[package]]
name = "typed-path"
version = "0.12.3"

View File

@ -35,7 +35,9 @@ serde_json = "1.0.151"
similar = "2.7.0"
tempfile = "3.27.0"
thiserror = "2.0.21"
tokio = { version = "1.53.1", default-features = false, features = ["io-std", "macros", "rt-multi-thread", "sync"] }
toml = "1.1.6"
tower-lsp-server = { version = "0.23.0", default-features = false, features = ["runtime-tokio"] }
walkdir = "2.5.0"
zip = "8.6.0"

View File

@ -13,6 +13,9 @@ the details needed to use, embed, and develop John Slop:
the versioned JSON Lines schema and partial-error records.
- [Architecture](architecture.md) describes module boundaries, shared domain
values, input safety, and the reusable library facade.
- [LSP framework and protocol decision](decisions/0003-lsp-framework-and-protocol.md)
records the selected server crate, stable protocol scope, and synchronization
assumptions.
- [Configuration](configuration.md) documents schema version 1, source
precedence, stable-ID merges, validation, and inspection commands.
- [Heuristics and confidence](heuristics.md) documents rule execution,

View File

@ -0,0 +1,54 @@
# ADR 0003: LSP framework and protocol contract
- Status: accepted
- 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 confidence 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.

View File

@ -187,7 +187,7 @@ first formatter milestone tag.
## Milestone 6 — LSP binary
- [ ] Select an actively maintained LSP framework after a short dependency/API
- [x] Select an actively maintained LSP framework after a short dependency/API
review (evaluate `tower-lsp-server`); pin the decision and protocol assumptions
in a decision record.
- [ ] Implement stdio initialization/shutdown and incremental or full document