129 lines
5.9 KiB
Markdown
129 lines
5.9 KiB
Markdown
# Usage
|
|
|
|
## Detector
|
|
|
|
Run the detector over one or more paths:
|
|
|
|
```sh
|
|
cargo run --bin john-slop -- [--fail-confidence 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 concise`, or `--output json`.
|
|
Human mode renders 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: 1`, 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 confidence threshold;
|
|
- `1`: at least one document reaches the threshold;
|
|
- `2`: arguments are invalid or an operational/input error prevents completion.
|
|
|
|
`--fail-confidence 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.
|
|
|
|
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.
|
|
|
|
Confidence is a summary of observable configured evidence. It is not an
|
|
AI-authorship probability. See [Heuristics and confidence](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`; 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.
|
|
|
|
## 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 test validates both the library and
|
|
the detector and formatter CLIs today; LSP integration tests will consume the
|
|
same corpus when that adapter is implemented.
|
|
|
|
## 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` and `--config FILE` select those layers.
|
|
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
|
|
|
|
Cargo exposes `john-slop-lsp` so packaging and CI exercise its target name, but
|
|
it remains an explicit Milestone 6 scaffold. Both adapter `--help` pages show
|
|
concise Helix and Vim setup; the complete snippets and validation workflow live
|
|
in [Editor setup](editors.md).
|