5.0 KiB
Crate-boundary experiment
Status: adopted for Milestone 13. The experiment originally recommended waiting because full builds do not improve and three publishable packages add release coordination. The project subsequently chose to support the reusable package boundary and accepted those measured costs; the durable policy is in ADR 0004.
Candidate design
The experiment keeps the root john-slop package as a compatibility facade and
binary distribution. It moves reusable analysis into john-slop-core, moves
protocol state into john-slop-lsp, and makes the facade's LSP dependency
optional behind the default-enabled lsp feature. Existing default API paths
and executable names remain intact.
The embedded catalogs live with john-slop-core, which makes that package
self-contained. Workspace default members include all three packages so the
existing unqualified quality commands continue to cover them.
Method
Baseline commit c12b6b8 (v0.1.11) and the experimental branch were
checked in separate worktrees. Each cold command used an empty, dedicated
CARGO_TARGET_DIR; dependency sources and the operating-system file cache were
warm. Timings are one directional sample rather than a statistical benchmark.
Artifact size is the resulting target directory size reported by du -sh.
Environment: Rust/Cargo 1.100.0-nightly from 2026-09-15, x86-64 Linux, 32 logical
CPUs. Commands used --locked; the full checks used all targets and features.
Results
| Scenario | Baseline wall / CPU | Candidate wall / CPU | Baseline / candidate artifacts |
|---|---|---|---|
| Reusable core | 7.51s / 29.96s¹ | 3.82s / 13.56s | 256 / 116 MiB¹ |
| Root library, no defaults | 7.51s / 29.96s | 4.09s / 19.04s | 256 / 158 MiB |
| Formatter, no defaults | 6.98s / 29.50s | 4.28s / 19.19s | 244 / 160 MiB |
| LSP | 7.92s / 30.13s | 6.97s / 29.66s | 243 / 244 MiB |
| Whole project | 7.90s / 49.68s | 7.73s / 50.69s | 415 / 416 MiB |
| No-change library check | 0.043s wall | 0.036s wall | not material |
¹ The single-crate baseline has no isolated core target, so its library result is the nearest comparison.
The useful changes are therefore concentrated in non-LSP builds:
- the directly consumable core uses about 55% less CPU and disk and 49% less wall time than the former monolithic library check;
- the compatibility library without default features uses about 36% less CPU, 38% less disk, and 46% less wall time;
- the formatter without default features uses about 35% less CPU and disk and 39% less wall time;
- LSP, full-project, and no-change incremental costs are effectively unchanged.
Tarpaulin still reports 92.19% (1,334/1,447 lines) with workspace coverage, so the boundary neither gains nor loses measured test coverage.
Gains
- Async protocol dependencies no longer enter core or no-LSP builds.
- The module ownership matches the conceptual detector/LSP boundary.
- A future library consumer can depend on
john-slop-corewithout CLI, JSON, diff, Tokio, or LSP dependencies. - The root facade avoids a forced source migration for default-feature users.
Costs and risks
- One package and manifest become three, with synchronized versions and the publish order core → LSP → facade.
- The embedded catalogs must move into the core package, changing repository paths and release ownership.
- Coverage and CI must remain workspace-aware.
john_slop::lspis unavailable when default features are disabled; this is a feature-contract change even though default builds are compatible.- Ordinary default and full-project builds receive no material speedup, and runtime behavior and performance do not improve.
Original recommendation and adoption
Do not merge this branch while John Slop is primarily distributed as one set of three binaries and has no demonstrated external core-library consumers. The measured savings are real but apply only when deliberately excluding LSP or depending directly on the new core package; the normal full build is unchanged.
Reconsider the branch if john-slop-core becomes a supported published API, if
the adapters gain independent release schedules, or if the full build grows
enough that the package boundaries enable additional parallelism. Until then,
optionalizing the LSP module in the existing single crate would capture most of
the no-default-feature compile benefit with substantially less release overhead.
Milestone 13 deliberately chose the first reconsideration condition: treat
john-slop-core and john-slop-lsp as supported reusable packages. The measured
full-build result has not changed. Adoption instead values the enforceable
dependency boundary, lean core consumers, and clearer ownership enough to
accept synchronized releases and workspace-aware CI/package checks. Shared
metadata and dependency requirements now use Cargo workspace inheritance, while
member-specific feature activation remains local so centralization does not
erase the isolation this experiment measured.