Semver Bump Decider

What this skill does

Compares two git refs of a library and decides whether the next version should be MAJOR, MINOR, or PATCH per semver. The decision is grounded in concrete changes: removed exports, signature shape changes, and added APIs.

Inputs

• repo_dir: library source root.
• from_ref, to_ref: git refs (commit hashes, tags, or branches).
• language: ts, js, py, or go (drives the API extraction tool).
• Optional private_paths: paths excluded from public-API analysis.

Steps

1. Confirm both refs exist: git -C <repo_dir> rev-parse <ref>.
2. Extract API shape at each ref:
   • TS: git checkout <ref>; api-extractor run --local. Save the report.
   • Go: apidiff (golang.org/x/exp/cmd/apidiff) directly compares two builds.
   • Python: extract __all__ and signatures via inspect.signature on a temp install.
3. Diff the two API reports. Classify each change:
   • Removed exported symbol -> breaking.
   • Renamed exported symbol -> breaking.
   • Required parameter added -> breaking.
   • Type narrowed -> breaking.
   • New optional parameter added -> additive.
   • New exported symbol -> additive.
   • Documentation-only -> patch.
4. Inspect commit messages between refs for Conventional-Commit hints: BREAKING CHANGE: footer or ! after type, feat: -> minor, fix: -> patch.
5. Decision: any breaking -> MAJOR; any additive (and no breaking) -> MINOR; only patch-level -> PATCH.
6. Compose a report with the decision, the per-change classification, and a "Why" line per breaking change.
7. Suggest the new version string given the current version (read from package.json / pyproject.toml / go.mod).
8. Save the report.

Output

semver-decision.md with: decision (MAJOR/MINOR/PATCH), suggested next version, table of API changes with classification, recommended changelog draft. Plus api-diff.json for tooling. Stdout prints the decision and the next version.

Verification

Manually inspect two random API changes and confirm the classification matches semver guidance. Re-run with --strict mode in api-extractor (or apidiff) and confirm no missed breaking change. Cross-reference with Conventional Commits: a feat!: in the range that didn't appear in the breaking list indicates an extraction gap.

Edge cases

• Pre-1.0 (0.x): semver treats minor changes as breaking-allowed; surface a note that any breaking change advances to 0.next.
• Internal-only refactor (no API change): decision is PATCH; explicitly note "no public API changes".
• New deprecation (warning added but symbol still works): MINOR.
• Repos with no public API surface (apps, not libs): decision unhelpful; refuse with a "this is an application, not a library" note.