4.0 KiB
John Slop
John Slop is an early-stage, local-first heuristic linter for concrete signals of low-effort or insufficiently reviewed text and source code. It is intended to highlight evidence for human review, not to prove that content was written by AI or assign an authorship probability.
Current prototype
The repository currently contains proof-of-concept code that:
- streams UTF-8 text from a file or recursively from a directory;
- streams text entries from ZIP-based files, including
.zip,.docx,.xlsx, and.pptx; - rejects missing paths and invalid UTF-8 with a diagnostic error;
- detects a configured-in-code set of hyphen-like Unicode characters; and
- returns typed findings, edits, and bounded evidence confidence for those characters.
The temporary command-line entry point accepts one file, directory, or supported ZIP-based path and prints a summary per document. Its interface will be replaced by the planned Clap-based detector binary during Milestone 1.
Cargo exposes explicit john-slop, john-slop-fmt, and john-slop-lsp binary
targets. The formatter and LSP currently exit with an explanatory unsupported
message until their dedicated implementation milestones.
Run the detector over one or more paths with:
cargo run --bin john-slop -- [--fail-confidence 0..100] <PATH>...
The detector exits 0 below the selected threshold, 1 when any document meets
it, and 2 for invalid arguments or operational failures. Confidence describes
configured evidence, not an AI-authorship probability.
Reusable consumers should call the library facade: load_config,
analyze_source, plan_replacements, and read_inputs. Replacement planning is
pure and shares the exact resolved configuration used by analysis.
Input iteration yields a separate result per document, so a bad directory entry
does not discard successfully read siblings.
Reads enforce the resource limits in
ADR 0002, including bounded
file/member sizes, archive expansion and compression ratios, entry counts,
directory depth, safe member paths, strict UTF-8, and NUL-byte rejection.
Library input failures are typed InputError variants. Executable boundaries
attach operation context and render them with miette; library consumers do not
need to parse presentation strings.
The implementation is being restructured into a reusable library plus detector,
formatter, and LSP binaries. See tasks.md for the ordered backlog and
AGENTS.md for the design and contribution rules.
Architecture and product choices are recorded under
docs/decisions, beginning with the
core analysis contracts.
The default traversal, text-recognition, and archive safety policy is specified
in ADR 0002.
Development
Run the current test and quality suite with:
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features
cargo doc --no-deps
Behavior is intentionally captured with regression tests before the refactor so that later changes are deliberate and reviewable.
Detector spans use zero-based UTF-8 byte offsets. Presentation layers will convert those canonical offsets to terminal or LSP coordinates at their boundaries.
The minimum supported Rust version (MSRV) is 1.88. CI checks both the MSRV and the current stable toolchain against the committed dependency lockfile. Linux is the currently exercised platform; support for other platforms will be declared only after CI coverage is added.
John Slop is distributed under the MIT license.