indrasvat/api-compat

API Compatibility Check

Detect breaking changes in API definitions. Read-only analysis, safe to re-run.

1. Prerequisites

Check for specialized tools via command -v: buf (protobuf), oasdiff (OpenAPI). Report availability. If missing, fall back to manual git-diff analysis and note which tool would improve accuracy.

2. Scope

If $ARGUMENTS names specific files, analyze only those. Otherwise, find API files changed since base branch using git diff --name-only $(git merge-base HEAD main). Detect by pattern:

| Pattern | Type | |---------|------| | *.proto | Protobuf | | openapi.yaml, swagger.json, *.openapi.*, *.swagger.* | OpenAPI | | *.graphql, *.gql | GraphQL | | *.go with exported types changed | Go exported API |

Stop with a clear message if no API files are found in scope.

3. Baseline

Compute and print the merge-base: git merge-base HEAD main. For each file in scope, diff working tree against that baseline using git diff <merge-base> -- <file>.

4. Analysis by Type

Protobuf

If buf is available, run buf breaking --against .git#ref=<merge-base>. Otherwise, manually inspect diffs for:

• BREAKING: field number reuse, field removal, type change, adding required fields
• SAFE: new optional field, new enum value with no renumbering

OpenAPI

If oasdiff is available, run oasdiff breaking <base-file> <current-file>. Otherwise, manually inspect diffs for:

• BREAKING: removed endpoint, changed HTTP method, removed parameter, new required parameter, response schema narrowing
• SAFE: new optional parameter, new endpoint, added response fields

GraphQL

Manually inspect diffs for:

• BREAKING: removed type/field, changed return type, new required argument, removed enum value
• SAFE: new optional field/argument, new type, new enum value

Go Exported API

Manually inspect diffs for:

• BREAKING: removed exported symbol, changed function signature, changed interface method set, changed struct field types
• SAFE: new exported symbol, new method on concrete type

5. Output

Print a summary line first: total changes found, how many breaking. Then print a compatibility report table:

| Change | File:Line | Type | Severity |

Severity values: BREAKING, WARN, SAFE. Use WARN when a change is technically non-breaking but likely to cause client issues (e.g., deprecating a widely-used field, adding an enum value to a closed enum).

6. Idempotency

Read-only. No files created, modified, or deleted. Safe to re-run at any time.

$ARGUMENTS