john-slop/docs/usage.md

8.5 KiB

Usage

Detector

Run the detector over one or more paths:

cargo run --bin john-slop -- [--fail-score 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 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 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 for the formula and Limitations 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 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. The separate 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.

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;
  • --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:

john-slop-lsp
john-slop-lsp --config-name editorial
john-slop-lsp --config ./john-slop.toml
john-slop-lsp --diagnostics ./diagnostics.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 runs the same configured detector as the CLI and publishes every applicable heuristic finding. 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; 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.