john-slop/docs/usage.md

185 lines
9.2 KiB
Markdown

# Usage
## Detector
Run the detector over one or more paths:
```sh
cargo run --bin john-slop -- [--fail-score 0..100] <PATH>...
cargo run --bin john-slop -- --stdin [--stdin-filename article.md]
```
Each path may be a UTF-8 text file, a directory, a ZIP archive, or a supported
ZIP-based office document (`.docx`, `.xlsx`, or `.pptx`). Directory traversal and
archive reading stream one result at a time, so callers do not need to retain an
entire input tree in memory.
`--stdin` reads one bounded strict UTF-8 document from standard input. Supply
`--stdin-filename PATH` when extension, language, and path scopes should use a
virtual filename. Standard input can be analyzed alongside filesystem paths.
Repeat `--ignore GLOB` to skip matching file or archive-member paths. Resource
limits can be overridden with `--max-document-bytes`, `--max-archive-bytes`,
`--max-expanded-bytes`, `--max-archive-entries`,
`--max-compression-ratio`, and `--max-walk-depth`.
Select output with `--output human`, `--output miette`, `--output concise`, or
`--output json`. Miette is the default and uses colored Unicode graphical source
annotations when the default `fancy-diagnostics` feature is enabled. Its marked
rule-code titles stay attached to their messages, while an empty line separates
complete diagnostics; it falls
back to human mode without that feature. Human mode renders uncolored plain
source excerpts, exact labels, remediation help, and a summary. Concise mode
emits stable single-line finding and summary records. JSON mode emits one object
per analyzed document with `schema_version: 2`, summary fields, exact byte spans,
and every finding. Machine modes never emit ANSI escapes or logs on stdout.
Findings cover the embedded or overridden heuristic catalog and retain exact
UTF-8 byte spans through every output mode. See [Output contracts](output.md)
for the human/concise formats and complete JSON Lines schema.
Exit statuses are stable:
- `0`: every analyzed document is below the requested evidence-score threshold;
- `1`: at least one document reaches the threshold;
- `2`: arguments are invalid or an operational/input error prevents completion.
`--fail-score SCORE` selects an exact inclusive score threshold and
defaults to 100. `--fail-level low|medium|high` instead uses the corresponding
threshold from the fully resolved configuration. The two options are mutually
exclusive. The old `--fail-confidence` spelling remains a visible alias for
migration.
Input failures are isolated per document whenever iteration can continue. Valid
documents still emit all findings, while any partial input failure makes the
final status `2` (taking precedence over threshold status `1`). Human and
concise input errors go to stderr. JSON mode emits versioned `input-error`
records on stdout alongside `analysis` records and leaves stderr empty unless a
fatal setup failure prevents the output contract from starting.
The low-care evidence score summarizes observable configured evidence. It is
not an AI-authorship probability. See [Heuristics and evidence scoring](heuristics.md) for
the formula and [Limitations](limitations.md) before using thresholds in review
workflows.
Configuration layers can be selected with `--config-name NAME` and `--config
FILE`; repeat `--diagnostics FILE` to load runtime rule catalogs without
recompilation. Command-line resource limits are the highest-precedence input overrides.
Use `john-slop config show` to print the resolved TOML and `john-slop config
paths` to inspect source precedence. See [Configuration](configuration.md) for
the schema and merge rules.
The LSP publishes Unicode findings by default. Start `john-slop-lsp` with
`--all-diagnostics` to publish the complete configured detector catalog, or use
`--minimum-diagnostic-weight WEIGHT` to retain Unicode findings and add only
non-Unicode findings at or above that weight. This editor-only filter does not
change CLI analysis, evidence scores, replacement planning, or formatting.
## Rust examples
The [`examples` directory](../examples/README.md) contains runnable Cargo
examples for direct text analysis, streaming path input, and replacement edit
planning. Run all example targets as part of the normal test matrix with
`cargo test --examples --all-features`.
Its [shared fixture manifest](../examples/fixtures/manifest.toml) pairs several
`example.txt` inputs with expected detector rules, replacement counts, and
formatted output. The executable fixture and protocol tests validate the
library, detector, formatter, and LSP against the shared replacement contract.
The separate [expected-failure diagnostic showcase](../examples/README.md#expected-failure-diagnostic-showcase)
prints every current prose finding in graphical Miette form and intentionally
exits `1` when its low evidence threshold is reached.
## Supported input policy
Input reads use strict UTF-8 and reject NUL-containing text. They do not follow
symlinks by default. Limits on files, walk depth, archive entries, expanded
bytes, compression ratio, and member paths protect analysis from unbounded or
unsafe input. The exact policy is recorded in
[ADR 0002](decisions/0002-input-policy-and-limits.md).
## Formatter
With no path, `john-slop-fmt` reads one bounded strict-UTF-8 document from stdin
and writes only formatted bytes to stdout. With a file path, the default remains
read-only and prints the transformed file without changing it:
```sh
john-slop-fmt < article.txt > article.ascii.txt
john-slop-fmt article.txt
john-slop-fmt --check article.txt
john-slop-fmt --diff article.txt
john-slop-fmt --write article.txt
```
The modes are mutually exclusive:
- default mode emits formatted text and exits `0`;
- `--check` emits nothing and exits `1` when any replacement is needed;
- `--diff` emits a unified diff and exits `1` when any replacement is needed;
- `--write` emits nothing and atomically replaces changed files, exiting `0`;
- argument, configuration, UTF-8, input, or write failures exit `2`.
All modes use the same embedded/user/named/explicit configuration precedence as
the detector. `--config-name NAME`, `--config FILE`, and repeatable
`--diagnostics FILE` select those layers. Diagnostic rules do not change the
formatter's replacement plan, but catalog validation stays consistent across
all adapters.
Replacement sources use deterministic longest-match semantics, and formatting
twice is byte-for-byte identical to formatting once.
Directories require `--recursive`, and recursive operation is deliberately
limited to `--check --recursive` or `--write --recursive`. Before a recursive
write, every input is read, decoded, planned, and edit-validated; a failure
prevents all writes. Changed files use a temporary file in the same directory,
copy original permissions, sync content, and replace by rename where the
platform supports it. Files needing no edit are never rewritten.
ZIP, DOCX, XLSX, and PPTX mutation is not supported. Extract and format an
individual UTF-8 file instead.
## LSP
`john-slop-lsp` is a stdio Language Server Protocol 3.17 adapter. Editors launch
it without positional arguments:
```sh
john-slop-lsp
john-slop-lsp --config-name editorial
john-slop-lsp --config ./john-slop.toml
john-slop-lsp --diagnostics ./diagnostics.toml
john-slop-lsp --all-diagnostics
john-slop-lsp --minimum-diagnostic-weight 10
```
The server advertises full-document synchronization and quick-fix code actions.
It stores only currently open UTF-8 snapshots, their URI, language ID, and
monotonically increasing version. On open or an accepted newer full-document
change it runs the same configured detector as the CLI and publishes every
applicable Unicode finding. `--all-diagnostics` publishes the complete result;
`--minimum-diagnostic-weight WEIGHT` adds only non-Unicode findings meeting the
threshold. File URI extensions select prose/source and path scopes; editor
language IDs provide the prose/source fallback for untitled or extensionless
buffers.
Each diagnostic has source `john-slop`, the stable heuristic rule ID as its
code, the configured severity and remediation text, document-version metadata,
and an exact UTF-16 range. Advice maps to LSP information, while warning and
error retain their corresponding LSP severities.
Runtime catalog rules are reloaded by
`workspace/didChangeConfiguration` together with normal configuration. Quick
fixes remain intentionally narrower than diagnostics: they are recomputed
from the current snapshot with the shared replacement planner and returned only
for findings carrying safe configured ASCII edits. Style, prompt-leakage, and
source-review findings are diagnostic-only. A request carrying stale John Slop
diagnostic metadata is rejected. Closing a document removes its snapshot and
publishes an empty diagnostic set. `workspace/didChangeConfiguration` reloads
the normal embedded, user, named, and explicit layers, recompiles the detector,
and republishes every open snapshot under the unchanged visibility filter; a failed reload keeps the last valid
configuration and detector.
Stdout is reserved for JSON-RPC framing. The server is quiet by default; pass
`--log-json` to emit lifecycle-only JSON Lines to stderr. Those records contain
event metadata, URI, and version but never document contents. Complete Helix and
Vim setup and validation steps live in [Editor setup](editors.md).