john-slop/examples/README.md

70 lines
2.7 KiB
Markdown

# Runnable Rust examples
These Cargo examples exercise the same library boundaries used by the three
John Slop binaries:
```sh
cargo run --example analyze_text
cargo run --example analyze_path -- examples/fixtures
cargo run --example plan_replacements
```
- `analyze_text` analyzes an in-memory prose snapshot and prints its explainable
findings.
- `analyze_path` streams a file, directory, or supported ZIP container. Its
optional path defaults to `examples/fixtures`.
- `plan_replacements` prints the exact UTF-8 byte edits shared by the formatter
and LSP quick fixes.
These examples use embedded defaults so their behavior does not depend on a
developer's user configuration. Applications that want normal configuration
layering should call `john_slop::load_config()` instead.
## Shared fixture corpus
[`fixtures/manifest.toml`](fixtures/manifest.toml) describes small inputs shared
by detector CLI, formatter, and LSP testing. Several directories deliberately
contain an `example.txt`, covering clean prose, copied assistant residue, stock
style, and Unicode punctuation. A Rust source example covers source-only rules.
Each input has a checked-in expected formatted result.
Exercise the currently implemented boundaries with:
```sh
cargo run --bin john-slop -- --output concise examples/fixtures/assistant/example.txt
cargo run --bin john-slop-fmt -- examples/fixtures/typography/example.txt
cargo run --bin john-slop-fmt -- --check examples/fixtures/clean/example.txt
cargo run --example analyze_path -- examples/fixtures
cargo test --test example_fixtures
cargo test --test lsp
```
The formatter integration test executes every case and compares stdout with its
expected ASCII file. The manifest also names `lsp` as a consumer, and the
in-process protocol suite proves that applying LSP edits produces the same bytes
as the formatter.
## Expected-failure diagnostic showcase
[`diagnostic-showcase.txt`](diagnostic-showcase.txt) deliberately contains every
kind of currently shipped prose signal. Its adjacent example configuration
promotes assistant self-identification from warning to error, making one run
show Miette advice, warning, and error diagnostics together:
```sh
cargo run --bin john-slop -- \
--config examples/diagnostic-showcase.toml \
--output miette --fail-level low \
examples/diagnostic-showcase.txt
```
That command is expected to exit with status `1`: reaching the configured
threshold is the behavior under demonstration. The repository test asserts the
nonzero result rather than making the suite red. Run it with capture disabled to
print the complete report:
```sh
cargo test --test example_fixtures \
diagnostic_showcase_is_an_expected_threshold_failure -- --nocapture
```