Coverage

This repository provides a canonical local workflow for collecting code coverage using the llvm-based tool cargo-llvm-cov. We avoid CI-specific workflows here — run these commands locally or on your preferred self-hosted/Codeberg runner.

Requirements

• Rust stable toolchain.
• rust-src and llvm-tools-preview components.
• cargo-llvm-cov (installable via cargo).

Install prerequisites

# ensure rustup is installed and add the nightly toolchain + components
rustup toolchain install nightly
rustup component add --toolchain nightly rust-src llvm-tools-preview

# install the coverage helper (you can skip if already installed)
cargo install cargo-llvm-cov --locked

Available commands (aliases) The repository includes cargo aliases in .cargo/config.toml:

• cargo coverage — produce a text coverage summary (target/coverage/)
• cargo coverage-html — generate an HTML report and open it (target/coverage/)
• cargo coverage-lcov — produce lcov info (target/coverage/)

You can also run cargo-llvm-cov directly if you prefer (these are equivalent to the aliases):

# Text summary (nightly is required for branch coverage)
cargo +nightly llvm-cov --workspace --tests --branch --output-path=target/coverage --ignore-filename-regex="^/rustc/"

# HTML report
cargo +nightly llvm-cov --workspace --tests --branch --output-path=target/coverage --ignore-filename-regex="^/rustc/" --open

# lcov
cargo +nightly llvm-cov --workspace --tests --branch --output-path=target/coverage --ignore-filename-regex="^/rustc/" --lcov

• Branch coverage (the --branch option) requires a nightly toolchain; the examples above run llvm-cov under nightly via cargo +nightly ....
• A convenience script is provided at ./mk/test which will install the required nightly components (if missing), install cargo-llvm-cov (if missing), and run the coverage commands for you.

Notes

• cargo --list will show the aliases defined in .cargo/config.toml.
• cargo llvm-cov requires the rust-src and llvm-tools-preview components; installing them via rustup component add is usually sufficient.
• These commands are local-first and independent of any particular hosted CI provider; they can be run on Codeberg CI, self-hosted runners, or developer machines.

Recommended additional files to include

• mk/extract_uncovered.py: The ./mk/test script invokes mk/extract_uncovered.py to process lcov info into a human-friendly uncovered-lines report. If you plan to run ./mk/test, ensure mk/extract_uncovered.py is present and executable. If you'd like, paste mk/extract_uncovered.py here and I can review it or provide a minimal implementation.
• mk/extract_uncovered.py is often a small Python script that reads an lcov/info file and writes a concise summary; adding it will make the mk/test flow fully self-contained.

If you want suggestions for other files to add (CI config, more helper scripts, or example fixtures for the integration tests), tell me which CI or tooling you plan to use and I will recommend minimal files.