# Usage ## Detector Run the detector over one or more paths: ```sh cargo run --bin john-slop -- [--fail-score 0..100] ... 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 miette`, `--output concise`, or `--output json`. Miette is the default and uses colored Unicode graphical source annotations when the default `fancy-diagnostics` feature is enabled. Its marked rule-code titles stay attached to their messages, while an empty line separates complete diagnostics; it falls back to human mode without that feature. Human mode renders uncolored 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: 2`, 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 evidence-score threshold; - `1`: at least one document reaches the threshold; - `2`: arguments are invalid or an operational/input error prevents completion. `--fail-score 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. The old `--fail-confidence` spelling remains a visible alias for migration. 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. The low-care evidence score summarizes observable configured evidence. It is not an AI-authorship probability. See [Heuristics and evidence scoring](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`; repeat `--diagnostics FILE` to load runtime rule catalogs without recompilation. 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. The LSP publishes Unicode findings by default. Start `john-slop-lsp` with `--all-diagnostics` to publish the complete configured detector catalog, or use `--minimum-diagnostic-weight WEIGHT` to retain Unicode findings and add only non-Unicode findings at or above that weight. This editor-only filter does not change CLI analysis, evidence scores, replacement planning, or formatting. ## 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 and protocol tests validate the library, detector, formatter, and LSP against the shared replacement contract. The separate [expected-failure diagnostic showcase](../examples/README.md#expected-failure-diagnostic-showcase) prints every current prose finding in graphical Miette form and intentionally exits `1` when its low evidence threshold is reached. ## 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 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: ```sh 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`; - `--check` emits nothing and exits `1` when any replacement is needed; - `--diff` emits a unified diff and exits `1` when any replacement is needed; - `--write` emits nothing and atomically replaces changed files, exiting `0`; - 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`, `--config FILE`, and repeatable `--diagnostics FILE` select those layers. Diagnostic rules do not change the formatter's replacement plan, but catalog validation stays consistent across all adapters. 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: ```sh john-slop-lsp john-slop-lsp --config-name editorial john-slop-lsp --config ./john-slop.toml john-slop-lsp --diagnostics ./diagnostics.toml john-slop-lsp --all-diagnostics john-slop-lsp --minimum-diagnostic-weight 10 ``` 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 runs the same configured detector as the CLI and publishes every applicable Unicode finding. `--all-diagnostics` publishes the complete result; `--minimum-diagnostic-weight WEIGHT` adds only non-Unicode findings meeting the threshold. File URI extensions select prose/source and path scopes; editor language IDs provide the prose/source fallback for untitled or extensionless buffers. Each diagnostic has source `john-slop`, the stable heuristic rule ID as its code, the configured severity and remediation text, document-version metadata, and an exact UTF-16 range. Advice maps to LSP information, while warning and error retain their corresponding LSP severities. Runtime catalog rules are reloaded by `workspace/didChangeConfiguration` together with normal configuration. Quick fixes remain intentionally narrower than diagnostics: they are recomputed from the current snapshot with the shared replacement planner and returned only for findings carrying safe configured ASCII edits. Style, prompt-leakage, and source-review findings are diagnostic-only. 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, recompiles the detector, and republishes every open snapshot under the unchanged visibility filter; a failed reload keeps the last valid configuration and detector. 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](editors.md).