Skip to content

v0.2.0

Choose a tag to compare

@cursor cursor released this 22 Oct 03:47
· 250 commits to main since this release
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