diff --git a/.run_status.toml b/.run_status.toml index 19c7b8a..0e656ed 100644 --- a/.run_status.toml +++ b/.run_status.toml @@ -1,11 +1,11 @@ [last_run_clean] run_status = "Success" -lines_parsed = 338 +lines_parsed = 375 coverage = 92.19 [last_run_clean.run_duration] -secs = 29 -nanos = 350250460 +secs = 38 +nanos = 218186395 [last_run_incremental] run_status = "Success" diff --git a/AGENTS.md b/AGENTS.md index 202fd19..35a9c52 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -224,7 +224,7 @@ cargo doc --no-deps ``` Run `cargo tarpaulin --config tarpaulin.toml` when tests or executable Rust code -change. It enforces the intentionally modest 30% line-coverage floor. Refresh +change. It enforces the 90% line-coverage floor. Refresh the tracked local badges with `rust_autobadges --high-coverage-percent 0.7 --mid-coverage-percent 0.3` after a clean test and coverage run. diff --git a/CHANGELOG.md b/CHANGELOG.md index d5cdcd7..4bb5571 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,9 @@ All notable changes to John Slop are recorded here. The format follows ### Changed +- Adopted the measured three-package Cargo workspace. Shared package metadata, + dependency requirements, and lint policy now use workspace inheritance while + the reusable core remains isolated from CLI, async, and LSP dependencies. - Renamed the ambiguous confidence metric to low-care evidence score throughout the Rust API, CLI, terminal output, and JSON schema version 2. Deprecated Rust type aliases and `--fail-confidence` remain available for migration; the diff --git a/Cargo.toml b/Cargo.toml index ed46657..e51ba94 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -45,7 +45,7 @@ edition.workspace = true rust-version.workspace = true license.workspace = true repository.workspace = true -description = "Heuristic low-care signal detector, ASCII formatter, and language server" +description = "Inspect files, directories, or ZIP-based documents for low-care signals" autobins = false [[bin]] diff --git a/docs/README.md b/docs/README.md index 7da5024..5391235 100644 --- a/docs/README.md +++ b/docs/README.md @@ -41,7 +41,10 @@ the details needed to use, embed, and develop John Slop: - [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. + workspace split, original recommendation, and subsequent adoption decision. +- [Workspace architecture decision](decisions/0004-supported-cargo-workspace.md) + records the supported package boundaries, inheritance policy, and accepted + release cost. Release-hardening contracts remain specified in [tasks.md](../tasks.md) and [AGENTS.md](../AGENTS.md) until that milestone lands. diff --git a/docs/architecture.md b/docs/architecture.md index f1b8ebb..9eb1eb7 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -23,6 +23,16 @@ The crate boundary separates dependency families: - the root `john_slop` package re-exports both libraries to preserve its public API and distributes the detector, formatter, and LSP binaries. +The root manifest is intentionally both a package and the workspace root. A +virtual manifest would relocate the compatibility facade, binaries, examples, +and fixtures without improving dependency isolation. `[workspace.package]`, +`[workspace.dependencies]`, and `[workspace.lints]` provide one source of truth +for shared release metadata, dependency requirements, and first-party unsafe +code policy. Member manifests retain only package-specific descriptions, +dependency selections, feature activation, and optionality. In particular, the +workspace Tokio requirement enables no features: the LSP library selects +`sync`, and the root LSP adapter selects its runtime and stdio features. + The modules within those crates retain deliberately narrow responsibilities: - `config` owns the validated embedded replacement catalog and input limits; diff --git a/docs/decisions/0004-supported-cargo-workspace.md b/docs/decisions/0004-supported-cargo-workspace.md new file mode 100644 index 0000000..2e8f81e --- /dev/null +++ b/docs/decisions/0004-supported-cargo-workspace.md @@ -0,0 +1,55 @@ +# ADR 0004: Supported Cargo workspace + +- Status: accepted +- Date: 2026-09-29 + +## Context + +The crate-boundary experiment extracted reusable analysis/configuration/input +code into `john-slop-core` and LSP protocol state into `john-slop-lsp`, leaving +the root `john_slop` package as a compatibility facade and binary distribution. +Cold core and no-LSP builds used roughly 35–55% less CPU and disk, while LSP and +whole-project builds were effectively unchanged. The experiment initially +recommended waiting because three publishable packages require synchronized +versions, ordered publication, workspace-aware CI, and clear asset ownership. + +The project has now chosen to offer the reusable package boundary and accepts +that release overhead. Repeating package metadata and dependency versions in +three manifests would make that overhead unnecessarily error-prone. + +## Decision + +Adopt the three-package layout as the supported architecture: + +- `john-slop-core` owns embedded catalogs and reusable synchronous domain logic; +- `john-slop-lsp` depends on core and owns protocol state/conversion; +- root `john_slop` remains the compatibility facade and owns all three binaries. + +Keep the root manifest as both a package and the workspace root. Moving its +sources under another directory solely to create a virtual manifest adds path, +fixture, and packaging churn without changing the dependency graph. + +Centralize shared version, edition, MSRV, license, repository, dependency +requirements, and lint policy in the root workspace tables. Every member +inherits them. Dependency feature activation and optionality remain in member +manifests: workspace inheritance must not cause the core package to compile +Tokio/LSP dependencies or make the facade's LSP stack unconditional. + +Keep all three packages as default members so existing root quality commands +cover the whole workspace. Enforce membership, synchronized resolved versions, +inheritance, and feature isolation with an integration test. Assemble packages +with Cargo's workspace packaging command and publish in dependency order: core, +LSP, then facade. + +## Consequences + +- Core/no-LSP consumers retain the measured lean dependency graph. +- Existing `john_slop` API paths and binary names remain compatible by default. +- Shared requirements have one update point, while member feature choices stay + reviewable at their point of use. +- Full builds gain no material speedup from the boundary. +- A release coordinates three matching package versions. Before matching + dependency versions exist in the registry, package assembly uses + `--no-verify`; registry-form verification follows publication. +- Embedded catalog changes belong to `john-slop-core`, and workspace coverage, + CI, dependency review, and packaging remain permanent maintenance costs. diff --git a/docs/dependencies.md b/docs/dependencies.md index 72359fe..2ef08ee 100644 --- a/docs/dependencies.md +++ b/docs/dependencies.md @@ -20,6 +20,14 @@ lines. Regex retains Unicode and performance defaults because configured rules use Unicode text and case matching; Miette's graphical stack remains isolated behind `fancy-diagnostics`. +All publishable packages inherit dependency requirements from the root +`[workspace.dependencies]` table. This centralizes versions and baseline feature +policy without globally enabling member-specific features: `john-slop-core` +does not select Clap, Tokio, or the LSP stack; `john-slop-lsp` selects only +Tokio synchronization; and the root adapter enables runtime/stdio support only +behind its optional `lsp` feature. `tests/workspace_contract.rs` pins this +boundary and the synchronized package metadata. + ## Security, licenses, and unsafe code `cargo audit --deny warnings` scanned 187 locked packages against 1,277 RustSec @@ -29,7 +37,8 @@ as warnings for ongoing review. [`deny.toml`](../deny.toml) contains the reviewe license allow-list and rejects wildcard versions, yanked packages, and unknown registries or Git sources. -A source scan found no first-party Rust `unsafe` blocks. Dependencies may use +A workspace lint forbids first-party Rust `unsafe` code, and the source scan +found no existing blocks. Dependencies may use unsafe code internally, notably for compression, operating-system integration, and async/runtime primitives; this review does not claim otherwise. Lockfile, advisory, source, and license checks remain CI gates because this result changes diff --git a/docs/development.md b/docs/development.md index f1c2e55..b3ef2f0 100644 --- a/docs/development.md +++ b/docs/development.md @@ -20,6 +20,15 @@ cargo audit --deny warnings cargo deny --locked check ``` +The root package is also the workspace root, and all three packages are default +members. These unqualified commands therefore cover the compatibility/binary +package, `john-slop-core`, and `john-slop-lsp`. Use `-p john-slop-core` for the +isolated reusable dependency graph or `-p john-slop-lsp` for protocol-only work. +The workspace contract test validates membership, version synchronization, +manifest inheritance, and feature isolation. Before a release, assemble every +publishable crate with `scripts/package-workspace.sh --no-verify`; see the +[release procedure](releasing.md) for the registry verification boundary. + The default `fancy-diagnostics` feature enables the detector's colored Miette renderer and default output mode. The default `lsp` feature exposes the compatibility facade's protocol module and builds the LSP binary. The diff --git a/docs/experiments/crate-boundary.md b/docs/experiments/crate-boundary.md index 6f3910d..b416849 100644 --- a/docs/experiments/crate-boundary.md +++ b/docs/experiments/crate-boundary.md @@ -1,8 +1,10 @@ # 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. +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 @@ -74,7 +76,7 @@ the boundary neither gains nor loses measured test coverage. - Ordinary default and full-project builds receive no material speedup, and runtime behavior and performance do not improve. -## Recommendation +## 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 @@ -86,3 +88,12 @@ 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. diff --git a/tasks.md b/tasks.md index f0ab3a9..97ac8aa 100644 --- a/tasks.md +++ b/tasks.md @@ -336,11 +336,13 @@ 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`. +Completed on 2026-09-29 with a **do-not-merge-yet** recommendation that was +subsequently superseded by the explicit Milestone 13 adoption decision. 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 and adoption rationale are in +`docs/experiments/crate-boundary.md` and ADR 0004. ## Milestone 13 — Supported Cargo workspace @@ -353,7 +355,7 @@ complete measurements are in `docs/experiments/crate-boundary.md`. versions, inherited dependency sources, and core/LSP feature isolation. Make CI, packaging, and publication guidance explicitly workspace-aware and verify every publishable package in dependency order. -- [ ] Replace the experimental recommendation with an adoption decision, update +- [x] Replace the experimental recommendation with an adoption decision, update architecture/dependency/development/release documentation, run the complete feature, lint, documentation, coverage, and package gates, and refresh the generated badges and recap. @@ -365,6 +367,12 @@ workspace member; each package can be assembled for publication in dependency order; coverage remains at or above 90%; and the measured costs of supporting the workspace are recorded rather than hidden. +Accepted on 2026-09-29 after both feature matrices, formatting, Clippy, +documentation, RustSec, cargo-deny, workspace package assembly, and the 90% +coverage floor passed. Tarpaulin remains at 92.19% (1,334/1,447 lines); the +workspace boundary changes dependency ownership, not executable behavior or +measurable source coverage. + ## Deferred by design - Statistical or model-based authorship classification.