95 lines
4.5 KiB
Markdown
95 lines
4.5 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
|
|
detector CLI today; formatter and LSP integration tests will consume the same
|
|
corpus when those adapters are 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 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. Both scaffolds accept `--help` and show concise Helix and Vim setup;
|
|
the complete snippets and validation workflow live in
|
|
[Editor setup](editors.md).
|