john-slop/docs/experiments/crate-boundary.md

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-core without 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::lsp is 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.