108 lines
5.1 KiB
Markdown
108 lines
5.1 KiB
Markdown
# John Slop
|
|
|
|

|
|

|
|

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