john-slop/docs/architecture.md

65 lines
3.1 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
-> diagnostic/output adapters
-> replacement planner -> TextEdit -> applier
-> formatter I/O
```
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` compiles configured matchers and path scopes once, then produces
explainable findings and bounded confidence;
- `diagnostic` binds findings to exact named snapshots as typed `miette`
diagnostics;
- `replacement` produces non-overlapping edits and validates/applies arbitrary
edit sets without performing I/O;
- `model` contains presentation-neutral domain values;
- `error` exposes typed input failures for library consumers;
- `src/bin` contains the detector presentation/exit policy and 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. Rule applicability uses the member path
so language and path filters behave the same inside and outside archives.
## Public facade
The crate root exposes core entry points and presentation-neutral types:
- `load_config` resolves the configuration embedded in the current build;
- `read_inputs` returns a streaming iterator of per-document results;
- `read_stdin` returns one bounded strict-UTF-8 standard-input document;
- `analyze_source` returns findings and evidence confidence for UTF-8 text;
- `plan_replacements` returns safe edits against the same source snapshot;
- `apply_replacements` validates boundaries and overlap, then applies edits in
descending byte order while borrowing no-op input unchanged.
`FindingDiagnostic` is the library bridge to `miette`; CLI-specific concise and
JSON rendering stays in the detector adapter so it cannot alter analysis.
`ConfigLoader` applies embedded, user base, named user, explicit file, and CLI
layers in order. Stable-ID merging and semantic validation happen before a
configuration reaches analysis. Keeping these operations behind the facade
avoids duplicating policy across the three binaries.
The formatter adapter owns filesystem mutation. It resolves configuration and
preflights every requested document before writing, then uses same-directory
temporary files and preserves permissions. Archive mutation remains outside the
library and adapter contract.
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.