docs: publish LSP usage guides
This commit is contained in:
parent
dcae1b1b06
commit
2f12c4e186
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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};
|
||||
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
Loading…
Reference in New Issue