3.8 KiB
Usage
Detector
Run the detector over one or more paths:
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 for the formula and Limitations 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
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.
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.