fader_master/docs/ci-coverage.md

73 lines
3.4 KiB
Markdown

# CI coverage and badge lifecycle
See [Build prerequisites](build.md) for the native and portable build commands.
TUI rendering, separator presentation, and configuration round-trip tests are
part of the portable suites. Unix-socket/server-restart tests require the
Linux executable test suite; real audio fixtures remain separately opt-in.
README screenshots are generated documentation assets, not coverage badges.
The generic renderer in `scripts/ci-coverage-badges.sh` is copied unchanged
from `Dandaedre/agent-tasks` revision
`fb9d8f7d16f100c2d1377f23394a2302eac9ab18`.
Jenkins installs the pinned `cargo-llvm-cov` 0.9.1 release and runs:
```sh
scripts/ci-run-coverage.sh 20 coverage/llvm-cov-summary.json \
"coverage/.coverage-ready-${BUILD_NUMBER}" coverage/coverage-status.txt
```
The underlying measurement is one locked `cargo llvm-cov --workspace
--all-targets --all-features --locked --json --summary-only` run. The script
reads the overall line percentage from the temporary JSON summary, displays the
unrounded measurement and the 20% floor, renders the rounded coverage badge,
then enforces the floor against the unrounded value. Ordinary production code
is not excluded. A valid current-build report is marked ready even when it is
below the floor; missing or invalid reports fail with an unavailable diagnostic
and cannot reuse an older value.
Coverage runs only when the Jenkins `ENABLE_NATIVE_BACKENDS` parameter is true.
The temporary FreeBSD-compatible mode deliberately emits the neutral/unavailable
coverage badge because its portable package subset would not be comparable to
the full workspace measurement. Enabling the parameter on a provisioned Linux
worker restores the existing coverage command and threshold.
The authoritative version is `[workspace.package].version` in the root
`Cargo.toml`. During Jenkins cleanup, the current build's test marker determines
the test badge, a ready marker preserves current measured coverage, and the
workspace version determines the version badge. Jenkins archives exactly these
files with fingerprints:
```text
coverage/version.svg
coverage/test.svg
coverage/coverage.svg
```
The temporary JSON summary and both build-specific markers are removed during
badge finalization. `coverage/coverage-status.txt` is retained just long enough
to populate the Jenkins build summary, then removed as well.
For a default-branch build, the publication script atomically copies them to:
```text
/mnt/assets/coverage/MadGobblins/fader_master/main/version.svg
/mnt/assets/coverage/MadGobblins/fader_master/main/test.svg
/mnt/assets/coverage/MadGobblins/fader_master/main/coverage.svg
```
Their public URLs are:
- `https://assets.dandaedre.com/coverage/MadGobblins/fader_master/main/version.svg`
- `https://assets.dandaedre.com/coverage/MadGobblins/fader_master/main/test.svg`
- `https://assets.dandaedre.com/coverage/MadGobblins/fader_master/main/coverage.svg`
The Jenkins job must expose `BRANCH_NAME` (multibranch Pipeline) or `GIT_BRANCH`
from `checkout scm`; builds without either variable do not publish. Non-default
branches still generate and archive all three badges. The real asset mount and
public retrieval remain deployment checks outside repository tests.
The public server should mount the asset tree read-only, disable directory
listings, serve SVG with a restrictive content security policy, and revalidate
these mutable URLs or give them a short cache lifetime.