120 lines
5.7 KiB
Markdown
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.
|