john-slop/docs/architecture.md

109 lines
5.9 KiB
Markdown

# Architecture
John Slop is a workspace with a compatibility facade and two reusable libraries.
Executables remain 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
-> LSP UTF-16 edit
```
The crate boundary separates dependency families:
- `john-slop-core` owns configuration, input, detection, diagnostics,
replacement planning, and presentation-neutral domain values;
- `john-slop-lsp` owns asynchronous editor state and protocol conversion while
depending only on `john-slop-core`;
- the root `john_slop` package re-exports both libraries to preserve its public
API and distributes the detector, formatter, and LSP binaries.
The root manifest is intentionally both a package and the workspace root. A
virtual manifest would relocate the compatibility facade, binaries, examples,
and fixtures without improving dependency isolation. `[workspace.package]`,
`[workspace.dependencies]`, and `[workspace.lints]` provide one source of truth
for shared release metadata, dependency requirements, and first-party unsafe
code policy. Member manifests retain only package-specific descriptions,
dependency selections, feature activation, and optionality. In particular, the
workspace Tokio requirement enables no features: the LSP library selects
`sync`, and the root LSP adapter selects its runtime and stdio features.
The modules within those crates retain deliberately narrow responsibilities:
- `config` owns validated embedded defaults, restricted runtime diagnostic
catalogs, the generated Unicode policy, 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 a bounded low-care evidence score;
- `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;
- `unicode_review` pins the UTS #39 ASCII-skeleton version and Gitea-compatible
invisible/control ranges; generated printable-ASCII mappings feed the shared
replacement planner while controls remain non-mutating;
- `lsp` indexes open snapshots, runs the compiled detector, converts canonical
finding and replacement spans to UTF-16 coordinates, and implements
versioned quick fixes plus whole-document formatting;
- `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 root compatibility facade and `john-slop-core` expose the same 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 an evidence score 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 catalogs, runtime diagnostic catalogs, 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. Runtime catalogs are declarative: they can add rules using existing
matcher implementations but cannot load executable code.
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.
The LSP adapter owns no filesystem mutation. `tower-lsp-server` supplies stdio
JSON-RPC framing while `LspBackend` tracks authoritative open-document versions
behind asynchronous locks. Every publication is checked against the current
version after analysis so a replaced snapshot cannot overwrite newer results.
Configuration reload swaps only a fully validated model and republishes open
documents in deterministic URI order. The detector is compiled once per
resolved configuration rather than once per edit. File URI paths drive normal
scope applicability; language IDs supply source/prose context for untitled or
extensionless buffers. All findings become diagnostics, while only findings
with core `TextEdit`s become code actions. Document formatting calls the same
replacement planner directly and never derives mutations from diagnostics. See
[ADR 0003](decisions/0003-lsp-framework-and-protocol.md) for framework and
protocol choices.
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.