0.2.0 |
|
---|---|
0.1.0 |
|
#7 in #violation
51KB
1K
SLoC
cargo-semver-check
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
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.
Using cargo-semver-check
to check your crate
Steps:
- Choose a crate you'd like to scan for semver violations, and
cd
into its source directory in preparation for somecargo rustdoc
commands. - 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 runningcargo +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 step. - Perform a
git checkout
of the crate source code you'd like to check for semver violations. - Repeat the
cargo rustdoc
command above, and note the newly-generateddoc/<your-crate-name>.json
file. cd
back to thecargo-semver-check
directory (temporary, should be removed shortly).- From the
cargo-semver-check
directory, runcargo run diff <path-to-new-rustdoc-json> <path-to-baseline-rustdoc-json>
. 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 forn
items in a few places that I haven't had time to optimize down toO(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.
Dependencies
~14–24MB
~397K SLoC