From 933066700f03153bcf333ace80b1a6321e7699f5 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Tue, 29 Sep 2026 21:32:16 +0200 Subject: [PATCH] docs: compare crate boundary tradeoffs --- .run_status.toml | 6 +- AGENTS.md | 16 ++-- Cargo.toml | 4 +- crates/john-slop-core/Cargo.toml | 1 + .../john-slop-core/assets}/config.toml | 0 .../john-slop-core/assets}/heuristics.toml | 0 crates/john-slop-core/src/config.rs | 4 +- crates/john-slop-lsp/Cargo.toml | 3 +- docs/README.md | 2 + docs/configuration.md | 4 +- docs/development.md | 2 +- docs/evaluation.md | 3 +- docs/experiments/crate-boundary.md | 88 +++++++++++++++++++ docs/releasing.md | 4 + tarpaulin.toml | 1 + tasks.md | 8 +- tests/evaluation.rs | 10 ++- 17 files changed, 132 insertions(+), 24 deletions(-) rename {assets => crates/john-slop-core/assets}/config.toml (100%) rename {assets => crates/john-slop-core/assets}/heuristics.toml (100%) create mode 100644 docs/experiments/crate-boundary.md diff --git a/.run_status.toml b/.run_status.toml index 9a02a46..19c7b8a 100644 --- a/.run_status.toml +++ b/.run_status.toml @@ -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 diff --git a/AGENTS.md b/AGENTS.md index c0f84c2..9c96e26 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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/.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 diff --git a/Cargo.toml b/Cargo.toml index 5c2f9c9..cde8531 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -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" diff --git a/crates/john-slop-core/Cargo.toml b/crates/john-slop-core/Cargo.toml index 365dd58..f13f57e 100644 --- a/crates/john-slop-core/Cargo.toml +++ b/crates/john-slop-core/Cargo.toml @@ -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" diff --git a/assets/config.toml b/crates/john-slop-core/assets/config.toml similarity index 100% rename from assets/config.toml rename to crates/john-slop-core/assets/config.toml diff --git a/assets/heuristics.toml b/crates/john-slop-core/assets/heuristics.toml similarity index 100% rename from assets/heuristics.toml rename to crates/john-slop-core/assets/heuristics.toml diff --git a/crates/john-slop-core/src/config.rs b/crates/john-slop-core/src/config.rs index 4b49de4..3affadf 100644 --- a/crates/john-slop-core/src/config.rs +++ b/crates/john-slop-core/src/config.rs @@ -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)] diff --git a/crates/john-slop-lsp/Cargo.toml b/crates/john-slop-lsp/Cargo.toml index 710b0bb..3b29612 100644 --- a/crates/john-slop-lsp/Cargo.toml +++ b/crates/john-slop-lsp/Cargo.toml @@ -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"] } diff --git a/docs/README.md b/docs/README.md index 0b3540f..7da5024 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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. diff --git a/docs/configuration.md b/docs/configuration.md index 4eeeaed..c70d3cf 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -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. diff --git a/docs/development.md b/docs/development.md index c4fa042..97c5456 100644 --- a/docs/development.md +++ b/docs/development.md @@ -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. diff --git a/docs/evaluation.md b/docs/evaluation.md index b143c96..10a1feb 100644 --- a/docs/evaluation.md +++ b/docs/evaluation.md @@ -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 diff --git a/docs/experiments/crate-boundary.md b/docs/experiments/crate-boundary.md new file mode 100644 index 0000000..9a9b282 --- /dev/null +++ b/docs/experiments/crate-boundary.md @@ -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. diff --git a/docs/releasing.md b/docs/releasing.md index b175808..27d4209 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -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. diff --git a/tarpaulin.toml b/tarpaulin.toml index 533d9df..0f414dc 100644 --- a/tarpaulin.toml +++ b/tarpaulin.toml @@ -4,6 +4,7 @@ engine = "Llvm" fail-under = 90.0 locked = true run-types = ["Tests"] +workspace = true [report] out = ["Stdout"] diff --git a/tasks.md b/tasks.md index 67c24ca..c359369 100644 --- a/tasks.md +++ b/tasks.md @@ -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. diff --git a/tests/evaluation.rs b/tests/evaluation.rs index bd5b86f..59efcb9 100644 --- a/tests/evaluation.rs +++ b/tests/evaluation.rs @@ -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::(); + let catalog_hash = Sha256::digest(include_bytes!( + "../crates/john-slop-core/assets/heuristics.toml" + )) + .iter() + .map(|byte| format!("{byte:02x}")) + .collect::(); assert_eq!(signoff.schema_version, 1); assert_eq!(signoff.release, env!("CARGO_PKG_VERSION")); assert_eq!(signoff.status, "accepted-after-prompt-damping-review");