docs: compare crate boundary tradeoffs
This commit is contained in:
parent
bee9367360
commit
933066700f
|
|
@ -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
|
||||
|
|
|
|||
16
AGENTS.md
16
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/<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
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -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)]
|
||||
|
|
|
|||
|
|
@ -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"] }
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -4,6 +4,7 @@ engine = "Llvm"
|
|||
fail-under = 90.0
|
||||
locked = true
|
||||
run-types = ["Tests"]
|
||||
workspace = true
|
||||
|
||||
[report]
|
||||
out = ["Stdout"]
|
||||
|
|
|
|||
8
tasks.md
8
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.
|
||||
|
|
|
|||
|
|
@ -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");
|
||||
|
|
|
|||
Loading…
Reference in New Issue