john-slop/docs/editors.md

121 lines
4.3 KiB
Markdown

# Editor setup
Both `john-slop-fmt` and `john-slop-lsp` are operational. The LSP publishes all
applicable configured heuristic findings, including prompt leakage, repeated
transitions, source placeholders, tutorial narration, and typography. Safe
ASCII-replacement findings additionally provide versioned quick fixes.
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.
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
```
Use the plugin's `:LspStatus`, `:LspNextDiagnostic`, and `:LspCodeAction`
commands to inspect server state, move through heuristic diagnostics, and apply
available ASCII quick fixes. 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
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. Compare detector and formatter
output with:
```sh
cargo run --bin john-slop -- --output concise \
examples/fixtures/typography/example.txt
cargo run --bin john-slop-fmt -- \
examples/fixtures/typography/example.txt
```
For non-fixable heuristic diagnostics, open
`examples/fixtures/style/example.txt` to see `repeated-transition` and other
style findings, or `examples/fixtures/source/example.rs` to see source-only
placeholder and narration findings alongside typography. Advice maps to LSP
information, warnings to warnings, and configured errors to errors. Every
diagnostic carries its stable heuristic rule ID as the code and includes the
configured remediation text.