semver_compare
Compare two TypeScript library versions to detect breaking API changes and recommend the SemVer bump, using paths, git refs, or npm specs.
Instructions
Compare two versions of a TypeScript library and detect breaking API changes. Use it to decide or check a SemVer bump; use semver_snapshot to list what one version exports without comparing it. Either side can be a filesystem path, a git ref, or an npm spec, so a working tree can be compared against the published release without checking anything out.
npm specs and git refs need network access and are unpacked into temp directories that are removed afterwards; nothing in a local path is written unless "installDeps" is set.
Returns the recommended SemVer bump (major/minor/patch) and a list of changes. Each change carries a confidence: "proven" (a structurally confident break) or "heuristic" (a conservative major the tool could not prove safe), and summary.majorProven / majorReview split the major count accordingly. The "gate" field gives what each CLI gate would exit with: "strict" fails only on a proven break, "strictReview" on any major. A "strict" pass does not mean nothing broke, since a break the tool could not prove stays review-only, so report both. Pass "declared" to grade the release against the bump it writes down instead of recommending one; a major it already declares then passes both gates.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"old": "<old>"
},
"name": "semver_compare"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| new | No | New version: a filesystem path, a git ref, or an npm spec. Defaults to current directory. | . |
| old | Yes | Old version: a filesystem path, a git ref (tag, branch, commit SHA), or an npm spec. A "name@version" that is not an existing path is read as npm (e.g. "lodash@4.17.21", "lodash@latest"); prefix with "npm:" to say so outright. | |
| entry | No | Entry file relative to project root (e.g. "src/index.ts"). Pass an array or a comma-separated string for a package with several entry points. Auto-detected from package.json if omitted. | |
| newAs | No | Force "new" to be treated as a filesystem path, a git ref, or an npm spec. "ref" is an accepted spelling of "git". | |
| oldAs | No | Force "old" to be treated as a filesystem path, a git ref, or an npm spec. "ref" is an accepted spelling of "git". Only needed when auto-detection would read the input as the wrong kind, which is what a monorepo tag shaped like "pkg@1.2.3" needs. | |
| declared | No | The bump this release declares, or "auto" to read it from .changeset/*.md and then the two package.json versions. Adds a "declaration" verdict to the report: "mismatch" when a proven break outranks the declaration, "review" when the changes argue for more than was declared, "ok" otherwise. Errors when "auto" finds nothing to read, rather than reporting a pass. | |
| maxChanges | No | How many changes to include (default 50). They are ordered proven breaks first, then additions, then review-only ones, so the cap drops the least actionable end. "summary" always counts every change, and an "omitted" field reports what was left out and the number to pass to get all of it. | |
| installDeps | No | Install dependencies before analysis. In a local path with no node_modules this runs "npm install --ignore-scripts" in that directory, and adds @types/node there if it is missing. Only a local path needs it: a git ref is always installed in its temp copy. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| gate | Yes | ||
| changes | Yes | ||
| omitted | No | ||
| summary | Yes | ||
| declaration | No | ||
| recommended | Yes |