Skip to content

Releases

cargo-tops v0.4.0

Choose a tag to compare

@github-actions github-actions released this 17 Nov 23:06
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.

v0.3.0

Choose a tag to compare

@VirtualMachinist VirtualMachinist released this 15 Nov 17:04
91417b5

cargo-tops v0.3.0 (protocol 1.1.0)

Package plane only. Protocol stays 1.1.0.

Changes since v0.2.0 (e0fa684, 2026-10-21).

crates.io

cargo-tops 0.3.0 is not on crates.io. cargo publish failed package verification on this tag: crates/cargo-tops/src/profile_data.rs embeds the repo-root class profiles with include_str!("../../../profiles/..."). Those files live outside the crate, and the package include list does not ship them, so the crates.io tarball cannot build. Workspace and CI builds on this commit succeed; the published package does not. The same include_str! paths are still on main.

Until a packaging fix ships, install from this tag (a git/workspace build, not the crates.io tarball):

cargo install --git https://github.com/Hedronite/rust-tops --tag v0.3.0 cargo-tops --locked

Security

  • rustix 1.1.5 → 1.1.6 (direct dependency of cargo-tops and xtask) to clear RUSTSEC-2026-0486 (unsound zero-length xattr buffer). MSRV stays 1.99.1 (#29).

Added

  • Three agent skills, rust-tops-adopt, rust-tops-gate, and rust-tops-review. Each is a SKILL.md plus a Nushell script that wraps cargo tops and prints {ok, command, data}. cargo tops init --skills writes that layout as ordinary files under .agents, .claude, .cursor, and .grok (no symlinks) (#13).
  • Class profiles as data: library-util, ffi-bridge, and workspace-root, merged over the template. init writes the chosen class profile as data, and check refuses a crate that has none (#17).
  • xtask sync writes and checks the hand copies listed in copies.toml. init refuses a symlinked main.bend (#19).
  • The kit CI run of cargo tops gate in the drop-in, so an adopting tree can take the same gate the kit uses (#18).
  • A BeautifulRust v1.5.0 strict lint table as the style companion for the kit, with the MIT terms noticed and the lint table marked as adapted. The BeautifulRust MIT text ships in the cargo-tops package (#25).
  • docs/REVIEW.md, the review gate. It does not change CRAP, coverage, or mutation.

Changed

  • cargo tops and cargo-tops are the same binary. Cargo passes tops as the first argument; the binary drops that word before clap parses.
  • Gate layers are judged as argv steps. An enabled layer with no command is NotRun and fails the gate. A missing origin/main is an empty mutation diff, reported as such (#15, #16).
  • One coverage run is the test run of unit, integration, and property tests. CRAP is wired only to a fresh lcov file from a coverage run that passed (#20).
  • The workspace MSRV, rust-version, and rust-toolchain.toml channel are 1.99.1.
  • cargo-crap is pinned to 0.9.0 and to rust-tops.lock, with parent directories held open around the report path (#22).
  • The kit and drop-in workflows pin taiki-e/install-action to v2.88.1, with no fallback install of cargo-crap (#23). The opt-in fuzz job installs cargo-fuzz with Cargo and pins its actions (#24). Remaining Swatinem/rust-cache steps are pinned to v2.9.3 (#26, #27).
  • unwrap and expect are denied outside tests in the kit modules. The strict lint table names its pedantic lints instead of enabling the whole group.

Fixed

  • Report-directory handling reuses one cargo metadata answer, writes lcov and CRAP under that directory, and creates parent directories before looking for them (#21).

Docs

  • Adoption floor for a multi-crate workspace (#14).
  • README reflects the v0.2.0 tag, release, and crates.io publish (#12).

Pull requests since v0.2.0

#12, #13, #14, #15, #16, #17, #18, #19, #20, #21, #22, #23, #24, #25, #26, #27, #28, #29.

MSRV

Building cargo-tops needs Rust 1.99.1, the same tool MSRV as 0.2.0.

Full changelog: https://github.com/Hedronite/rust-tops/blob/v0.3.0/CHANGELOG.md

Compare: v0.2.0...v0.3.0

v0.2.0

Choose a tag to compare

@cursor cursor released this 22 Oct 03:47
e0fa684

cargo-tops v0.2.0 (protocol 1.1.0)

rust-tops is a testing and optimization protocol for Rust crates, and cargo-tops is the Cargo subcommand that sets it up (init), validates it (check) and runs its gates (gate).

This release adds protocol 1.1.0's laws layer: cargo tops gate now checks your crate's own files and gate reports against the Bend law pack LAWS.bend.

Breaking

cargo tops gate can now fail on Bend laws. When the laws layer is enabled (a fresh cargo tops init enables it) and this is not --dry-run, gate:

  • needs the Bend version pinned in laws/bend.lock (2.0.36). It looks on PATH, then in $HOME/.bend/bin. If that binary is absent, gate runs sh scripts/fetch-bend.sh, which checks the sha256.
  • exits 1 before any other layer when laws/bend.lock is missing, or when the lock has no [bend] version. A missing scripts/fetch-bend.sh exits 1 the same way only when that Bend is not already installed. A failed fetch exits 1 before any other layer. Those stops print fail: laws: ....
  • fails when bend returns Refuse. In 0.1.4, gate never looked for Bend.

The gate summary line changed. A failing run that gets past the Bend check now prints fail: N problem(s), M command(s) run. 0.1.4 printed fail: N of M command(s). The success line stays ok: N command(s) passed.

cargo tops init output changed. It now writes rust-toolchain.toml (channel = crate.msrv; every bundled profile sets crate.msrv to 1.88), laws/bend.lock, and scripts/fetch-bend.sh. The workflow it writes does not install stable: each job reads channel from rust-toolchain.toml and passes it to dtolnay/rust-toolchain at commit 683b588, which has no default toolchain. A missing rust-toolchain.toml fails that read. An empty channel fails the install.

Migration from 0.1.4

  1. cargo install cargo-tops --version 0.2.0 --locked
  2. A repo that keeps protocol.version: "1.0.0" and does not list laws still validates. cargo tops check accepts it, and cargo tops gate does not call Bend. The failure summary above is the change for that repo.
  3. To adopt the laws layer, set protocol.version: "1.1.0" and add { id: laws, enabled: true, tier: 0, runner: bend } to layers. The schema requires id, enabled, and runner. The bundled template also sets scope: workspace. Copy in laws/bend.lock and scripts/fetch-bend.sh. cargo tops init skips a file that already exists and prints skip existing <path>. Run it in a scratch directory and copy those files in, or overwrite with cargo tops init --force and review the diff. The flag is --force. There is no short flag.
  4. If you take the new workflow, add a rust-toolchain.toml with a versioned channel.
  5. Run cargo tops gate and read target/rust-tops/cases.json for each law's verdict.

Upgrading from 0.1.4 keeps the same YAML reader and the same tool MSRV. Building cargo-tops needs Rust 1.99.1, which is this package's MSRV. crate.msrv is the adopter crate's floor: cargo tops init writes it into rust-toolchain.toml, and every bundled profile sets it to 1.88. Coming from 0.1.3 or earlier, the 0.1.4 reader still applies: rust-tops.yaml is read by serde-saphyr 2.0.0 with strict booleans (yes/no/on/off/y/n stay strings; a typed bool rejects them), duplicate keys error, << merge keys apply, and .inf/.nan are rejected on a serde_json::Value (an f64 field still accepts them). See the CHANGELOG [0.1.4] entry.

Added

  • Protocol 1.1.0: RUST_TOPS.md §3.1 defines the laws layer. For each law the runner picks one case from the crate's files or this run's reports, and bend judges a program that imports LAWS.bend. Refuse fails the run, Ack is recorded, and a law with no fact is not-evaluated, never a pass. §22 makes a Refuse from an enabled laws layer normative.
  • schema/rust-tops.schema.json adds laws to the layer ids. Both schema $ids move to v1.1.0. config/rust-tops.lock.example sets [notes] schema to 1.1.0. init does not write rust-tops.lock.
  • gate runs the laws layer last, writes target/rust-tops/cases.bend and target/rust-tops/cases.json, and prints every law.
  • Fifteen laws can take a case from your files, including msrv_enforced, lock_honesty, clippy_toolchain_pinned, missing_tool_not_green, and single_deny_site. Each of those fifteen is not-evaluated when its file or report is absent. The other 38 are always not-evaluated.
  • init adds class jobs to the workflow: fuzz-smoke (parser-codec), miri (no-std-embedded, unsafe-kernel), kani and callgrind-hot (unsafe-kernel). Each fails when its tool is missing.
  • A fresh cargo tops init && cargo tops gate exits 0 for every class init offers (tested with a stubbed Bend and with Bend 2.0.36).
  • Nix: overlays.default exposes rust-tops-bend (Bend 2.0.36) on x86_64-linux and aarch64-linux. On Darwin, use scripts/fetch-bend.sh.

Changed

  • cargo-tops now depends on toml 1 to read laws/bend.lock, Cargo.toml lints, Cargo config rustflags, and rust-toolchain.toml.
  • The drop-in workflow pins dtolnay/rust-toolchain by commit (683b588) and takes the toolchain from rust-toolchain.toml.

Docs

  • The README badge block is two rows (#8).
  • The Bend gate docs say what bend PROOF.bend proves on this repository and what an adopter's laws layer does not prove (#9).
  • The README and BEND2-INTEGRATION.md describe protocol 1.1.0 and the laws layer (#10).

Known limits

  • bend stops at the first refusal. Laws after it print unreported.
  • No source scanner yet. Laws about Rust source stay not-evaluated.
  • An adopter's gate never downloads Lean. The Lean --verdict recheck stays this repository's proof of the catalog.

MSRV and install

Building cargo-tops needs Rust 1.99.1, the same tool MSRV as 0.1.4. That number is not the adopter crate.msrv (1.88 in the bundled profiles).

cargo install cargo-tops --version 0.2.0 --locked

Full changelog: https://github.com/Hedronite/rust-tops/blob/main/CHANGELOG.md

Compare: v0.1.4...v0.2.0

v0.1.4

Choose a tag to compare

@VirtualMachinist VirtualMachinist released this 21 Oct 04:00
7b1b8aa

Package 0.1.4. Protocol 1.0.0 is unchanged.

Compatible patch over v0.1.3. One release covers the unpublished work since that tag.

  • Fail-closed Bend gate: Bend 2.0.36 and Lean 4.34.0 are pinned, a missing bend fails, and law-diff guards laws/.
  • PROOF.bend is one claim per line. The 53 claim strings are unchanged.
  • cargo-tops reads rust-tops.yaml with serde-saphyr 2.0.0. unsafe-libyaml is gone.
  • Compiling cargo-tops from source needs Rust 1.99.1. Cargo refuses an older compiler before the build.

The two version planes stay separate. Adopters still pin protocol.version: 1.0.0.

v0.1.3

Choose a tag to compare

@VirtualMachinist VirtualMachinist released this 25 Sep 13:26
62bbac4

Compatible 0.x patch. Protocol plane stays 1.0.0. Schema stays Bend-free.

Maintainer tooling: scripts/gen-laws.py → scripts/gen-laws.rs (native Cargo script, RFC 3502, std-only). Regenerated H-01..H-53 pack is byte-identical. Package-plane wiring bumped to 0.1.3.

cargo install cargo-tops
cargo +nightly -Zscript scripts/gen-laws.rs
./scripts/bend-gate.sh

Identity lock: git tag v0.1.3 = Cargo 0.1.3 = crates.io cargo-tops. v0.1.2 was not moved.

v0.1.2

Choose a tag to compare

@VirtualMachinist VirtualMachinist released this 25 Sep 12:07

Compatible 0.x patch. Protocol plane stays 1.0.0. Schema stays Bend-free.

Provisional Bend2 pack: harvest H-01..H-53 encoded as laws/LAWS.bend. Hard rows Refuse, soft rows Ack. Not a protocol bump.

Nix flake overlay: overlays.default exposes cargo-tops and rust-tops-laws.

cargo install cargo-tops
cargo tops init --class parser-codec   # now writes LAWS.bend
./scripts/bend-gate.sh
nix build github:Hedronite/rust-tops#rust-tops-laws

Identity lock: git tag v0.1.2 = Cargo 0.1.2 = crates.io cargo-tops. v0.1.1 was not moved.

v0.1.1

Choose a tag to compare

@VirtualMachinist VirtualMachinist released this 25 Sep 05:03

Compatible 0.x patch. Protocol plane stays 1.0.0.

cargo-tops is now on crates.io:

cargo install cargo-tops
cargo tops init --class parser-codec

Fixed

  • Drop-in kit is vendored in the crate (templates/) so cargo package / cargo install cargo-tops is self-contained. v0.1.0 was git-only; include_str pointed at workspace files outside the crate.

CLI verbs init / check / gate unchanged. Identity lock: git tag v0.1.1 = Cargo 0.1.1 = crates.io cargo-tops.

v0.1.0

Choose a tag to compare

@VirtualMachinist VirtualMachinist released this 25 Sep 04:57

First public kit of the Rust Testing and Optimization Protocol Suite.

Plane Number
Protocol 1.0.0 (RUST_TOPS.md, schema)
Package / git tag 0.1.0 (this tag). First published tag; not 0.0.x.

This repository is a template / framework / protocol, not a product-crate instance.

Ships

  • Normative protocol + JSON Schema
  • Drop-in kit: clippy, nextest, mutants, crap, deny, GHA floor
  • Harvested GHA floor: sysdeps-before-all-features, honest MSRV, feature-matrix, nonempty record-only coverage. No job-level RUSTFLAGS. No --fail-under-lines.
  • POLICIES.md gates/checks
  • BEND2-INTEGRATION.md candidate laws (not protocol 1.0)
  • cargo-tops init / check / gate
  • Fixtures: parser-codec, no-std-embedded

Adopt: copy config/drop-in/ and config/rust-tops.example.yaml, or cargo install --path crates/cargo-tops && cargo tops init.