100 lines
5.0 KiB
Markdown
100 lines
5.0 KiB
Markdown
# 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](../decisions/0004-supported-cargo-workspace.md).
|
|
|
|
## 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.
|