john-slop/docs/usage.md

53 lines
2.2 KiB
Markdown

# Usage
## Detector
Run the detector over one or more paths:
```sh
cargo run --bin john-slop -- [--fail-confidence 0..100] <PATH>...
```
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.
The current human-readable output contains the source identity, bounded evidence
confidence, and finding count. Findings cover the embedded or overridden
heuristic catalog and retain exact UTF-8 byte spans for later presentation.
Source-highlighted `miette` diagnostics are planned for the next milestone.
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.
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`; `--max-document-bytes BYTES` is the current highest-precedence input
override. 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.
## 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 and LSP
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.