john-slop/README.md

108 lines
5.1 KiB
Markdown

# John Slop
![version](badges/version.svg)
![tests](badges/test.svg)
![test coverage](badges/coverage.svg)
John Slop is an early-stage, local-first linter for concrete signs of low-effort
or insufficiently reviewed text and source code. It reports explainable
heuristics for human review; it does not prove AI authorship or identify a
model.
Today, the detector reads UTF-8 files, directories, ZIP archives, and common
ZIP-based office documents. Eleven conservative, configurable rules cover
copied assistant scaffolding, generic style residue, source-code placeholders,
tutorial narration, and configured non-ASCII characters. Rules retain exact
source spans, apply path/content scopes, and feed a bounded, explainable
confidence score. The detector renders plain or graphical Miette diagnostics,
concise records, or versioned JSON Lines. The formatter applies only configured
Unicode-to-ASCII replacements, supports check/diff modes, and requires explicit
opt-in for atomic file writes. The stdio LSP publishes those same replacement
findings and versioned quick fixes in editors without writing files.
## Install and quick start
Rust 1.98.1 or newer is required.
```sh
cargo install --git https://git.dandaedre.com/idle-org/john_slop \
--locked --all-features
cargo run --bin john-slop -- path/to/document path/to/source-directory
cargo run --bin john-slop -- --output miette path/to/document
cargo run --bin john-slop-fmt -- path/to/document
cargo run --bin john-slop-fmt -- --check path/to/document
cargo run --bin john-slop-lsp
```
Use `--fail-confidence 0..100` to make the detector exit with status `1` when a
document reaches a chosen evidence threshold. Confidence measures configured
signals, not the probability that AI wrote the content.
Formatter file mode prints transformed text without modifying the source. Use
`--write` explicitly for atomic in-place replacement, or pipe editor buffers
through `john-slop-fmt` over stdin/stdout.
Editors start `john-slop-lsp` over stdio. It tracks open snapshots with full
document synchronization, reports configured ASCII replacements, and offers
quick fixes whose result matches the formatter. See the editor guide for Helix
and Vim setup.
## What it reports
John Slop looks for configured, reviewable evidence such as copied assistant
scaffolding, knowledge-cutoff disclaimers, stock filler, unfinished source-code
placeholders, tutorial narration, and Unicode punctuation covered by the ASCII
replacement catalog. Every result includes the matching source span, rule ID,
severity, message, and remediation help.
The confidence score aggregates those configured signals. It is not an
AI-authorship probability, and a clean result does not prove human authorship or
good quality. Legitimate transcripts, tutorials, multilingual text, and
typographic punctuation can match. Review the source context before acting.
## Configuration and operation
Configuration precedence is embedded defaults, platform user `config.toml`, an
optional named `<name>.toml`, explicit `--config`, then CLI flags. Replacement
and heuristic tables merge by stable ID. Commented [base and named sample
configs](examples/config/) demonstrate disabling entries and overriding rules.
The detector accepts files, directories, stdin, ZIPs, and ZIP-based office
documents. Its stable exit statuses are `0` below the selected threshold, `1`
at or above it, and `2` for usage, configuration, or input failure. The
formatter is read-only unless `--write` is explicit; the LSP never writes files.
Analysis is local, deterministic, and makes no network request or telemetry
submission. Input text appears only in process memory and requested output.
Archive limits, strict UTF-8 handling, and non-followed symlinks constrain
untrusted inputs, but John Slop is not a sandbox or malware scanner.
## Documentation
- [Runnable Rust examples](examples/README.md)
- [Expected-failure Miette diagnostic showcase](examples/README.md#expected-failure-diagnostic-showcase)
- [Documentation index](docs/README.md)
- [Command-line usage and current capabilities](docs/usage.md)
- [Helix and Vim formatter/LSP setup](docs/editors.md)
- [Human, Miette, concise, and JSON output contracts](docs/output.md)
- [Architecture and public library API](docs/architecture.md)
- [Layered configuration](docs/configuration.md)
- [Commented base and named configuration examples](examples/config/)
- [Heuristics, confidence, and applicability](docs/heuristics.md)
- [Evaluation corpus and current metrics](docs/evaluation.md)
- [Limitations and responsible interpretation](docs/limitations.md)
- [Development, tests, features, and coverage](docs/development.md)
- [Performance benchmarks](docs/benchmarks.md)
- [Dependency and binary review](docs/dependencies.md)
- [Design decision records](docs/decisions/)
- [Contributing](CONTRIBUTING.md), [security](SECURITY.md), and
[release procedure](docs/releasing.md)
- [Background reading](docs/background.md)
- [Ambiguous and invisible Unicode data sources](docs/unicode-confusables.md)
The ordered implementation plan lives in [tasks.md](tasks.md), and contribution
rules live in [AGENTS.md](AGENTS.md).
John Slop is distributed under the [MIT license](LICENSE).