docs: publish LSP usage guides

This commit is contained in:
Dandaedre 2026-09-29 17:14:04 +02:00
parent dcae1b1b06
commit 2f12c4e186
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
9 changed files with 84 additions and 30 deletions

View File

@ -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)

View File

@ -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.

View File

@ -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.

View File

@ -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

View File

@ -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

View File

@ -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).

View File

@ -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.

View File

@ -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};

View File

@ -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"