john-slop/docs/development.md

120 lines
5.7 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 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:
```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
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.
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):
```sh
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`](../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 the same line-coverage command used by Jenkins:
```sh
cargo tarpaulin --config tarpaulin.toml --out Json --output-dir coverage
```
The configuration enforces a 90% floor. The current suite measured 92.72%
(1,604/1,730 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.
`Cargo.toml` is the authoritative version source. Jenkins temporarily renames
the Tarpaulin JSON output to `coverage/summary.json`, extracts and validates its
overall percentage, renders the badges locally, and then removes the summary.
It archives only `coverage/version.svg`, `coverage/test.svg`, and
`coverage/coverage.svg`, with fingerprinting. Successful `main` builds publish
those files atomically under
`/mnt/assets/coverage/idle-org/john-slop/main/`, which serves these mutable URLs:
- `https://assets.dandaedre.com/coverage/idle-org/john-slop/main/version.svg`
- `https://assets.dandaedre.com/coverage/idle-org/john-slop/main/test.svg`
- `https://assets.dandaedre.com/coverage/idle-org/john-slop/main/coverage.svg`
The asset server is deployment-owned: it must mount assets read-only, disable
directory listings, serve SVG with a restrictive content security policy, and
revalidate these URLs or apply a short cache lifetime.
## 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 `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. Jenkins derives the current version badge from that metadata.
## Fuzzing
The standalone [`fuzz`](../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](benchmarks.md). Benchmark reports are local artifacts;
only methodology and contextualized measurements belong in version control.