#semver #violation #scan #rustdoc #query #check #enums

yanked cargo_semver_check

Scan your Rust crate for semver violations

0.2.0 Jul 13, 2022
0.1.0 Jul 12, 2022

#7 in #violation

Apache-2.0

51KB
1K SLoC

Rust 725 SLoC // 0.0% comments Rusty Object Notation 214 SLoC GraphQL 153 SLoC // 0.1% comments

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 some cargo 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 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 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-generated doc/<your-crate-name>.json file.
  • cd back to the cargo-semver-check directory (temporary, should be removed shortly).
  • From the cargo-semver-check directory, run cargo 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 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.

Dependencies

~14–24MB
~397K SLoC