docs: adopt supported cargo workspace
Rust CI JohnSlop failed CI.
Gitea/john_slop/pipeline/head There was a failure building this commit Details

This commit is contained in:
Dandaedre 2026-09-29 21:45:32 +02:00
parent e9667a6842
commit ca8a352a40
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
11 changed files with 125 additions and 17 deletions

View File

@ -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"

View File

@ -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.

View File

@ -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

View File

@ -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]]

View File

@ -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.

View File

@ -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;

View File

@ -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.

View File

@ -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

View File

@ -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

View File

@ -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.

View File

@ -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.