john-slop/docs/architecture.md

6.0 KiB

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:

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 TextEdits become code actions. Document formatting calls the same replacement planner directly and never derives mutations from diagnostics. See ADR 0003 for framework and protocol choices.

See ADR 0001 for the foundational contracts and ADR 0002 for traversal and archive safety decisions.