john-slop/examples/README.md

102 lines
4.4 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
cargo run --example ascii_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.
- `ascii_replacements` builds an opt-in catalog through the public API and maps
fullwidth characters to all 95 printable ASCII targets.
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, safe Unicode punctuation replacements, and diagnostic-only Unicode
lookalikes/invisibles. A Rust source example covers source-only rules. Each
input has a checked-in expected formatted result; the Unicode review fixture's
expected result is intentionally byte-identical because those findings do not
authorize rewriting.
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.
## Printable ASCII replacement showcase
[`ascii_replacements.rs`](ascii_replacements.rs) extends the embedded defaults
in memory with fullwidth mappings for ASCII `!` through `~` and maps ideographic
space to ASCII space. Its [Unicode input](ascii-replacement-showcase/fullwidth.txt)
and [expected output](ascii-replacement-showcase/ascii.txt) display all 95
printable ASCII targets in one place:
```sh
cargo run --example ascii_replacements
```
The example reports 95 planned edits on stderr and writes only the transformed
fixture to stdout. These broad letter, digit, punctuation, and space mappings
are an API/configuration demonstration, not additions to the production
defaults or a recommendation to rewrite arbitrary multilingual text. The
embedded catalog remains limited to individually reviewed conservative rules.
## Expected-failure diagnostic showcase
[`diagnostic-showcase.txt`](diagnostic-showcase.txt) contains every currently
shipped prose signal, while
[`diagnostic-showcase/source.rs`](diagnostic-showcase/source.rs) adds the
source-placeholder and tutorial-narration rules plus all ten embedded
replacement characters, a Cyrillic ASCII lookalike, a zero-width space, and a
right-to-left override. The adjacent example configuration promotes assistant
self-identification from warning to error and lifts the typography occurrence
cap for this display, making one run show Miette advice, warning, error,
fixable, and deliberately non-fixable Unicode diagnostics together:
```sh
cargo run --bin john-slop -- \
--config examples/diagnostic-showcase.toml \
--output miette --fail-level low \
examples/diagnostic-showcase.txt \
examples/diagnostic-showcase/source.rs
```
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 and representative prose/source categories rather than requiring
exact equality with an evolving catalog. Keeping new diagnostic kinds visible
here is nevertheless part of the intended maintenance workflow. Run the test
with capture disabled to print the complete report:
```sh
cargo test --test example_fixtures \
diagnostic_showcase_spans_prose_source_and_severities -- --nocapture
```