Skip to content

cargo-tops v0.4.0

Latest

Choose a tag to compare

@github-actions github-actions released this 17 Nov 23:06
· 127 commits to main since this release
98b5c89

Breaking 0.x minor. cargo tops gate now fails on the coverage floors and the CRAP threshold and ratchet that rust-tops.yaml names. Protocol plane moves to 1.2.0 (prose and one optional schema key; no default threshold and no part of the CRAP formula changed). Package plane moves to 0.4.0.

Upgrade

  • An instance with the coverage or crap layer enabled is now held to its numbers. Before the first 0.4.0 gate in CI, add gates.crap.baseline: <tracked path> to rust-tops.yaml, run cargo tops gate once, run cargo tops crap-baseline, and commit the baseline. Without a baseline every function is judged as new.
  • Set protocol.version: "1.2.0" when you adopt the 1.2.0 text. A 1.1.0 instance still validates.
  • Add a root RUST-TOPS.md from config/drop-in/RUST-TOPS.md (§14.4).

Added

  • Coverage floors in cargo tops gate: the crate's line and region totals against gates.coverage.line_min_pct and region_min_pct, and each production file against per_file_line_min_pct, with every failing file listed. The coverage layer adds cargo llvm-cov report --json --summary-only after its run and judges that summary (§7.5).
  • The CRAP threshold and ratchet in cargo tops gate: a new production function fails above gates.crap.threshold_agent (or threshold_production); a function in the baseline fails when it rises above the threshold, or, if it was already above it, above its baseline score plus 0.01 (§2.1, §16).
  • cargo tops crap-baseline: writes the last gate's CRAP report, sorted by file and function, to gates.crap.baseline or to crap-baseline.json in the Cargo target directory.
  • gates.crap.baseline in the schema and the typed config.
  • §19 exemptions in the gate: layer: crap by path glob and optional symbol, layer: coverage by path for the per-file floor. An expired exemption, or one whose date is not a day, exempts nothing and fails the gate.
  • cargo tops init writes RUST-TOPS.md, the adoption record, filled from the instance it writes. The template is config/drop-in/RUST-TOPS.md, a hand copy of crates/cargo-tops/templates/drop-in/RUST-TOPS.md that xtask sync checks.
  • This repository's own baseline, crap-baseline.json, is the CRAP report of main at the 0.3.0 release merge, and its root RUST-TOPS.md records its own adoption.
  • cargo-tops --version and cargo tops --version print the package version. cargo tops version prints the package, the protocol it implements (1.2.0) and the tool pins in ./rust-tops.lock, or says there is none.
  • .github/workflows/release.yml: on a pushed v* tag it builds cargo-tops for x86_64-unknown-linux-gnu and aarch64-apple-darwin, writes sha256 sums, attests build provenance, and creates the GitHub release with this changelog section. Its crates.io job uses trusted publishing and runs only when the repository variable CRATES_IO_TRUSTED_PUBLISHING is true. No registry token is stored.
  • A publish-dry-run job in the kit workflow (cargo publish --dry-run -p cargo-tops --locked), and cargo run -p xtask -- pins, which fails when the drop-in's cargo-tops install version differs from the workspace version. CI runs it.
  • A nextest-macos job (macOS, Rust 1.99.1, Nushell 0.108.0 fetched by sha256) and a workflow-lint job (actionlint 1.7.12 fetched by checksum, over .github/workflows/ and config/drop-in/, with the bare job files wrapped before they are linted).
  • cargo run -p xtask -- docs: fails when the README pin table disagrees with Cargo.toml, the rust-tops.lock tool pins, or the number of profiles/*.yaml. CI runs it.

Changed

  • Protocol 1.2.0 (RUST_TOPS.md): §2.1 says the thresholds apply to new and changed production functions and existing code is held by the baseline ratchet; §2.2 allows a dated crap exemption for an exhaustive dispatch match instead of a split, and names counting such a match as one decision as a candidate for a future major version; §5.6 reconciles density.max_fn_cc with the agent CRAP threshold without changing either; §7.5 and §16 say how the gate judges the floors and the baseline; §14.4 requires the RUST-TOPS.md record; §19 says how exemptions are matched. The §16 .cargo-crap.toml example matches the drop-in.
  • Coverage and CRAP rows belong to the instance's crate: the package crate.name names (from the gate directory's Cargo.toml or cargo metadata), else the gate directory. Files under any tests/, benches/ or examples/ directory, and files that gates.coverage.exclude_globs match at any depth, are not production. This is what kept src/tests/ files, which cargo llvm-cov leaves out of its report, from reaching the CRAP judgment with no coverage. The coverage run itself stays workspace-wide, so a test in any member counts and the run still stands for unit, integration and property.
  • Both schema $ids, the example instance, the init template and this repository's rust-tops.yaml move to 1.2.0. config/rust-tops.lock.example sets [notes] schema to 1.2.0.
  • AGENTS.md (repo root, init template, init golden) is the 1.2.0 harness: the gate judges the floors, the baseline ratchet, the dispatch-match exemption, and never refreshing the baseline to let a score rise.
  • The drop-in workflow installs cargo-tops 0.4.0 and says to name a tracked baseline. The init goldens are re-recorded for that pin, RUST-TOPS.md, and protocol.version.
  • cargo tops init reads the crate it runs in: crate.name, edition and msrv come from cargo metadata (msrv from rust-version, else the lock's rustc, said on stdout), hot_paths is empty, and unsafe_policy follows the crate's lint table. It no longer writes parser-codec defaults. It writes rust-tops.lock, writes no rust-toolchain.toml when one exists in the crate directory or a parent up to the workspace root, and writes the Bend files only with --laws, which also enables the laws layer. Plain init leaves it disabled.
  • The gate runs each cargo deny check kind once: static-lint runs bans, licenses and sources, and security-advisory runs advisories.
  • The drop-in installs cargo-deny, cargo-nextest, cargo-llvm-cov and cargo-mutants at the versions in config/rust-tops.lock.example. Every overlay checkout sets persist-credentials: false. The Miri and fuzz overlays use one dated nightly, recorded in the lock notes. Both schema $ids are https URLs for this repository at v0.4.0.
  • The nextest and coverage-crap jobs stay in this repository's workflow as the drop-in floor jobs that the laws layer requires. They are not required checks: tops-gate runs the same suite and coverage on Linux.

Fixed

  • The coverage and crap layers judged nothing: gate passed with any coverage and any CRAP score once the reports were nonempty.
  • A relative CARGO_TARGET_DIR is read under the gate directory, where the gate runs Cargo, not under the caller's working directory. With --path pointing at a crate, the reports now sit where Cargo writes its build.
  • cargo publish could not build the cargo-tops tarball: the profile data was read from outside the crate. The profiles are copied under crates/cargo-tops/templates/profiles/, and xtask sync keeps them equal to profiles/.
  • The cargo_argv test runs the binary it just built, with an empty CARGO_HOME and only the environment cargo needs. The xtask sync tests run the built xtask binary instead of cargo run, which took about 1 s in all and ended the 20 s timeouts.
  • The README, the laws guide and the policies note stated facts that were no longer true: the previous tag, the tool lock rustc, the protocol version in the contrast table, the number of profile files and --class values, the docs.rs row for a version not yet published, what init writes for the laws layer, and a cognitive-complexity key the drop-in does not have. The rust-tops.lock notes name schema 1.2.0.