126 lines
4.6 KiB
Markdown
126 lines
4.6 KiB
Markdown
# John Slop
|
|
|
|

|
|

|
|

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