3.1 KiB
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:
path -> input stream -> Document -> analysis -> Analysis + Finding
-> diagnostic/output adapters
-> replacement planner -> TextEdit -> applier
-> formatter I/O
The main modules have deliberately narrow responsibilities:
configowns the validated embedded replacement catalog and input limits;inputstreams files, directory entries, and archive members as documents;detectorcompiles configured matchers and path scopes once, then produces explainable findings and bounded confidence;diagnosticbinds findings to exact named snapshots as typedmiettediagnostics;replacementproduces non-overlapping edits and validates/applies arbitrary edit sets without performing I/O;modelcontains presentation-neutral domain values;errorexposes typed input failures for library consumers;src/bincontains 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_configresolves the configuration embedded in the current build;read_inputsreturns a streaming iterator of per-document results;read_stdinreturns one bounded strict-UTF-8 standard-input document;analyze_sourcereturns findings and evidence confidence for UTF-8 text;plan_replacementsreturns safe edits against the same source snapshot;apply_replacementsvalidates 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 for the foundational contracts and ADR 0002 for traversal and archive safety decisions.