john-slop/README.md

90 lines
4.0 KiB
Markdown

# 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:
```sh
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](docs/decisions/0002-input-policy-and-limits.md), 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](tasks.md) for the ordered backlog and
[AGENTS.md](AGENTS.md) for the design and contribution rules.
Architecture and product choices are recorded under
[`docs/decisions`](docs/decisions/), beginning with the
[core analysis contracts](docs/decisions/0001-core-analysis-contracts.md).
The default traversal, text-recognition, and archive safety policy is specified
in [ADR 0002](docs/decisions/0002-input-policy-and-limits.md).
## Development
Run the current test and quality suite with:
```sh
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](LICENSE).
## Background reading
- [Wikipedia: Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia%3ASigns_of_AI_writing)
- [Wikipedia: WikiProject AI Cleanup](https://en.wikipedia.org/wiki/Wikipedia:WikiProject_AI_Cleanup)
- [The Verge: Wikipedia editors are battling AI slop](https://www.theverge.com/report/756810/wikipedia-ai-slop-policies-community-speedy-deletion)