semver-guard

name

semver-guard

description

Catch breaking changes before you call a release a patch. Triggers when you're about to bump a version, publish, or describe a change as patch/minor (or on /semver-guard). It reads the diff to the public surface — exports, function signatures, types, return shapes, defaults — classifies each change as breaking / additive / internal, and refuses to let a breaking change ship under a patch or minor label.

semver-guard — catch breaking changes before you call it a patch

You're about to release. The version bump you pick is a promise: patch means "safe to update blindly", minor means "new stuff, nothing removed", major means "this will break callers". semver-guard checks that the bump matches what the diff actually did to your public surface — because a breaking change shipped as a patch is how you wake up to a hundred broken builds.

When to run

• Automatically, when you're about to bump the version, publish, tag a release, or call a change "a patch" / "a minor" / "non-breaking".
• On demand when the user types /semver-guard.

What it looks at

The diff to the public surface only — what consumers can import and call: exported functions/classes/constants/types, public methods and fields, the package's declared API (e.g. exports/main/types, __all__, pub), and documented behavior. Internal/private changes don't affect the bump.

The classification

Go through the changed public surface and label each:

• ✗ breaking (major) — removed or renamed an export; added a required parameter; changed a parameter's type or order; narrowed a type or made a field required; removed an enum member; changed a return type/shape; changed a default that callers relied on; tightened input validation that used to pass; changed an error type thrown.
• ✓ additive (minor) — new export; new optional parameter; new optional field; a widened (more permissive) type; a new enum member (usually).
• · internal (patch) — bug fix, refactor, perf, docs, tests — no public surface change.

The bump rule

The release is at least the highest class present: any ✗ → major, else any ✓ → minor, else patch. Do not let the user ship a breaking change under a patch or minor label — either bump to major, or keep the old surface working (re-export the old name, make the new param optional, add an overload, deprecate instead of remove).

What to do with findings

• For each breaking change, say whether it can be made non-breaking cheaply (re-export, optional param, overload, deprecation shim) and offer that, or confirm it genuinely requires a major.
• Don't invent breaks. A renamed local variable or a changed private helper is not a breaking change — only the public surface counts.

Output format

semver-guard — N change(s) to the public surface
  ✗ breaking  removed export `parseConfig`                 → major
  ✗ breaking  `fetch(url)` now requires `fetch(url, opts)`  → major (make opts optional to avoid)
  ✓ additive  new optional export `withRetry`              → minor
  · internal  refactored the cache (no surface change)     → patch
This is a MAJOR bump. You called it a patch.

Keep it tight. Public surface only. The bump should never lie about what changed.