110 lines
6.0 KiB
Markdown
110 lines
6.0 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. The default publication filter retains only Unicode
|
|
findings; explicit all-diagnostic and minimum-weight modes expose broader
|
|
findings, 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.
|