Draft new library API, to allow us finer-grained control over edge cases

[obi1kenobi]

As cargo-semver-checks is getting adopted by more and more projects, we're seeing more and more cases where our current APIs and config flags give users insufficient control over various edge cases that happen in the real world.

To address such edge cases, we'll need to expose a richer API in our lib target, which can then be used both as a dependency of other tools (e.g. release-plz) and directly via the CLI. I'm adding a draft for such a new API, and I'm looking for feedback!

Here are the issues we've seen so far, lightly grouped:

• "We failed to generate or read the rustdoc JSON."
  • Hitting a recursion limit while running cargo semver-check on diesel #108
  • Crate fails to compile #570
  • Failure to generate rustdoc when RUSTFLAGS env var sets -Dwarnings #589
• "There's no baseline version to check against."
  • Should skip if no baseline versions available  #146
  • Skip bin-only targets in --workspace runs #163
  • Improve error message when testing on not-yet-published crate #247
  • Option to skip crates whose Cargo.toml version is already published on the registry #356
  • Error message on previously nonexistent crate is a bit unhelpful #481
• "The baseline version exists but cannot be used."
  • The tool fails when generating rustdoc of a yanked release from registry #275
• "Unusual edge cases, where the library API can force handling them to happen at the layer above, which is better suited to the task"
  • cargo semver-checks might exit 0 if it finds only publish = false crates in a workspace #424
  • can fail when projects of same name are in a subdirectory #462
  • Notice if a run is going to be a no-op before generating rustdoc JSON #707

The proposed new lib target API is here: #600

If you have general feedback about the idea, please post it here.

If you have feedback related to specific lines of code, please post it attached to those lines in the PR: #600.