185 lines
9.2 KiB
Markdown
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).
|