2.7 KiB
ADR 0004: Supported Cargo workspace
- Status: accepted
- Date: 2026-09-29
Context
The crate-boundary experiment extracted reusable analysis/configuration/input
code into john-slop-core and LSP protocol state into john-slop-lsp, leaving
the root john_slop package as a compatibility facade and binary distribution.
Cold core and no-LSP builds used roughly 35–55% less CPU and disk, while LSP and
whole-project builds were effectively unchanged. The experiment initially
recommended waiting because three publishable packages require synchronized
versions, ordered publication, workspace-aware CI, and clear asset ownership.
The project has now chosen to offer the reusable package boundary and accepts that release overhead. Repeating package metadata and dependency versions in three manifests would make that overhead unnecessarily error-prone.
Decision
Adopt the three-package layout as the supported architecture:
john-slop-coreowns embedded catalogs and reusable synchronous domain logic;john-slop-lspdepends on core and owns protocol state/conversion;- root
john_slopremains the compatibility facade and owns all three binaries.
Keep the root manifest as both a package and the workspace root. Moving its sources under another directory solely to create a virtual manifest adds path, fixture, and packaging churn without changing the dependency graph.
Centralize shared version, edition, MSRV, license, repository, dependency requirements, and lint policy in the root workspace tables. Every member inherits them. Dependency feature activation and optionality remain in member manifests: workspace inheritance must not cause the core package to compile Tokio/LSP dependencies or make the facade's LSP stack unconditional.
Keep all three packages as default members so existing root quality commands cover the whole workspace. Enforce membership, synchronized resolved versions, inheritance, and feature isolation with an integration test. Assemble packages with Cargo's workspace packaging command and publish in dependency order: core, LSP, then facade.
Consequences
- Core/no-LSP consumers retain the measured lean dependency graph.
- Existing
john_slopAPI paths and binary names remain compatible by default. - Shared requirements have one update point, while member feature choices stay reviewable at their point of use.
- Full builds gain no material speedup from the boundary.
- A release coordinates three matching package versions. Before matching
dependency versions exist in the registry, package assembly uses
--no-verify; registry-form verification follows publication. - Embedded catalog changes belong to
john-slop-core, and workspace coverage, CI, dependency review, and packaging remain permanent maintenance costs.