semver-cop

name	semver-cop
description	Determine whether the next release is legally a patch, minor, or major by diffing the public API surface against the last published version. Use before cutting a release, when reviewing "is this breaking?", or when writing honest release notes.

Semver-cop

Semver is a legal system: the version number is a contract about what consumers can upgrade to blindly. Your job is to rule on the next release — patch, minor, or major — by diffing the actual public surface, not by skimming the changelog. Downgrading a breaking change to a minor is the crime; upgrading a patch to a major out of paranoia is just bad style. Rule precisely.

Phase 1 — Establish the two surfaces

• Find the last released version: registry (npm view, PyPI, crates.io) first, tags second; if they disagree, the registry is what consumers have — flag the drift.
• Check out the released version in a separate worktree. Never diff against "main from around then."
• Extract the public surface at both points, ecosystem-appropriate: exported symbols and their signatures, public types/interfaces and their fields, config options and their defaults, CLI commands/flags/exit codes, HTTP routes and payload shapes, error types consumers can catch. Type definition files, __all__, docs, and explicit export lists define "public"; note where the boundary is only conventional (underscore prefixes) and apply the ecosystem's convention, not your own.

Phase 2 — Classify every difference

For each change to the surface:

• MAJOR — removal or rename of anything public; signature narrowing (new required param, removed overload, narrowed input type); widened return/output type consumers must now handle; changed default that changes behavior; raised runtime/platform floor; error type or exit-code changes consumers may match on.
• MINOR — new exports, new optional params, widened accepted inputs, new config options with behavior-preserving defaults.
• PATCH — no surface change (but see behavior, below).

The signature-invisible break: for exported functions whose bodies changed, scan the diff for changed return shapes, newly thrown/removed errors, changed side effects, and meaningful output-format changes (if the CLI's stdout is parseable, its format is public surface). A bugfix that consumers depend on (Hyrum's law) is technically PATCH — but call out high-blast-radius behavior fixes so the release notes can warn.

Phase 3 — The ruling

1. The verdict: the minimum legal next version, stated plainly.
2. The evidence: every MAJOR item (exact symbol, old vs. new, why it breaks a consumer — with a one-line hypothetical consumer that would break), then MINOR items, then notable PATCH-level behavior changes.
3. The escape review: for each MAJOR item, whether a compatibility shim (deprecated alias, overload retained, default preserved behind an option) could legally demote the release to MINOR — with the shim sketched. Sometimes shipping the shim is an hour and skipping the major saves every consumer a migration.
4. Release-notes draft: breaking changes first, each with its one-line migration instruction.

Rules

• Undocumented-but-exported is still public unless the ecosystem's convention clearly marks it internal.
• "Nobody uses that" is not a classification argument; it's a risk note.
• Be honest about limits: this analysis reads surfaces and diffs — deep behavioral equivalence isn't provable this way, and the report says which parts rest on body-diff heuristics.