docs: publish release-ready usage and config samples
This commit is contained in:
parent
e42169da3d
commit
a67ee320e7
36
README.md
36
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 `<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)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
4
tasks.md
4
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.
|
||||
|
|
|
|||
|
|
@ -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/**"]);
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue