diff --git a/README.md b/README.md index 2070df0..92c0fad 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,8 @@ source spans, apply path/content scopes, and feed a bounded, explainable confidence score. The detector renders source-highlighted human diagnostics, concise records, or versioned JSON Lines. The formatter applies only configured Unicode-to-ASCII replacements, supports check/diff modes, and requires explicit -opt-in for atomic file writes. The LSP is planned in [tasks.md](tasks.md). +opt-in for atomic file writes. The stdio LSP publishes those same replacement +findings and versioned quick fixes in editors without writing files. ## Quick start @@ -27,6 +28,7 @@ Rust 1.98.1 or newer is required. cargo run --bin john-slop -- path/to/document path/to/source-directory cargo run --bin john-slop-fmt -- path/to/document cargo run --bin john-slop-fmt -- --check path/to/document +cargo run --bin john-slop-lsp ``` Use `--fail-confidence 0..100` to make the detector exit with status `1` when a @@ -37,6 +39,11 @@ Formatter file mode prints transformed text without modifying the source. Use `--write` explicitly for atomic in-place replacement, or pipe editor buffers through `john-slop-fmt` over stdin/stdout. +Editors start `john-slop-lsp` over stdio. It tracks open snapshots with full +document synchronization, reports configured ASCII replacements, and offers +quick fixes whose result matches the formatter. See the editor guide for Helix +and Vim setup. + ## Documentation - [Runnable Rust examples](examples/README.md) diff --git a/docs/README.md b/docs/README.md index 376d4aa..2763bd7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,9 +6,9 @@ the details needed to use, embed, and develop John Slop: - [Runnable Rust examples](../examples/README.md) demonstrate in-memory analysis, streaming path input, and shared replacement planning. - [Usage](usage.md) documents accepted inputs, detector output, exit statuses, - and the current formatter/LSP status. -- [Editor setup](editors.md) provides Helix (`hx`) and Vim configuration for - the formatter and future LSP adapter, with current status caveats. + formatter modes, and the LSP protocol contract. +- [Editor setup](editors.md) provides working Helix (`hx`) and Vim formatter/LSP + configuration and validation steps. - [Output contracts](output.md) specifies human and concise presentation plus the versioned JSON Lines schema and partial-error records. - [Architecture](architecture.md) describes module boundaries, shared domain @@ -31,6 +31,5 @@ the details needed to use, embed, and develop John Slop: - [Decision records](decisions/) preserve durable product and engineering choices, including confidence semantics and input limits. -Future LSP and release-hardening contracts remain specified in -[tasks.md](../tasks.md) and [AGENTS.md](../AGENTS.md) until their implementation -milestones land. +Release-hardening contracts remain specified in [tasks.md](../tasks.md) and +[AGENTS.md](../AGENTS.md) until that milestone lands. diff --git a/docs/architecture.md b/docs/architecture.md index 2561638..42fc90d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -11,6 +11,7 @@ path -> input stream -> Document -> analysis -> Analysis + Finding -> diagnostic/output adapters -> replacement planner -> TextEdit -> applier -> formatter I/O + -> LSP UTF-16 edit ``` The main modules have deliberately narrow responsibilities: @@ -23,6 +24,8 @@ The main modules have deliberately narrow responsibilities: diagnostics; - `replacement` produces non-overlapping edits and validates/applies arbitrary edit sets without performing I/O; +- `lsp` indexes open snapshots, converts canonical byte spans to UTF-16 + coordinates, and implements replacement diagnostics and versioned quick fixes; - `model` contains presentation-neutral domain values; - `error` exposes typed input failures for library consumers; - `src/bin` contains the detector presentation/exit policy and formatter/LSP @@ -59,6 +62,15 @@ preflights every requested document before writing, then uses same-directory temporary files and preserves permissions. Archive mutation remains outside the library and adapter contract. +The LSP adapter owns no filesystem mutation. `tower-lsp-server` supplies stdio +JSON-RPC framing while `LspBackend` tracks authoritative open-document versions +behind asynchronous locks. Every publication is checked against the current +version after analysis so a replaced snapshot cannot overwrite newer results. +Configuration reload swaps only a fully validated model and republishes open +documents in deterministic URI order. See +[ADR 0003](decisions/0003-lsp-framework-and-protocol.md) for framework and +protocol choices. + See [ADR 0001](decisions/0001-core-analysis-contracts.md) for the foundational contracts and [ADR 0002](decisions/0002-input-policy-and-limits.md) for traversal and archive safety decisions. diff --git a/docs/editors.md b/docs/editors.md index f254d21..745bf54 100644 --- a/docs/editors.md +++ b/docs/editors.md @@ -1,8 +1,8 @@ # Editor setup -> **Current status:** `john-slop-fmt` is operational. `john-slop-lsp` remains an -> explicit Milestone 6 scaffold and returns an unsupported diagnostic when -> started without `--help`. +Both `john-slop-fmt` and `john-slop-lsp` are operational. The LSP publishes +configured ASCII-replacement warnings and versioned quick fixes; it does not +publish the broader heuristic confidence findings. Install all three binaries somewhere on `PATH`, then confirm the editor-facing help is available: @@ -85,10 +85,16 @@ if executable('john-slop-lsp') endif ``` -The plugin's `:LspStatus`, `:LspNextDiagnostic`, and `:LspCodeAction` commands -will expose server state, diagnostics, and replacement quick fixes once -Milestone 6 lands. The registration shape and `allowlist` follow the plugin's -current upstream documentation. +Use the plugin's `:LspStatus`, `:LspNextDiagnostic`, and `:LspCodeAction` +commands to inspect server state, move through replacement diagnostics, and +apply the ASCII quick fix. The registration shape and `allowlist` follow the +plugin's current upstream documentation. + +The server uses the same configuration layers as the other binaries. Add +`args = ["--config-name", "editorial"]` to the Helix language-server table, or +append those arguments to the Vim `cmd` list, when an editor-specific named +configuration is wanted. `--log-json` is available for troubleshooting and +writes lifecycle metadata to stderr without document contents. ## Try the shared fixtures diff --git a/docs/limitations.md b/docs/limitations.md index 3fca5eb..2bd67a8 100644 --- a/docs/limitations.md +++ b/docs/limitations.md @@ -70,8 +70,13 @@ violations are errors rather than clean results. Generated, vendor, dependency, and minified paths are skipped by default. The formatter handles strict UTF-8 files and configured ASCII replacements only; it does not rewrite ZIP-based containers, prose, or source structure. Recursive writes require explicit -`--write --recursive` and preflight the complete input set. The LSP remains a -scaffold for Milestone 6. +`--write --recursive` and preflight the complete input set. + +The LSP intentionally handles open editor snapshots only, uses full-document +synchronization, and publishes configured ASCII-replacement warnings rather +than the broader heuristic/confidence catalog. It does not read or write a +document URI, mutate archives, provide prose rewrites, or implement incremental +range changes. Configuration reload errors retain the last valid configuration. Analysis is local and performs no network lookup. Consequently, it cannot check citations, current facts, provenance, licensing, or similarity to external diff --git a/docs/usage.md b/docs/usage.md index e8a2415..4b5dfaa 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -71,9 +71,8 @@ planning. Run all example targets as part of the normal test matrix with Its [shared fixture manifest](../examples/fixtures/manifest.toml) pairs several `example.txt` inputs with expected detector rules, replacement counts, and -formatted output. The executable fixture test validates both the library and -the detector and formatter CLIs today; LSP integration tests will consume the -same corpus when that adapter is implemented. +formatted output. The executable fixture and protocol tests validate the +library, detector, formatter, and LSP against the shared replacement contract. ## Supported input policy @@ -122,7 +121,31 @@ individual UTF-8 file instead. ## LSP -Cargo exposes `john-slop-lsp` so packaging and CI exercise its target name, but -it remains an explicit Milestone 6 scaffold. Both adapter `--help` pages show -concise Helix and Vim setup; the complete snippets and validation workflow live -in [Editor setup](editors.md). +`john-slop-lsp` is a stdio Language Server Protocol 3.17 adapter. Editors launch +it without positional arguments: + +```sh +john-slop-lsp +john-slop-lsp --config-name editorial +john-slop-lsp --config ./john-slop.toml +``` + +The server advertises full-document synchronization and quick-fix code actions. +It stores only currently open UTF-8 snapshots, their URI, language ID, and +monotonically increasing version. On open or an accepted newer full-document +change it publishes warnings only for enabled Unicode-to-ASCII replacements. +Each diagnostic has source `john-slop`, a stable replacement-rule code, the +document version, and a UTF-16 range. Heuristic confidence findings are not +published by this initial server. + +Quick fixes are recomputed from the current snapshot with the shared replacement +planner and returned as versioned workspace edits. A request carrying stale John +Slop diagnostic metadata is rejected. Closing a document removes its snapshot +and publishes an empty diagnostic set. `workspace/didChangeConfiguration` +reloads the normal embedded, user, named, and explicit layers; a failed reload +keeps the last valid configuration. + +Stdout is reserved for JSON-RPC framing. The server is quiet by default; pass +`--log-json` to emit lifecycle-only JSON Lines to stderr. Those records contain +event metadata, URI, and version but never document contents. Complete Helix and +Vim setup and validation steps live in [Editor setup](editors.md). diff --git a/examples/README.md b/examples/README.md index 6895fe7..b1c98de 100644 --- a/examples/README.md +++ b/examples/README.md @@ -13,8 +13,8 @@ cargo run --example plan_replacements findings. - `analyze_path` streams a file, directory, or supported ZIP container. Its optional path defaults to `examples/fixtures`. -- `plan_replacements` prints the exact UTF-8 byte edits that the formatter and - LSP adapters will share. +- `plan_replacements` prints the exact UTF-8 byte edits shared by the formatter + and LSP quick fixes. These examples use embedded defaults so their behavior does not depend on a developer's user configuration. Applications that want normal configuration @@ -36,8 +36,10 @@ cargo run --bin john-slop-fmt -- examples/fixtures/typography/example.txt cargo run --bin john-slop-fmt -- --check examples/fixtures/clean/example.txt cargo run --example analyze_path -- examples/fixtures cargo test --test example_fixtures +cargo test --test lsp ``` -The formatter integration test now executes every case and compares stdout with -its expected ASCII file. The manifest also names `lsp` as a consumer so the -Milestone 6 protocol tests can reuse the same inputs and expected edits. +The formatter integration test executes every case and compares stdout with its +expected ASCII file. The manifest also names `lsp` as a consumer, and the +in-process protocol suite proves that applying LSP edits produces the same bytes +as the formatter. diff --git a/examples/plan_replacements.rs b/examples/plan_replacements.rs index b0cb051..956a519 100644 --- a/examples/plan_replacements.rs +++ b/examples/plan_replacements.rs @@ -1,4 +1,4 @@ -//! Inspect the edits shared by detector, formatter, and future LSP adapters. +//! Inspect the edits shared by detector, formatter, and LSP adapters. use john_slop::{Config, apply_replacements, plan_replacements}; diff --git a/src/bin/editor_help.rs b/src/bin/editor_help.rs index 05e7275..e275454 100644 --- a/src/bin/editor_help.rs +++ b/src/bin/editor_help.rs @@ -1,6 +1,6 @@ //! Shared editor-integration help for the formatter and LSP adapters. -pub const EDITOR_SETUP: &str = r#"EDITOR SETUP (fmt available; LSP planned for Milestone 6): +pub const EDITOR_SETUP: &str = r#"EDITOR SETUP (formatter and replacement LSP available): Helix ~/.config/helix/languages.toml: [language-server.john-slop] command = "john-slop-lsp"