docs: publish release-ready usage and config samples

This commit is contained in:
Dandaedre 2026-09-29 17:26:47 +02:00
parent e42169da3d
commit a67ee320e7
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
8 changed files with 155 additions and 4 deletions

View File

@ -20,11 +20,14 @@ 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.
## Quick start
## 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
@ -45,6 +48,36 @@ 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)
@ -55,6 +88,7 @@ and Vim setup.
- [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)

View File

@ -18,6 +18,8 @@ the details needed to use, embed, and develop John Slop:
assumptions.
- [Configuration](configuration.md) documents schema version 1, source
precedence, stable-ID merges, validation, and inspection commands.
- [Commented configuration examples](../examples/config/) provide user-wide and
named partial overlays ready to copy.
- [Heuristics and confidence](heuristics.md) documents rule execution,
applicability, evidence damping, normalization, and score interpretation.
- [Evaluation corpus](evaluation.md) records fixture provenance, per-rule

View File

@ -32,6 +32,9 @@ files are optional; a selected explicit file must exist.
The current `schema_version` is `1`. The complete defaults and documented record
examples live in [`assets/config.toml`](../assets/config.toml) and
[`assets/heuristics.toml`](../assets/heuristics.toml).
Ready-to-copy, commented partial layers live in
[`examples/config`](../examples/config/): `config.toml` demonstrates a user-wide
base and `editorial.toml` demonstrates a named overlay.
Replacement and heuristic arrays merge by stable `id`. A partial record changes
only the supplied fields:
@ -56,6 +59,10 @@ layer, invalid regular expressions or globs, unsafe matchers, non-ASCII
replacement targets, and invalid thresholds are fatal configuration
diagnostics.
Set `enabled = false` on a known rule or replacement ID to disable it. Because
records merge by ID, do not copy the full embedded table merely to change one
field; a later partial record preserves every unspecified value.
Replacement `source` values are non-empty Unicode strings containing at least
one non-ASCII byte; `replacement` values are non-empty ASCII strings. Sources
must be unique. When enabled sources share a prefix, the longest matching source

15
examples/config/README.md Normal file
View File

@ -0,0 +1,15 @@
# Commented configuration examples
Copy [`config.toml`](config.toml) to the platform path printed by
`john-slop config paths` for user-wide policy. Copy [`editorial.toml`](editorial.toml)
beside it and select it with `--config-name editorial` for a named overlay.
Both are deliberately partial. Embedded defaults remain active for fields and
stable IDs they do not mention. Inspect the exact merged result before enforcing
it:
```sh
john-slop config show --config-name editorial
```
Project-local policy can use either file with `--config path/to/file.toml`.

View File

@ -0,0 +1,30 @@
# User-wide base layer. `schema_version` is optional in overlays, but spelling
# it out makes compatibility expectations explicit.
schema_version = 1
[input]
# Bound each decoded document to 4 MiB for this installation.
max_document_bytes = 4194304
[thresholds]
# Confidence bands affect labels and `--fail-level`; they are not probabilities.
low = 20
medium = 50
high = 75
# Arrays merge by stable ID. A known ID needs only the fields being changed.
[[replacements]]
id = "em-dash"
# Keep typographic em dashes instead of offering an ASCII replacement.
enabled = false
[[rules]]
id = "templated-conclusion"
# Disable a rule that is unsuitable for the user's normal documents.
enabled = false
[[rules]]
id = "source-placeholder-todo"
# Severity changes presentation; weight changes confidence contribution.
severity = "error"
weight = 15.0

View File

@ -0,0 +1,28 @@
# Named overlay selected with `--config-name editorial`. It is applied after the
# user-wide config.toml and before an explicit `--config` file.
[thresholds]
low = 15
medium = 40
high = 70
[[rules]]
id = "templated-filler"
weight = 2.0
# Scope is one value, so supplied arrays replace the embedded scope arrays.
[[rules]]
id = "assistant-self-identification"
[rules.scope]
content = ["prose"]
extensions = ["md", "txt"]
include = ["articles/**", "docs/**"]
exclude = ["docs/quoted-transcripts/**"]
skip_generated = true
skip_vendor = true
skip_minified = true
[[replacements]]
id = "en-dash"
enabled = false

View File

@ -213,10 +213,10 @@ same config.
## Milestone 7 — Hardening, documentation, and release
- [ ] Replace the placeholder README with installation, threat model, examples,
- [x] Replace the placeholder README with installation, threat model, examples,
configuration precedence/schema, rule authoring, confidence interpretation,
CLI/formatter/LSP setup, exit codes, privacy, and limitations.
- [ ] Publish commented sample base and named configs. Document how to disable a
- [x] Publish commented sample base and named configs. Document how to disable a
rule/replacement and how merge-by-ID works.
- [ ] Add CI on the supported OS/MSRV matrix for formatting, Clippy, tests, docs,
audit/deny checks, and fixture/golden consistency.

View File

@ -1,6 +1,9 @@
use std::{collections::BTreeSet, fs, path::Path, process::Command};
use john_slop::{AnalysisContext, Config, Detector, apply_replacements, plan_replacements};
use john_slop::{
AnalysisContext, Config, ConfigLoader, ConfigPaths, Detector, apply_replacements,
plan_replacements,
};
use serde::Deserialize;
#[derive(Debug, Deserialize)]
@ -162,3 +165,35 @@ fn diagnostic_showcase_is_an_expected_threshold_failure() {
#[cfg(feature = "fancy-diagnostics")]
assert!(stdout.contains("╭─["));
}
#[test]
fn commented_base_and_named_configs_form_a_valid_layered_example() {
let root = Path::new(env!("CARGO_MANIFEST_DIR")).join("examples/config");
let config = ConfigLoader::from_paths(ConfigPaths {
directory: root.clone(),
base: root.join("config.toml"),
named: Some(root.join("editorial.toml")),
explicit: None,
})
.load()
.expect("load commented sample layers");
assert_eq!(config.input.max_document_bytes, 4_194_304);
assert_eq!(config.thresholds.low, 15);
assert_eq!(config.thresholds.medium, 40);
assert_eq!(config.thresholds.high, 70);
assert!(
!config
.replacements
.iter()
.find(|replacement| replacement.id == "em-dash")
.expect("embedded replacement remains present")
.enabled
);
let rule = config
.rules
.iter()
.find(|rule| rule.id == "assistant-self-identification")
.expect("embedded rule remains present");
assert_eq!(rule.scope.include, vec!["articles/**", "docs/**"]);
}