john-slop/docs/development.md

5.1 KiB

Development

The project uses Rust edition 2024 and requires Rust 1.98.1 or newer. The committed lockfile makes application builds reproducible. Linux is the supported and exercised platform; other platforms are not declared supported until CI covers them. Jenkins checks Linux on both Rust 1.98.1 (the MSRV) and current stable, with all features and without default features.

Quality gates

Run the same core checks required by the contributor guide:

cargo fmt --all -- --check
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo test --locked --all-targets --all-features
cargo test --locked --all-targets --no-default-features
cargo doc --locked --no-deps --all-features
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 for the registry verification boundary.

To smoke-test installation from the current source checkout, identify the local package explicitly (recent Cargo versions no longer infer it from an omitted package argument):

cargo install --path . --locked --all-features

Use --root <temporary-directory> when verifying this command without changing the normal Cargo installation root.

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 no-default-features test run exercises the core, detector, and formatter without the async protocol dependency graph and with the plain diagnostic fallback. Focused unit and integration tests cover domain invariants, input failures, archives, CLI exit behavior, and feature configurations.

CI runs the executable fixture manifest and Insta CLI snapshots explicitly in addition to the full suite. cargo-audit rejects RustSec advisories and yanked packages. deny.toml rejects unknown dependency sources, wildcard versions, and licenses outside the reviewed allow-list; duplicate versions are reported for review while upstream compatibility is assessed.

Insta snapshots are reserved for stable user-facing text such as CLI help and usage errors. Structured domain values use direct assertions so failures remain precise and easy to review. Accept snapshot changes only after inspecting the generated diff.

Coverage and badges

Run line coverage with Cargo Tarpaulin:

cargo tarpaulin --config tarpaulin.toml

The configuration enforces a 90% floor. The current suite measured 92.83% (1,579/1,701 lines) on 2026-09-30. 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.

After a clean test and coverage run, refresh the repository-local badges with:

rust_autobadges --high-coverage-percent 0.7 --mid-coverage-percent 0.3

Commit badges/*.svg and .run_status.toml; do not commit the generated tarpaulin-report.html. Jenkins runs both feature configurations and enforces the Tarpaulin floor before building release binaries.

Test scope

Add behavior tests at the lowest useful layer and an integration test when a change crosses a binary boundary. Important edge cases include malformed input, invalid UTF-8, empty text, Unicode byte spans, deterministic ordering, archive limits, and near misses for detection rules. The detailed expectations and task-level commit discipline are in AGENTS.md.

Each completed milestone receives an immutable annotated v0.1.N Git tag, where N is the milestone number, after its acceptance criteria and quality gates pass. Its completion commit must also use package version 0.1.N in the workspace manifest, internal registry requirements, lockfile, changelog, binary version output, and generated version badge.

Fuzzing

The standalone fuzz package contains five cargo-fuzz targets and reviewed seeds for configuration merging, rule validation/compilation, UTF-8 span conversion, replacement invariants, and hostile archive bytes. See its README for invocation. Fuzz artifacts remain ignored until a failure has been minimized and promoted to a normal regression test.

Benchmarks

Run cargo bench --locked --bench core for the large-document, many-file, rule-scaling, and archive-limit workloads described in Performance benchmarks. Benchmark reports are local artifacts; only methodology and contextualized measurements belong in version control.