john-slop/README.md

3.7 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.

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.

Background reading