docs: add Helix and Vim adapter setup
This commit is contained in:
parent
65592760f3
commit
1bacd8a75d
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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 |
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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."#;
|
||||
|
|
@ -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"
|
||||
))
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
))
|
||||
|
|
|
|||
|
|
@ -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']"));
|
||||
}
|
||||
Loading…
Reference in New Issue