john-slop/README.md

126 lines
4.6 KiB
Markdown

# John Slop
![version](https://assets.dandaedre.com/coverage/idle-org/john-slop/main/version.svg)
![tests](https://assets.dandaedre.com/coverage/idle-org/john-slop/main/test.svg)
![test coverage](https://assets.dandaedre.com/coverage/idle-org/john-slop/main/coverage.svg)
John Slop is a local-first linter for concrete signs of low-effort or
insufficiently reviewed text and source code. It reports explainable evidence
for human review; it does not prove AI authorship or identify a model.
## Quickstart
With `cargo-binstall` available, install all three prebuilt binaries from the
latest release candidate:
```sh
cargo binstall --git https://proxy.dandaedre.com/gitea/idle-org/john-slop \
john-slop
```
To build from source, Rust 1.98.1 or newer is required. Install from the
upstream Git repository:
```sh
cargo install --git https://proxy.dandaedre.com/gitea/idle-org/john-slop \
--locked --all-features
```
Or install a checkout from its repository root:
```sh
cargo install --path . --locked --all-features
```
Scan a document or source directory:
```sh
john-slop path/to/document path/to/source-directory
```
Generate a commented `config.toml` in the current directory, then edit category
or individual-rule switches as needed:
```sh
john-slop config init
john-slop config init-diagnostics
```
The second command creates a runtime rule catalog: exact-phrase and regex
diagnostics can then be added without changing or recompiling the program.
Diagnostics are colored Miette reports by default. Make the command fail when a
document reaches a chosen low-care evidence score with `--fail-score 0..100`:
```sh
john-slop --fail-score 40 path/to/document
```
Preview configured Unicode-to-ASCII replacements, or check them in automation:
```sh
john-slop-fmt path/to/document
john-slop-fmt --check path/to/document
```
Formatting is read-only unless `--write` is explicit. Start the editor server
with `john-slop-lsp`; the [editor guide](docs/editors.md) has ready-to-use Helix
and Vim configuration.
## Overview
John Slop provides three binaries backed by the same configuration and source
spans:
- `john-slop` detects copied assistant scaffolding, generic style residue,
source placeholders, tutorial narration, configured replacements, ASCII-like
Unicode, and invisible or bidirectional controls.
- `john-slop-fmt` previews, checks, or explicitly applies configured ASCII
replacements, including the default printable-ASCII UTS #39 profile.
- `john-slop-lsp` publishes Unicode diagnostics over stdio by default, offers
explicit weighted or all-diagnostic opt-ins, provides quick fixes for safe
replacements, and formats without writing editor-owned files.
The detector accepts UTF-8 files, directories, ZIP archives, and common
ZIP-based office documents. Each finding includes its source span, stable rule
ID, severity, message, and remediation help. A bounded evidence score aggregates
configured signals; it is not the probability that AI wrote the content.
Analysis is local and deterministic, with no network requests or telemetry.
False positives remain possible—especially in transcripts, tutorials,
multilingual text, and intentional typography—so findings are prompts for
review, not verdicts. Projects with multilingual text should consider the
Unicode profile's non-mutating `review` mode before writing formatted output.
## Learn progressively
Start with the guide closest to what you want to do:
1. [Use the CLI and understand exit statuses](docs/usage.md).
2. [Read or integrate the available output formats](docs/output.md).
3. [Configure rules, replacements, and layered overrides](docs/configuration.md),
with [commented configuration examples](examples/config/).
4. [Run the Rust and expected-failure examples](examples/README.md).
5. [Connect the formatter and LSP to Helix or Vim](docs/editors.md).
6. [Understand the review-signal methodology](docs/review-signals.md), the
[heuristics and evidence score](docs/heuristics.md), and then the
[interpretation limits](docs/limitations.md).
The [documentation index](docs/README.md) offers the same guided path with a
little more context.
## Advanced topics
Architecture, the public library API, evaluation results, performance,
dependency policy, design decisions, Unicode research, development, and release
engineering are collected in the [advanced guide](docs/advanced.md).
## Project
See [CONTRIBUTING.md](CONTRIBUTING.md) to work on the project and
[SECURITY.md](SECURITY.md) to report a vulnerability. The ordered implementation
plan lives in [tasks.md](tasks.md), and agent contribution rules live in
[AGENTS.md](AGENTS.md).
John Slop is distributed under the [MIT license](LICENSE).