Repository navigation
v0.2.0
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 onPATH, then in$HOME/.bend/bin. If that binary is absent,gaterunssh scripts/fetch-bend.sh, which checks the sha256. - exits 1 before any other layer when
laws/bend.lockis missing, or when the lock has no[bend] version. A missingscripts/fetch-bend.shexits 1 the same way only when that Bend is not already installed. A failed fetch exits 1 before any other layer. Those stops printfail: laws: .... - fails when
bendreturnsRefuse. In 0.1.4,gatenever 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
cargo install cargo-tops --version 0.2.0 --locked- A repo that keeps
protocol.version: "1.0.0"and does not listlawsstill validates.cargo tops checkaccepts it, andcargo tops gatedoes not call Bend. The failure summary above is the change for that repo. - To adopt the
lawslayer, setprotocol.version: "1.1.0"and add{ id: laws, enabled: true, tier: 0, runner: bend }tolayers. The schema requiresid,enabled, andrunner. The bundled template also setsscope: workspace. Copy inlaws/bend.lockandscripts/fetch-bend.sh.cargo tops initskips a file that already exists and printsskip existing <path>. Run it in a scratch directory and copy those files in, or overwrite withcargo tops init --forceand review the diff. The flag is--force. There is no short flag. - If you take the new workflow, add a
rust-toolchain.tomlwith a versionedchannel. - Run
cargo tops gateand readtarget/rust-tops/cases.jsonfor 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 thelawslayer. For each law the runner picks one case from the crate's files or this run's reports, andbendjudges a program that importsLAWS.bend.Refusefails the run,Ackis recorded, and a law with no fact isnot-evaluated, never a pass. §22 makes aRefusefrom an enabledlawslayer normative. schema/rust-tops.schema.jsonaddslawsto the layer ids. Both schema$ids move tov1.1.0.config/rust-tops.lock.examplesets[notes] schemato1.1.0.initdoes not writerust-tops.lock.gateruns thelawslayer last, writestarget/rust-tops/cases.bendandtarget/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, andsingle_deny_site. Each of those fifteen isnot-evaluatedwhen its file or report is absent. The other 38 are alwaysnot-evaluated. initadds class jobs to the workflow:fuzz-smoke(parser-codec),miri(no-std-embedded, unsafe-kernel),kaniandcallgrind-hot(unsafe-kernel). Each fails when its tool is missing.- A fresh
cargo tops init && cargo tops gateexits 0 for every classinitoffers (tested with a stubbed Bend and with Bend 2.0.36). - Nix:
overlays.defaultexposesrust-tops-bend(Bend 2.0.36) onx86_64-linuxandaarch64-linux. On Darwin, usescripts/fetch-bend.sh.
Changed
cargo-topsnow depends ontoml1 to readlaws/bend.lock,Cargo.tomllints, Cargo config rustflags, andrust-toolchain.toml.- The drop-in workflow pins
dtolnay/rust-toolchainby commit (683b588) and takes the toolchain fromrust-toolchain.toml.
Docs
- The README badge block is two rows (#8).
- The Bend gate docs say what
bend PROOF.bendproves on this repository and what an adopter'slawslayer does not prove (#9). - The README and
BEND2-INTEGRATION.mddescribe protocol 1.1.0 and thelawslayer (#10).
Known limits
bendstops at the first refusal. Laws after it printunreported.- No source scanner yet. Laws about Rust source stay
not-evaluated. - An adopter's
gatenever downloads Lean. The Lean--verdictrecheck 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 --lockedFull changelog: https://github.com/Hedronite/rust-tops/blob/main/CHANGELOG.md
Compare: v0.1.4...v0.2.0