docs: compare crate boundary tradeoffs

This commit is contained in:
Dandaedre 2026-09-29 21:32:16 +02:00
parent bee9367360
commit 933066700f
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
17 changed files with 132 additions and 24 deletions

View File

@ -9,9 +9,9 @@ nanos = 350250460
[last_run_incremental]
run_status = "Success"
lines_parsed = 338
lines_parsed = 360
coverage = 92.19
[last_run_incremental.run_duration]
secs = 19
nanos = 900243697
secs = 21
nanos = 698238921

View File

@ -32,11 +32,10 @@ src/
john-slop-fmt.rs replacement formatter
john-slop-lsp.rs stdio language server
crates/
john-slop-core/src/ config, input, detection, diagnostics, and edits
john-slop-core/
assets/ embedded replacement and heuristic catalogs
src/ config, input, detection, diagnostics, and edits
john-slop-lsp/src/ protocol state, UTF-16 mapping, and code actions
assets/
config.toml embedded replacement defaults
heuristics.toml embedded detection rules
tests/
fixtures/ small, reviewed input/output fixtures
```
@ -96,7 +95,8 @@ Never use a hash-map iteration order as output order.
## Heuristics and evidence scoring
Store data-driven heuristic definitions in `assets/heuristics.toml`, separately
Store data-driven heuristic definitions in
`crates/john-slop-core/assets/heuristics.toml`, separately
from replacement configuration. Compile and validate rules once at startup.
Invalid regular expressions, duplicate IDs, negative/non-finite weights, invalid
thresholds, and unsafe empty matches are configuration errors—not ignored rules.
@ -140,7 +140,8 @@ configuration directory; do not hand-build it from `HOME`.
The precedence from lowest to highest is:
1. embedded `assets/config.toml` and `assets/heuristics.toml`;
1. embedded `crates/john-slop-core/assets/config.toml` and
`crates/john-slop-core/assets/heuristics.toml`;
2. user base config at `$XDG_CONFIG_HOME/john_slop/config.toml`, conventionally
`~/.config/john_slop/config.toml` on Linux;
3. named user config at `$XDG_CONFIG_HOME/john_slop/<config_name>.toml` when a
@ -155,7 +156,8 @@ field: replacement/rule tables merge by stable ID, while ignore globs and file
extensions replace as complete arrays unless the schema explicitly says
otherwise. Do not rely on a library's default array-merge semantics implicitly.
`assets/config.toml` is the canonical, documented replacement catalog. Each
`crates/john-slop-core/assets/config.toml` is the canonical, documented
replacement catalog. Each
entry has an ID, Unicode source string/code point, ASCII replacement, rationale,
and enabled flag. Reject duplicate sources, empty sources, non-ASCII targets,
and conflicting edits. Longer sources win matching precedence. Provide a command

View File

@ -33,8 +33,8 @@ lsp = ["dep:john-slop-lsp-engine", "dep:tokio", "dep:tower-lsp-server"]
[dependencies]
clap = { version = "4.6.7", default-features = false, features = ["derive", "error-context", "help", "std", "suggestions", "usage"] }
globset = { version = "0.4.20", default-features = false }
john-slop-core = { path = "crates/john-slop-core" }
john-slop-lsp-engine = { package = "john-slop-lsp", path = "crates/john-slop-lsp", optional = true }
john-slop-core = { version = "0.1.0", path = "crates/john-slop-core" }
john-slop-lsp-engine = { package = "john-slop-lsp", version = "0.1.0", path = "crates/john-slop-lsp", optional = true }
miette = { version = "7.6.0", default-features = false, features = ["derive"] }
serde = { version = "1.0.229", features = ["derive"] }
serde_json = "1.0.151"

View File

@ -5,6 +5,7 @@ edition = "2024"
rust-version = "1.98.1"
license = "MIT"
repository = "https://git.dandaedre.com/idle-org/john_slop"
description = "Reusable heuristic analysis, configuration, input, and replacement engine for John Slop"
[dependencies]
directories = "6.0.0"

View File

@ -13,8 +13,8 @@ use serde::{Deserialize, Serialize};
use crate::{Category, FindingSeverity};
const EMBEDDED_CONFIG: &str = include_str!("../../../assets/config.toml");
const EMBEDDED_HEURISTICS: &str = include_str!("../../../assets/heuristics.toml");
const EMBEDDED_CONFIG: &str = include_str!("../assets/config.toml");
const EMBEDDED_HEURISTICS: &str = include_str!("../assets/heuristics.toml");
/// A validated named configuration without path syntax or a file extension.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]

View File

@ -5,12 +5,13 @@ edition = "2024"
rust-version = "1.98.1"
license = "MIT"
repository = "https://git.dandaedre.com/idle-org/john_slop"
description = "Language Server Protocol engine for John Slop"
[lib]
name = "john_slop_lsp_engine"
[dependencies]
john-slop-core = { path = "../john-slop-core" }
john-slop-core = { version = "0.1.0", path = "../john-slop-core" }
serde_json = "1.0.151"
thiserror = "2.0.21"
tokio = { version = "1.53.1", default-features = false, features = ["sync"] }

View File

@ -40,6 +40,8 @@ the details needed to use, embed, and develop John Slop:
Gitea's locale-aware catalog, its upstream, and safe adoption boundaries.
- [Decision records](decisions/) preserve durable product and engineering
choices, including evidence-score semantics and input limits.
- [Crate-boundary experiment](experiments/crate-boundary.md) records the measured
workspace split and its do-not-merge recommendation.
Release-hardening contracts remain specified in [tasks.md](../tasks.md) and
[AGENTS.md](../AGENTS.md) until that milestone lands.

View File

@ -30,8 +30,8 @@ files are optional; a selected explicit file must exist.
## Schema
The current `schema_version` is `1`. The complete defaults and documented record
examples live in [`assets/config.toml`](../assets/config.toml) and
[`assets/heuristics.toml`](../assets/heuristics.toml).
examples live in [`config.toml`](../crates/john-slop-core/assets/config.toml) and
[`heuristics.toml`](../crates/john-slop-core/assets/heuristics.toml).
Ready-to-copy, commented partial layers live in
[`examples/config`](../examples/config/): `config.toml` demonstrates a user-wide
base and `editorial.toml` demonstrates a named overlay.

View File

@ -48,7 +48,7 @@ cargo tarpaulin --config tarpaulin.toml
```
The configuration enforces a 90% floor. The current suite measured 92.19%
(1333/1446 lines) on 2026-09-29. The remaining lines are dominated by
(1,334/1,447 lines) on 2026-09-29. The remaining lines are dominated by
platform/I/O failure injection, malformed archive internals, coordinate
overflow, LSP logging/reload failures, and subprocess attribution. Do not add
brittle tests or production seams solely to make Tarpaulin count those paths.

View File

@ -48,7 +48,8 @@ Each shipped rule has at least one explicitly labeled realistic near miss. The
The renewed review accepts lighter `0.90ⁿ` correlation damping for distinct
prompt-leakage rules while retaining `0.75ⁿ` for other categories. The checked-in
`signoff.toml` records that decision, acknowledges the corpus limitations, and
contains the unchanged SHA-256 digest of `assets/heuristics.toml`.
contains the unchanged SHA-256 digest of
`crates/john-slop-core/assets/heuristics.toml`.
Any default rule, matcher, pattern, weight, occurrence cap, scope, or threshold
change invalidates the sign-off test. Renewal requires reviewing positive and

View File

@ -0,0 +1,88 @@
# Crate-boundary experiment
Status: **do not merge yet**. The branch proves that dependency isolation works,
but the current project does not recover enough value from it to justify three
publishable packages and their release coordination.
## 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` (`milestone-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.
## Recommendation
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.

View File

@ -3,6 +3,10 @@
Releases are built from a clean, reviewed Linux checkout with the exact Rust
toolchain recorded in `BUILD-INFO`.
If publishing Rust packages, publish and verify `john-slop-core` first,
`john-slop-lsp` second, and the root `john_slop` facade last. All three versions
must remain synchronized; path dependencies carry matching registry versions.
1. Ensure `CHANGELOG.md`, `Cargo.toml`, `Cargo.lock`, documentation, and the
version badge agree; run every command in `docs/development.md`.
2. Run normal Criterion sampling and the fuzz targets appropriate to changes.

View File

@ -4,6 +4,7 @@ engine = "Llvm"
fail-under = 90.0
locked = true
run-types = ["Tests"]
workspace = true
[report]
out = ["Stdout"]

View File

@ -325,7 +325,7 @@ floor; and the generated badges are current.
`john-slop-lsp` workspace crate. Keep the root package as the compatibility
facade and binary distribution, preserving public behavior and all three
executable names.
- [ ] Run identical clean and incremental measurements on the experiment,
- [x] Run identical clean and incremental measurements on the experiment,
compare compile time, artifact size, dependency isolation, API/release cost,
tests, coverage, and packaging against `milestone-11`, then record an explicit
merge-or-abandon recommendation.
@ -336,6 +336,12 @@ any claimed build improvement is measured rather than inferred. Do not merge
the experiment when its gains do not justify the added workspace and release
complexity.
Completed on 2026-09-29 with a **do-not-merge-yet** recommendation. Core and
no-LSP checks use roughly 35–55% less CPU/disk, but the full workspace remains
effectively unchanged while package publishing, version synchronization, asset
ownership, feature contracts, CI, and coverage all become more complex. The
complete measurements are in `docs/experiments/crate-boundary.md`.
## Deferred by design
- Statistical or model-based authorship classification.

View File

@ -121,10 +121,12 @@ fn reviewed_corpus_reports_per_rule_metrics_and_false_positive_rate() {
&fs::read_to_string(root.join("signoff.toml")).expect("read evaluation sign-off"),
)
.expect("parse evaluation sign-off");
let catalog_hash = Sha256::digest(include_bytes!("../assets/heuristics.toml"))
.iter()
.map(|byte| format!("{byte:02x}"))
.collect::<String>();
let catalog_hash = Sha256::digest(include_bytes!(
"../crates/john-slop-core/assets/heuristics.toml"
))
.iter()
.map(|byte| format!("{byte:02x}"))
.collect::<String>();
assert_eq!(signoff.schema_version, 1);
assert_eq!(signoff.release, env!("CARGO_PKG_VERSION"));
assert_eq!(signoff.status, "accepted-after-prompt-damping-review");