Repository navigation
Releases
cargo-tops v0.4.0
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
coverageorcraplayer enabled is now held to its numbers. Before the first 0.4.0 gate in CI, addgates.crap.baseline: <tracked path>torust-tops.yaml, runcargo tops gateonce, runcargo 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.mdfromconfig/drop-in/RUST-TOPS.md(§14.4).
Added
- Coverage floors in
cargo tops gate: the crate's line and region totals againstgates.coverage.line_min_pctandregion_min_pct, and each production file againstper_file_line_min_pct, with every failing file listed. The coverage layer addscargo llvm-cov report --json --summary-onlyafter its run and judges that summary (§7.5). - The CRAP threshold and ratchet in
cargo tops gate: a new production function fails abovegates.crap.threshold_agent(orthreshold_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, togates.crap.baselineor tocrap-baseline.jsonin the Cargo target directory.gates.crap.baselinein the schema and the typed config.- §19 exemptions in the gate:
layer: crapby path glob and optionalsymbol,layer: coverageby 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 initwritesRUST-TOPS.md, the adoption record, filled from the instance it writes. The template isconfig/drop-in/RUST-TOPS.md, a hand copy ofcrates/cargo-tops/templates/drop-in/RUST-TOPS.mdthatxtask syncchecks.- This repository's own baseline,
crap-baseline.json, is the CRAP report ofmainat the 0.3.0 release merge, and its rootRUST-TOPS.mdrecords its own adoption. cargo-tops --versionandcargo tops --versionprint the package version.cargo tops versionprints 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 pushedv*tag it buildscargo-topsforx86_64-unknown-linux-gnuandaarch64-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 variableCRATES_IO_TRUSTED_PUBLISHINGistrue. No registry token is stored.- A
publish-dry-runjob in the kit workflow (cargo publish --dry-run -p cargo-tops --locked), andcargo run -p xtask -- pins, which fails when the drop-in'scargo-topsinstall version differs from the workspace version. CI runs it. - A
nextest-macosjob (macOS, Rust 1.99.1, Nushell 0.108.0 fetched by sha256) and aworkflow-lintjob (actionlint 1.7.12 fetched by checksum, over.github/workflows/andconfig/drop-in/, with the bare job files wrapped before they are linted). cargo run -p xtask -- docs: fails when the README pin table disagrees withCargo.toml, therust-tops.locktool pins, or the number ofprofiles/*.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 datedcrapexemption for an exhaustive dispatchmatchinstead of a split, and names counting such a match as one decision as a candidate for a future major version; §5.6 reconcilesdensity.max_fn_ccwith the agent CRAP threshold without changing either; §7.5 and §16 say how the gate judges the floors and the baseline; §14.4 requires theRUST-TOPS.mdrecord; §19 says how exemptions are matched. The §16.cargo-crap.tomlexample matches the drop-in. - Coverage and CRAP rows belong to the instance's crate: the package
crate.namenames (from the gate directory'sCargo.tomlorcargo metadata), else the gate directory. Files under anytests/,benches/orexamples/directory, and files thatgates.coverage.exclude_globsmatch at any depth, are not production. This is what keptsrc/tests/files, whichcargo llvm-covleaves 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 forunit,integrationandproperty. - Both schema
$ids, the example instance, the init template and this repository'srust-tops.yamlmove to1.2.0.config/rust-tops.lock.examplesets[notes] schemato1.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-tops0.4.0 and says to name a tracked baseline. The init goldens are re-recorded for that pin,RUST-TOPS.md, andprotocol.version. cargo tops initreads the crate it runs in:crate.name,editionandmsrvcome fromcargo metadata(msrvfromrust-version, else the lock'srustc, said on stdout),hot_pathsis empty, andunsafe_policyfollows the crate's lint table. It no longer writes parser-codec defaults. It writesrust-tops.lock, writes norust-toolchain.tomlwhen 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 thelawslayer. Plaininitleaves it disabled.- The gate runs each
cargo denycheck kind once:static-lintrunsbans,licensesandsources, andsecurity-advisoryrunsadvisories. - The drop-in installs
cargo-deny,cargo-nextest,cargo-llvm-covandcargo-mutantsat the versions inconfig/rust-tops.lock.example. Every overlay checkout setspersist-credentials: false. The Miri and fuzz overlays use one dated nightly, recorded in the lock notes. Both schema$ids arehttpsURLs for this repository atv0.4.0. - The
nextestandcoverage-crapjobs stay in this repository's workflow as the drop-in floor jobs that the laws layer requires. They are not required checks:tops-gateruns the same suite and coverage on Linux.
Fixed
- The coverage and crap layers judged nothing:
gatepassed with any coverage and any CRAP score once the reports were nonempty. - A relative
CARGO_TARGET_DIRis read under the gate directory, where the gate runs Cargo, not under the caller's working directory. With--pathpointing at a crate, the reports now sit where Cargo writes its build. cargo publishcould not build thecargo-topstarball: the profile data was read from outside the crate. The profiles are copied undercrates/cargo-tops/templates/profiles/, andxtask synckeeps them equal toprofiles/.- The
cargo_argvtest runs the binary it just built, with an emptyCARGO_HOMEand only the environment cargo needs. Thextasksync tests run the builtxtaskbinary instead ofcargo 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
--classvalues, the docs.rs row for a version not yet published, whatinitwrites for the laws layer, and acognitive-complexitykey the drop-in does not have. Therust-tops.locknotes name schema 1.2.0.
v0.3.0
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 --lockedSecurity
rustix1.1.5 → 1.1.6 (direct dependency ofcargo-topsandxtask) 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, andrust-tops-review. Each is aSKILL.mdplus a Nushell script that wrapscargo topsand prints{ok, command, data}.cargo tops init --skillswrites that layout as ordinary files under.agents,.claude,.cursor, and.grok(no symlinks) (#13). - Class profiles as data:
library-util,ffi-bridge, andworkspace-root, merged over the template.initwrites the chosen class profile as data, andcheckrefuses a crate that has none (#17). xtask syncwrites and checks the hand copies listed incopies.toml.initrefuses a symlinkedmain.bend(#19).- The kit CI run of
cargo tops gatein 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-topspackage (#25). docs/REVIEW.md, the review gate. It does not change CRAP, coverage, or mutation.
Changed
cargo topsandcargo-topsare the same binary. Cargo passestopsas 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
NotRunand fails the gate. A missingorigin/mainis 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, andrust-toolchain.tomlchannel are 1.99.1. cargo-crapis pinned to 0.9.0 and torust-tops.lock, with parent directories held open around the report path (#22).- The kit and drop-in workflows pin
taiki-e/install-actionto v2.88.1, with no fallback install ofcargo-crap(#23). The opt-in fuzz job installscargo-fuzzwith Cargo and pins its actions (#24). RemainingSwatinem/rust-cachesteps are pinned to v2.9.3 (#26, #27). unwrapandexpectare 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 metadataanswer, 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
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
v0.1.4
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
bendfails, andlaw-diffguardslaws/. PROOF.bendis one claim per line. The 53 claim strings are unchanged.cargo-topsreadsrust-tops.yamlwith serde-saphyr 2.0.0.unsafe-libyamlis gone.- Compiling
cargo-topsfrom 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
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.shIdentity lock: git tag v0.1.3 = Cargo 0.1.3 = crates.io cargo-tops. v0.1.2 was not moved.
v0.1.2
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-lawsIdentity lock: git tag v0.1.2 = Cargo 0.1.2 = crates.io cargo-tops. v0.1.1 was not moved.
v0.1.1
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-codecFixed
- Drop-in kit is vendored in the crate (
templates/) socargo package/cargo install cargo-topsis self-contained.v0.1.0was git-only;include_strpointed 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
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.mdgates/checksBEND2-INTEGRATION.mdcandidate laws (not protocol 1.0)cargo-topsinit/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.