From a67ee320e70e502b8f8b88ce33e24759b6941af9 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Tue, 29 Sep 2026 17:26:47 +0200 Subject: [PATCH] docs: publish release-ready usage and config samples --- README.md | 36 ++++++++++++++++++++++++++++++++- docs/README.md | 2 ++ docs/configuration.md | 7 +++++++ examples/config/README.md | 15 ++++++++++++++ examples/config/config.toml | 30 +++++++++++++++++++++++++++ examples/config/editorial.toml | 28 +++++++++++++++++++++++++ tasks.md | 4 ++-- tests/example_fixtures.rs | 37 +++++++++++++++++++++++++++++++++- 8 files changed, 155 insertions(+), 4 deletions(-) create mode 100644 examples/config/README.md create mode 100644 examples/config/config.toml create mode 100644 examples/config/editorial.toml diff --git a/README.md b/README.md index 859b4e3..e6532c8 100644 --- a/README.md +++ b/README.md @@ -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 `.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) diff --git a/docs/README.md b/docs/README.md index abd50a8..0fa49d2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 diff --git a/docs/configuration.md b/docs/configuration.md index 308b335..28ff883 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -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 diff --git a/examples/config/README.md b/examples/config/README.md new file mode 100644 index 0000000..1a97e69 --- /dev/null +++ b/examples/config/README.md @@ -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`. diff --git a/examples/config/config.toml b/examples/config/config.toml new file mode 100644 index 0000000..36c23da --- /dev/null +++ b/examples/config/config.toml @@ -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 diff --git a/examples/config/editorial.toml b/examples/config/editorial.toml new file mode 100644 index 0000000..bf463e3 --- /dev/null +++ b/examples/config/editorial.toml @@ -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 diff --git a/tasks.md b/tasks.md index 813fac8..a6487b0 100644 --- a/tasks.md +++ b/tasks.md @@ -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. diff --git a/tests/example_fixtures.rs b/tests/example_fixtures.rs index 7231ae9..831542c 100644 --- a/tests/example_fixtures.rs +++ b/tests/example_fixtures.rs @@ -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/**"]); +}