81 lines
3.8 KiB
Markdown
81 lines
3.8 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.
|
|
|
|
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.
|
|
|
|
`--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`; `--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.
|