56 lines
2.5 KiB
Markdown
56 lines
2.5 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
|
|
```
|
|
|
|
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 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.
|
|
|
|
`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.
|
|
|
|
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.
|