feat(cargo-coverage-gate): add cargo subcommand for per-crate coverage gating

.spelling

@@ -327,3 +327,38 @@ workspace
 xxH3
 —
 →
+ADO
+cargo-llvm-cov
+cobertura
+Codecov
+deserializer
+deserialization
+destructured
+emoji
+freeform
+GFM
+JSON's
+kebab
+lcov
+llvm
+llvm-cov
+llvm-tools
+Markdown
+monorepo
+nextest
+prefixed
+ratchet
+renderable
+renderer
+renderers
+representable
+subcommand
+subcommands
+unparseable
+vs
+workspace's
+v2
+§
+tracefile
+LCOV
+deserializer

Cargo.toml

@@ -22,6 +22,7 @@ homepage = "https://github.com/microsoft/ox-tools"
 
 [workspace.dependencies]
 # local dependencies
+cargo-coverage-gate = { path = "crates/cargo-coverage-gate", default-features = false, version = "0.1.0" }
 cargo-heather = { path = "crates/cargo-heather", default-features = false, version = "0.2.1" }
 
 # external dependencies
@@ -31,6 +32,7 @@ anyhow = { version = "1.0.100", default-features = false }
 assert_cmd = { version = "2.2.0", default-features = false }
 async-once-cell = { version = "0.5", default-features = false }
 bytes = { version = "1.11.1", default-features = false }
+cargo_metadata = { version = "0.23.1", default-features = false }
 chrono = { version = "0.4.40", default-features = false }
 chrono-tz = { version = "0.10.4", default-features = false }
 clap = { version = "4.5.60", default-features = false }
@@ -48,6 +50,7 @@ http = { version = "1.2.0", default-features = false, features = ["std"] }
 infinity_pool = { version = "0.8.1", default-features = false }
 insta = { version = "1.44.1", default-features = false }
 jiff = { version = "0.2.21", default-features = false }
+lcov = { version = "0.8.2", default-features = false }
 libc = { version = "0.2.178", default-features = false }
 many_cpus = { version = "2.1.0", default-features = false }
 mockall = { version = "0.14.0", default-features = false }

README.md

@@ -25,6 +25,7 @@ This repository contains a set of tools  that help you build robust highly scala
 
 These are the primary crates built out of this repo:
 
+- [`cargo-coverage-gate`](./crates/cargo-coverage-gate/README.md) - A cargo sub-command that gates pull requests on per-crate line coverage measured by cargo-llvm-cov
 - [`cargo-heather`](./crates/cargo-heather/README.md) -  A cargo sub-command to validate license headers in Rust, TOML, PowerShell, Just, and env source files
 
 ## About this Repo

crates/cargo-coverage-gate/CHANGELOG.md

@@ -0,0 +1 @@
+# Changelog

crates/cargo-coverage-gate/Cargo.toml

@@ -0,0 +1,51 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+[package]
+name = "cargo-coverage-gate"
+description = "A cargo subcommand that gates pull requests on per-package line coverage measured by cargo-llvm-cov"
+version = "0.1.0"
+readme = "README.md"
+keywords = ["oxidizer", "cargo", "subcommand", "coverage", "ci"]
+categories = ["command-line-utilities", "development-tools::cargo-plugins"]
+
+edition.workspace = true
+rust-version.workspace = true
+authors.workspace = true
+license.workspace = true
+homepage.workspace = true
+repository = "https://github.com/microsoft/ox-tools/tree/main/crates/cargo-coverage-gate"
+
+[package.metadata.docs.rs]
+all-features = true
+
+[package.metadata.cargo_check_external_types]
+allowed_external_types = [
+    # The `#[ohno::error]` attribute on `CoverageGateError` implements
+    # these traits, which transitively appear in the public API.
+    "ohno::enrichable::Enrichable",
+    "ohno::error_ext::ErrorExt",
+]
+
+[[bin]]
+name = "cargo-coverage-gate"
+path = "src/bin/cargo-coverage-gate/main.rs"
+
+[dependencies]
+cargo_metadata = { workspace = true }
+clap = { workspace = true, features = ["derive", "std", "help", "usage", "error-context"] }
+lcov = { workspace = true }
+ohno = { workspace = true, features = ["app-err"] }
+serde = { workspace = true, features = ["derive", "alloc"] }
+serde_json = { workspace = true, features = ["std"] }
+tracing = { workspace = true }
+tracing-subscriber = { workspace = true, features = ["fmt"] }
+
+[dev-dependencies]
+assert_cmd = { workspace = true }
+predicates = { workspace = true }
+pretty_assertions = { workspace = true, features = ["std"] }
+tempfile = { workspace = true }
+
+[lints]
+workspace = true

crates/cargo-coverage-gate/README.md

@@ -0,0 +1,109 @@
+<div align="center">
+ <img src="./logo.png" alt="Cargo-Coverage-Gate Logo" width="96">
+
+# Cargo-Coverage-Gate
+
+[![crate.io](https://img.shields.io/crates/v/cargo-coverage-gate.svg)](https://crates.io/crates/cargo-coverage-gate)
+[![docs.rs](https://docs.rs/cargo-coverage-gate/badge.svg)](https://docs.rs/cargo-coverage-gate)
+[![MSRV](https://img.shields.io/crates/msrv/cargo-coverage-gate)](https://crates.io/crates/cargo-coverage-gate)
+[![CI](https://github.com/microsoft/ox-tools/actions/workflows/main.yml/badge.svg?event=push)](https://github.com/microsoft/ox-tools/actions/workflows/main.yml)
+[![Coverage](https://codecov.io/gh/microsoft/ox-tools/graph/badge.svg?token=FCUG0EL5TI)](https://codecov.io/gh/microsoft/ox-tools)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
+<a href="../.."><img src="../../logo.svg" alt="This crate was developed as part of the Oxidizer project" width="20"></a>
+
+</div>
+
+## cargo-coverage-gate
+
+A pull-request-time gate that compares per-package line coverage produced
+by [`cargo-llvm-cov`][__link0] against per-package thresholds carried in
+`Cargo.toml`. The accompanying `cargo-coverage-gate` binary reads the
+coverage lcov tracefile, resolves each package’s threshold from a small
+three-layer lookup, and emits a verdict table to stdout (and,
+optionally, to a Markdown summary file for CI step summaries).
+
+The full design is in [`docs/design/main.md`][__link1] in the source tree;
+the implementation plan tracking the build is in
+[`docs/implementation-plans/0000.md`][__link2].
+
+### Threshold resolution
+
+For each workspace member, the effective threshold is the first match
+among:
+
+1. `[package.metadata.coverage-gate] min-lines-percent = N` in the package’s
+   `Cargo.toml`,
+1. `[workspace.metadata.coverage-gate] min-lines-percent = N` in the workspace
+   root `Cargo.toml`, or
+1. The built-in default of `100.0` — full coverage required.
+
+Setting `min-lines-percent = 0.0` explicitly opts a package out of gating.
+
+### Why lcov, not the JSON?
+
+`cargo-llvm-cov` exports the same instrumentation run in several
+formats (JSON, lcov, cobertura, codecov-custom-JSON). The gate
+consumes lcov because that is what every other coverage UI fed by
+the same data sees: Codecov ingests lcov uploads directly, ADO
+consumes cobertura that cargo-llvm-cov derives from lcov, and the
+lcov line semantics (“a line is covered if any region on it was
+hit”) match the human reading of “did we hit this line”. The JSON
+export uses a stricter “every region on the line must be hit”
+interpretation that systematically reports a couple of
+percentage-points lower, which makes calibrating thresholds against
+codecov / ADO numbers confusing.
+
+### Binary usage
+
+```text
+cargo coverage-gate  [--lcov <path>] [-p <spec>]... [--package <spec>]...
+                     [--summary-file <path>] [--quiet]
+```
+
+Exit codes: `0` if every gated package meets its threshold, `1` if any
+gated package falls below its threshold, and `2` for configuration
+errors (unparseable lcov, missing data for a gated package, a `--package`
+selector that matches no member, an out-of-range `min-lines-percent`
+value, …).
+
+When `--summary-file` is unset, the binary falls back to
+`$GITHUB_STEP_SUMMARY` and then `$COVERAGE_GATE_SUMMARY` to decide
+where to write the Markdown verdict table.
+
+### Library usage
+
+```rust
+use std::io;
+
+let lcov = std::fs::read_to_string("target/coverage/lcov.info")?;
+let report = cargo_coverage_gate::evaluate(&lcov, None, &[])?;
+report.render_text(&mut io::stdout())?;
+let code = report.verdict().exit_code();
+```
+
+### Public API
+
+The library exposes [`evaluate`][__link3], which returns an
+[`EvaluatedReport`][__link4]. The report can be rendered as plain text via
+[`EvaluatedReport::render_text`][__link5] or as GitHub-flavored Markdown
+via [`EvaluatedReport::render_markdown`][__link6], and reduced to a single
+[`Verdict`][__link7] via [`EvaluatedReport::verdict`][__link8]. The accompanying
+binary loads the lcov tracefile from disk and orchestrates rendering
+plus the appropriate exit code.
+
+
+<hr/>
+<sub>
+This crate was developed as part of <a href="../..">The Oxidizer Project</a>. Browse this crate's <a href="https://github.com/microsoft/ox-tools/tree/main/crates/cargo-coverage-gate">source code</a>.
+</sub>
+
+ [__cargo_doc2readme_dependencies_info]: ggGmYW0CYXZlMC43LjJhdIQbYLuo4OFUWT8bvMCT2d1BCU8bCvLHCBSvMr0bKR38GpAvnJ5hYvRhcoQbeMd-OXFcBm0bmRUrCNlaa-Mbh5mmtfAjdb0bXEoRTJRFNyZhZIGDc2NhcmdvLWNvdmVyYWdlLWdhdGVlMC4xLjBzY2FyZ29fY292ZXJhZ2VfZ2F0ZQ
+ [__link0]: https://github.com/taiki-e/cargo-llvm-cov
+ [__link1]: https://github.com/microsoft/ox-tools/blob/main/crates/cargo-coverage-gate/docs/design/main.md
+ [__link2]: https://github.com/microsoft/ox-tools/blob/main/crates/cargo-coverage-gate/docs/implementation-plans/0000.md
+ [__link3]: https://docs.rs/cargo-coverage-gate/0.1.0/cargo_coverage_gate/fn.evaluate.html
+ [__link4]: https://docs.rs/cargo-coverage-gate/0.1.0/cargo_coverage_gate/struct.EvaluatedReport.html
+ [__link5]: https://docs.rs/cargo-coverage-gate/0.1.0/cargo_coverage_gate/?search=EvaluatedReport::render_text
+ [__link6]: https://docs.rs/cargo-coverage-gate/0.1.0/cargo_coverage_gate/?search=EvaluatedReport::render_markdown
+ [__link7]: https://docs.rs/cargo-coverage-gate/0.1.0/cargo_coverage_gate/enum.Verdict.html
+ [__link8]: https://docs.rs/cargo-coverage-gate/0.1.0/cargo_coverage_gate/?search=EvaluatedReport::verdict