Repository navigation
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.