Add Version.diff classification matching node-semver 7.7.2 - #493

Hi @masonjian, thanks for picking up #262! Really appreciate your contribution! ❤️ The tests and docs are thorough.

Unfortunately, I don't think this PR addresses the original issue. The motivating example is choosing a bump on a staging branch. If staging is 1.0.1-rc.1 and master is 1.0.1, the answer should be bump_minor(). Here, Version.parse("1.0.1-rc.1").diff(Version.parse("1.0.1")) returns 'prerelease', which would point users to bump_prerelease().

I'd like to propose a different direction: make diff match node-semver's diff. Node's semver.diff (checked against semver@7.7.2) differs in ways people will likely notice:

Node returns a bump type with a pre prefix for prerelease targets, ignores build metadata, and is direction-aware.

Python users who know node-semver would then get the same answers, and the function would return a bump type rather than a field name. Node's algorithm ports cleanly:

def diff(self, other: Comparable) -> str | None:
    # operand coercion as in the current version

    cmp = self.compare(other)
    if cmp == 0:
        return None

    high, low = (self, other) if cmp > 0 else (other, self)
    high_pre = bool(high.prerelease)
    low_pre = bool(low.prerelease)

    if low_pre and not high_pre:
        if not low.minor and not low.patch:
            return "major"
        if low.to_tuple()[:3] == high.to_tuple()[:3]:
            return "minor" if low.minor and not low.patch else "patch"

    prefix = "pre" if high_pre else ""
    for part in ("major", "minor", "patch"):
        if getattr(self, part) != getattr(other, part):
            return prefix + part
    return "prerelease"

What this changes:

• Build-only differences return None, because compare() ignores build metadata. This matches node and ==, so the 'build' return value goes away.
• The result depends on which version is higher, matching node's behavior.
• The return values are major, minor, patch, premajor, preminor, prepatch, prerelease, or None.
  Node's quirks come along. For example, 1.0.0-alpha → 1.0.0 returns major, and 1.0.1-rc.1 → 1.0.1 returns patch.

This still doesn't solve the staging case from #262, since node returns patch there too. If you want that answer, it would need a separate, explicitly named method, or docs showing how to combine diff with a core comparison.

This is a rewrite of the method and its tests rather than a patch. The tests could be based on node-semver's own diff test cases, which would give good coverage and a clear parity check. The docs would also need to change from "first differing part" to "bump type, matching node-semver".

Happy to review a revision, and it may be worth agreeing on the direction in #262 first.