7.0 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.
Findings cover the embedded or overridden heuristic catalog and retain exact UTF-8 byte spans through every output mode. See Output contracts 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 for the formula and Limitations 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 for
the schema and merge rules.
Rust examples
The examples directory 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 pairs several
example.txt inputs with expected detector rules, replacement counts, and
formatted output. The executable fixture and protocol tests validate the
library, detector, formatter, and LSP against the shared replacement contract.
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
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:
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; --checkemits nothing and exits1when any replacement is needed;--diffemits a unified diff and exits1when any replacement is needed;--writeemits nothing and atomically replaces changed files, exiting0;- 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
john-slop-lsp is a stdio Language Server Protocol 3.17 adapter. Editors launch
it without positional arguments:
john-slop-lsp
john-slop-lsp --config-name editorial
john-slop-lsp --config ./john-slop.toml
The server advertises full-document synchronization and quick-fix code actions.
It stores only currently open UTF-8 snapshots, their URI, language ID, and
monotonically increasing version. On open or an accepted newer full-document
change it publishes warnings only for enabled Unicode-to-ASCII replacements.
Each diagnostic has source john-slop, a stable replacement-rule code, the
document version, and a UTF-16 range. Heuristic confidence findings are not
published by this initial server.
Quick fixes are recomputed from the current snapshot with the shared replacement
planner and returned as versioned workspace edits. A request carrying stale John
Slop diagnostic metadata is rejected. Closing a document removes its snapshot
and publishes an empty diagnostic set. workspace/didChangeConfiguration
reloads the normal embedded, user, named, and explicit layers; a failed reload
keeps the last valid configuration.
Stdout is reserved for JSON-RPC framing. The server is quiet by default; pass
--log-json to emit lifecycle-only JSON Lines to stderr. Those records contain
event metadata, URI, and version but never document contents. Complete Helix and
Vim setup and validation steps live in Editor setup.