Scan your Rust crate for semver violations.
Queries rustdoc-generated crate documentation using the trustfall
"query everything" engine.
Each query looks for a particular kind of semver violation, such as:
- public struct was removed
- public plain struct's public field was removed
- public enum was removed
- public enum's variant was removed
``` cargo install cargo-semver-checks
cargo semver-checks diff-files --current
cargo +nightly rustdoc -- -Zunstable-options --output-format json ```
This crate is a work-in-progress. It can catch some semver violations, and will miss many more.
Its queries and adapter implementation have not been optimized for runtime,
and will currently exhibit O(n^2) runtime growth on large codebases.
See the notes in the section below for details.
cargo-semver-checks to check your crateSteps:
- Perform a git checkout of your crate's last published version,
which will represent your semver baseline.
- Generate rustdoc documentation in JSON format for the crate's last published version
by running cargo +nightly rustdoc -- -Zunstable-options --output-format json.
- The above command will generate a file named doc/<your-crate-name>.json in your crate's
build target directory. Copy this file somewhere else -- otherwise it will be overwritten
by the next steps.
- Switch to the version of your crate that you'd like to check.
- Repeat the cargo rustdoc command above, and note
the newly-generated doc/<your-crate-name>.json file in your build target directory.
- Run cargo semver-checks diff-files --current <new-rustdoc> --baseline <previous-rustdoc>.
This step will run multiple queries that look for particular kinds of semver violations,
and report violations they find.
Notes:
- Only 5 violations per category are reported for now.
- If using it on a massive codebase (multiple hundreds of thousands of lines of Rust),
the queries may be a bit slow: there is some O(n^2) scaling for n items in a few places that
I haven't had time to optimize down to O(n) yet. Apologies! I have temporarily prioritized
features over speed, and the runtime will improve significantly with a small amount of extra work.
- No false positives: Currently, all queries report constructive proof of semver violations:
there are no false positives. They always list a file name and line number for the baseline item
that could not be found in the new code.
- There are false negatives: This tool is a work-in-progress, and cannot check all kinds of
semver violations yet. Just because it doesn't find any semver issues doesn't mean
they don't exist.
This crate was intended to be published under the name cargo-semver-check, and may indeed one
day be published under that name. Due to
an unfortunate mishap,
it remains cargo-semver-checks for the time being.