diff --git a/.run_status.toml b/.run_status.toml index 9353dba..8d2f72f 100644 --- a/.run_status.toml +++ b/.run_status.toml @@ -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 diff --git a/README.md b/README.md index 6eaf608..d8a72dd 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/badges/coverage.svg b/badges/coverage.svg index 538dc80..4acc2bf 100644 --- a/badges/coverage.svg +++ b/badges/coverage.svg @@ -1 +1 @@ -test-coverage: 76%test-coverage76% \ No newline at end of file +test-coverage: 77%test-coverage77% \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index b1241c5..5a028a0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 diff --git a/docs/editors.md b/docs/editors.md new file mode 100644 index 0000000..6cd9dbf --- /dev/null +++ b/docs/editors.md @@ -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 +``` diff --git a/docs/usage.md b/docs/usage.md index 9cb8974..04cd2bb 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -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). diff --git a/src/bin/editor_help.rs b/src/bin/editor_help.rs new file mode 100644 index 0000000..33ec0c1 --- /dev/null +++ b/src/bin/editor_help.rs @@ -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."#; diff --git a/src/bin/john-slop-fmt.rs b/src/bin/john-slop-fmt.rs index 031eb3d..c97b751 100644 --- a/src/bin/john-slop-fmt.rs +++ b/src/bin/john-slop-fmt.rs @@ -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" )) diff --git a/src/bin/john-slop-lsp.rs b/src/bin/john-slop-lsp.rs index d92608c..9048a5a 100644 --- a/src/bin/john-slop-lsp.rs +++ b/src/bin/john-slop-lsp.rs @@ -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" )) diff --git a/tests/adapter_help.rs b/tests/adapter_help.rs new file mode 100644 index 0000000..7a08948 --- /dev/null +++ b/tests/adapter_help.rs @@ -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']")); +}