john-slop/docs/editors.md

4.3 KiB

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:

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:

[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:

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

Vim

Vim's native formatprg option is enough for formatting. Add this to ~/.vimrc:

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.

Classic Vim needs an LSP client plugin. With prabirshrestha/vim-lsp, register John Slop in ~/.vimrc:

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:

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.