Add draft of proposed new library API.

[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, since it 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

This PR contains the code for discussion #599.

If you have general feedback about the idea, please post it in the discussion: #599

If you have feedback related to specific lines of code, please post it attached to those lines in this PR.

[obi1kenobi]

Note that the file name at the time this PR was opened is arbitrary and will not be merged as such. I added it so we get syntax highlighting and a proper review environment, without worrying about compile errors / imports / what is in which file.

[thomaseizinger]

An alternative to this design would be to model the internals of cargo semver-checks as a state machine that a binary or other consumer needs to manually advance. That is a bit more work to integrate but gives you greater flexibility. In other words, the library part would only offer building blocks that you can compose together with your own policy.

For example, if said state machine yields an event like:

struct WorkspaceCrateDiscovered {
	pub publish: bool,
	pub name: String
	// ...
}

We would also need APIs like:

pub fn load_crate_from_registry(name: &str) -> Result<...> { }

pub fn check_semver(base: &CrateData, new: &CrateData) -> Result<impl Iterator<Item = SemverViolation>, ...> {}

Upon encountering a WorkspaceCrateDiscovered event a user could then e.g. decide whether or not to continue checking the crate for semver-violations based on the publish field.