john-slop/docs/architecture.md

45 lines
1.9 KiB
Markdown

# Architecture
John Slop keeps detection and replacement behavior in a library. Executables are
thin adapters responsible for argument parsing, presentation, and process exit
statuses.
The current flow is:
```text
path -> input stream -> Document -> analysis -> Analysis + Finding
-> replacement planner -> TextEdit
```
The main modules have deliberately narrow responsibilities:
- `config` owns the validated embedded replacement catalog and input limits;
- `input` streams files, directory entries, and archive members as documents;
- `detector` produces explainable findings and bounded confidence;
- `replacement` produces non-overlapping edits without performing I/O;
- `model` contains presentation-neutral domain values;
- `error` exposes typed input failures for library consumers;
- `src/bin` contains the detector and the formatter/LSP adapters.
All source spans are zero-based UTF-8 byte ranges into the exact analyzed source
snapshot. Presentation layers will convert those canonical spans to terminal or
UTF-16 LSP coordinates at their boundaries. Archive sources retain both their
outer path and inner member identity.
## Public facade
The crate root exposes four entry points:
- `load_config` resolves the configuration embedded in the current build;
- `read_inputs` returns a streaming iterator of per-document results;
- `analyze_source` returns findings and evidence confidence for UTF-8 text;
- `plan_replacements` returns safe edits against the same source snapshot.
Configuration files and precedence layers are a later milestone. Keeping these
operations behind the facade lets those layers evolve without duplicating logic
across the three binaries.
See [ADR 0001](decisions/0001-core-analysis-contracts.md) for the foundational
contracts and [ADR 0002](decisions/0002-input-policy-and-limits.md) for traversal
and archive safety decisions.