docs: add Helix and Vim adapter setup

This commit is contained in:
Dandaedre 2026-09-29 16:36:12 +02:00
parent 65592760f3
commit 1bacd8a75d
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
10 changed files with 206 additions and 6 deletions

View File

@ -1,8 +1,8 @@
[last_run_clean]
run_status = "Success"
lines_parsed = 211
coverage = 76.1
lines_parsed = 242
coverage = 76.72
[last_run_clean.run_duration]
secs = 16
nanos = 510511933
secs = 18
nanos = 765260395

View File

@ -35,6 +35,7 @@ signals, not the probability that AI wrote the content.
- [Runnable Rust examples](examples/README.md)
- [Documentation index](docs/README.md)
- [Command-line usage and current capabilities](docs/usage.md)
- [Helix and Vim formatter/LSP setup](docs/editors.md)
- [Human, concise, and JSON output contracts](docs/output.md)
- [Architecture and public library API](docs/architecture.md)
- [Layered configuration](docs/configuration.md)

View File

@ -1 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="122" height="18" role="img" aria-label="test-coverage: 76%"><title>test-coverage: 76%</title><linearGradient id="bms-ec87f8807b558adf" x2="0" y2="100%"><stop offset="0" stop-color="#fff" stop-opacity=".7"/><stop offset=".1" stop-color="#aaa" stop-opacity=".1"/><stop offset=".9" stop-color="#000" stop-opacity=".3"/><stop offset="1" stop-color="#000" stop-opacity=".5"/></linearGradient><clipPath id="bmr-ec87f8807b558adf"><rect width="122" height="18" rx="4" fill="#fff"/></clipPath><g clip-path="url(#bmr-ec87f8807b558adf)"><rect width="87" height="18" fill="#555"/><rect x="87" width="35" height="18" fill="#97ca00"/><rect width="122" height="18" fill="url(#bms-ec87f8807b558adf)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="445" y="140" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="770">test-coverage</text><text x="445" y="130" transform="scale(.1)" fill="#fff" textLength="770">test-coverage</text><text aria-hidden="true" x="1035" y="140" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="250">76%</text><text x="1035" y="130" transform="scale(.1)" fill="#fff" textLength="250">76%</text></g></svg>
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="122" height="18" role="img" aria-label="test-coverage: 77%"><title>test-coverage: 77%</title><linearGradient id="bms-1641980536081ca4" x2="0" y2="100%"><stop offset="0" stop-color="#fff" stop-opacity=".7"/><stop offset=".1" stop-color="#aaa" stop-opacity=".1"/><stop offset=".9" stop-color="#000" stop-opacity=".3"/><stop offset="1" stop-color="#000" stop-opacity=".5"/></linearGradient><clipPath id="bmr-1641980536081ca4"><rect width="122" height="18" rx="4" fill="#fff"/></clipPath><g clip-path="url(#bmr-1641980536081ca4)"><rect width="87" height="18" fill="#555"/><rect x="87" width="35" height="18" fill="#97ca00"/><rect width="122" height="18" fill="url(#bms-1641980536081ca4)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="445" y="140" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="770">test-coverage</text><text x="445" y="130" transform="scale(.1)" fill="#fff" textLength="770">test-coverage</text><text aria-hidden="true" x="1035" y="140" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="250">77%</text><text x="1035" y="130" transform="scale(.1)" fill="#fff" textLength="250">77%</text></g></svg>

Before

Width:  |  Height:  |  Size: 1.3 KiB

After

Width:  |  Height:  |  Size: 1.3 KiB

View File

@ -7,6 +7,8 @@ the details needed to use, embed, and develop John Slop:
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 LSP adapter contracts, with current scaffold caveats.
- [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

105
docs/editors.md Normal file
View File

@ -0,0 +1,105 @@
# Editor setup
> **Current status:** these configurations are ready for the adapter contracts,
> but `john-slop-fmt` and `john-slop-lsp` are still explicit scaffolds. The
> formatter becomes operational in Milestone 5 and the language server in
> Milestone 6. Until then, both return an unsupported diagnostic when started
> without `--help`.
Install all three binaries somewhere on `PATH`, then confirm the editor-facing
help is available:
```sh
john-slop-fmt --help
john-slop-lsp --help
```
## Helix (`hx` / `helix-term`)
Helix configures formatters and language servers in `languages.toml`. Put this
in `~/.config/helix/languages.toml` on Linux, or in `.helix/languages.toml` for
project-local configuration:
```toml
[language-server.john-slop]
command = "john-slop-lsp"
[[language]]
name = "john-slop-text"
language-id = "plaintext"
scope = "text.john-slop"
file-types = ["txt"]
formatter = { command = "john-slop-fmt" }
language-servers = ["john-slop"]
auto-format = false
```
This complete custom language entry makes the repository's `example.txt`
fixtures useful without depending on a built-in plain-text grammar. Use
`:format` to run the formatter. Set `auto-format = true` only if save-time
replacement is wanted after Milestone 5.
For an existing language, merge John Slop into that language's entry rather
than replacing its useful defaults. For example, Rust should retain
`rust-analyzer`:
```toml
[[language]]
name = "rust"
formatter = { command = "john-slop-fmt" }
language-servers = ["rust-analyzer", "john-slop"]
```
Run `hx --health rust` (or the selected language name) to confirm both binaries
are visible. Helix documents that a formatter reads the buffer from stdin and
writes it to stdout, while an LSP command must be on `PATH`; those are the
contracts the two John Slop milestones target. See the official
[Helix language configuration reference](https://docs.helix-editor.com/languages.html).
## Vim
Vim's native `formatprg` option is enough for formatting. Add this to
`~/.vimrc`:
```vim
augroup john_slop_format
autocmd!
autocmd BufRead,BufNewFile *.txt setfiletype text
autocmd FileType text,markdown,rust setlocal formatprg=john-slop-fmt
augroup END
```
Use `gggqG` to filter the whole buffer through the formatter, or select a range
and press `gq`. Vim requires `formatprg` programs to read stdin and write stdout;
see the official [`formatprg` and `gq` help](https://vimhelp.org/options.txt.html#%27formatprg%27).
Classic Vim needs an LSP client plugin. With
[`prabirshrestha/vim-lsp`](https://github.com/prabirshrestha/vim-lsp), register
John Slop in `~/.vimrc`:
```vim
if executable('john-slop-lsp')
au User lsp_setup call lsp#register_server({
\ 'name': 'john-slop',
\ 'cmd': {server_info->['john-slop-lsp']},
\ 'allowlist': ['text', 'markdown', 'rust'],
\ })
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.
## Try the shared fixtures
Open `examples/fixtures/typography/example.txt` in either editor. Its expected
formatter result is the adjacent `formatted.txt`; the shared manifest records
three replacements and one typography rule. The CLI is usable now for a
baseline:
```sh
cargo run --bin john-slop -- --output concise \
examples/fixtures/typography/example.txt
```

View File

@ -89,4 +89,6 @@ Cargo already exposes `john-slop-fmt` and `john-slop-lsp` so packaging and CI
exercise their target names. Both are explicit scaffolds today and return an
unsupported diagnostic. Replacement planning is available through the library;
file-writing formatter behavior and the stdio language server arrive in later
milestones.
milestones. Both scaffolds accept `--help` and show concise Helix and Vim setup;
the complete snippets and validation workflow live in
[Editor setup](editors.md).

27
src/bin/editor_help.rs Normal file
View File

@ -0,0 +1,27 @@
//! Shared editor-integration help for the formatter and LSP adapters.
pub const EDITOR_SETUP: &str = r#"EDITOR SETUP (fmt: Milestone 5; LSP: Milestone 6):
Helix ~/.config/helix/languages.toml:
[language-server.john-slop]
command = "john-slop-lsp"
[[language]]
name = "john-slop-text"
language-id = "plaintext"
scope = "text.john-slop"
file-types = ["txt"]
formatter = { command = "john-slop-fmt" }
language-servers = ["john-slop"]
Vim ~/.vimrc formatter (use gggqG for the whole buffer):
autocmd BufRead,BufNewFile *.txt setfiletype text
autocmd FileType text,markdown,rust setlocal formatprg=john-slop-fmt
Vim ~/.vimrc LSP (requires prabirshrestha/vim-lsp):
au User lsp_setup call lsp#register_server({
\ 'name': 'john-slop',
\ 'cmd': {server_info->['john-slop-lsp']},
\ 'allowlist': ['text', 'markdown', 'rust'],
\ })
See docs/editors.md for installation, existing-language setup, and validation."#;

View File

@ -1,8 +1,23 @@
//! Formatter command-line adapter scaffold.
#[path = "editor_help.rs"]
mod editor_help;
use clap::Parser;
use miette::{Result, miette};
/// Replace configured Unicode punctuation with safe ASCII equivalents.
#[derive(Debug, Parser)]
#[command(
name = "john-slop-fmt",
version,
about,
after_help = editor_help::EDITOR_SETUP
)]
struct Cli {}
fn main() -> Result<()> {
let _cli = Cli::parse();
Err(miette!(
"john-slop-fmt is not implemented yet; replacement planning is available through the library"
))

View File

@ -1,8 +1,23 @@
//! Language-server adapter scaffold.
#[path = "editor_help.rs"]
mod editor_help;
use clap::Parser;
use miette::{Result, miette};
/// Publish John Slop replacement diagnostics and quick fixes over stdio.
#[derive(Debug, Parser)]
#[command(
name = "john-slop-lsp",
version,
about,
after_help = editor_help::EDITOR_SETUP
)]
struct Cli {}
fn main() -> Result<()> {
let _cli = Cli::parse();
Err(miette!(
"john-slop-lsp is not implemented yet; LSP support is planned for Milestone 6"
))

33
tests/adapter_help.rs Normal file
View File

@ -0,0 +1,33 @@
use std::process::{Command, Output};
fn help(binary: &str) -> Output {
Command::new(binary)
.arg("--help")
.output()
.expect("run adapter help")
}
#[test]
fn formatter_help_contains_helix_and_vim_setup() {
let output = help(env!("CARGO_BIN_EXE_john-slop-fmt"));
let stdout = String::from_utf8(output.stdout).expect("UTF-8 formatter help");
assert!(output.status.success());
assert!(output.stderr.is_empty());
assert!(stdout.contains("Helix ~/.config/helix/languages.toml"));
assert!(stdout.contains("formatter = { command = \"john-slop-fmt\" }"));
assert!(stdout.contains("setlocal formatprg=john-slop-fmt"));
}
#[test]
fn lsp_help_contains_helix_and_vim_setup() {
let output = help(env!("CARGO_BIN_EXE_john-slop-lsp"));
let stdout = String::from_utf8(output.stdout).expect("UTF-8 LSP help");
assert!(output.status.success());
assert!(output.stderr.is_empty());
assert!(stdout.contains("[language-server.john-slop]"));
assert!(stdout.contains("command = \"john-slop-lsp\""));
assert!(stdout.contains("lsp#register_server"));
assert!(stdout.contains("['john-slop-lsp']"));
}