john-slop/docs/development.md

64 lines
2.4 KiB
Markdown

# 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 currently
exercised platform; other platforms are not declared supported until CI covers
them.
## Quality gates
Run the same core checks required by the contributor guide:
```sh
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
```
The default `fancy-diagnostics` feature enables `miette`'s rich terminal
renderer. The no-default-features test run ensures the shared library and all
binaries remain valid without that optional renderer. Focused unit and
integration tests cover domain invariants, input failures, archives, CLI exit
behavior, and feature configurations.
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:
```sh
cargo tarpaulin --config tarpaulin.toml
```
The configuration enforces a 30% floor. The current suite measured 78.44%
(946/1206 lines) on 2026-09-29. The low floor is intentional while CLI
subprocesses and future protocol adapters are not attributed consistently by
every backend; the tracked badge still reports the measured result.
After a clean test and coverage run, refresh the repository-local badges with:
```sh
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](../AGENTS.md).
Each completed milestone receives an immutable annotated `milestone-N` Git tag
after its acceptance criteria and quality gates pass.