regression-api-contract

What this skill does

# regression-api-contract

Detect breaking changes in API contracts across REST, GraphQL, and gRPC interfaces.

## Triggers


Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

- "breaking change" → API contract regression
- "schema compatibility" → contract validation
- "Pact" / "Swagger diff" → contract testing tool names

## Purpose

This skill detects API contract regressions by:
- Identifying breaking changes in REST API endpoints
- Detecting schema changes in request/response contracts
- Validating GraphQL schema compatibility
- Checking gRPC/protobuf definition changes
- Enforcing semantic versioning compliance
- Integrating consumer contract testing (Pact, Spring Cloud Contract)

## Behavior

When triggered, this skill:

1. **Identifies API contract scope**:
   - Discover API definition files (OpenAPI, GraphQL, protobuf)
   - Identify baseline version for comparison
   - Determine API type (REST, GraphQL, gRPC)
   - Locate consumer contract tests

2. **Compares contracts to baseline**:
   - Load current API definition
   - Load baseline API definition
   - Run compatibility analysis using appropriate tools
   - Generate detailed diff of changes

3. **Classifies changes by severity**:
   - **BREAKING**: Removed endpoints, fields, or enum values; type changes; new required fields
   - **NON-BREAKING**: New optional fields, new endpoints, extended enums
   - **DEPRECATED**: Marked for future removal
   - **INTERNAL**: Implementation changes with no contract impact

4. **Validates semantic versioning**:
   - Check if version increment matches change type
   - Ensure breaking changes trigger major version bump
   - Verify non-breaking changes use minor/patch versions
   - Flag version mismatches

5. **Runs consumer contract tests**:
   - Execute Pact or Spring Cloud Contract tests
   - Validate against consumer expectations
   - Identify consumers affected by changes
   - Generate compatibility matrix

6. **Generates compatibility report**:
   - List all breaking changes with locations
   - Document affected consumers
   - Recommend version bump strategy
   - Suggest migration paths for consumers

## Breaking Change Categories

### REST API Breaking Changes

```yaml
rest_breaking_changes:
  removed:
    - endpoint: "DELETE /api/v1/users/{id}"
      severity: BREAKING
      reason: "Endpoint removed entirely"

    - field: "email" from "User" response
      severity: BREAKING
      reason: "Required field removed from response"

    - enum_value: "PENDING" from "OrderStatus"
      severity: BREAKING
      reason: "Enum value removed"

  modified:
    - field: "created_at"
      from_type: "string"
      to_type: "integer"
      severity: BREAKING
      reason: "Field type changed"

    - field: "email"
      from_required: false
      to_required: true
      severity: BREAKING
      reason: "Optional field made required in request"

    - constraint: "password"
      from: "minLength: 6"
      to: "minLength: 12"
      severity: BREAKING
      reason: "Stricter validation on request field"

  renamed:
    - endpoint: "GET /api/v1/user/{id}"
      to: "GET /api/v1/users/{id}"
      severity: BREAKING
      reason: "Path renamed without redirect/alias"

    - parameter: "userId"
      to: "user_id"
      severity: BREAKING
      reason: "Parameter renamed without backward compatibility"
```

### GraphQL Schema Breaking Changes

```yaml
graphql_breaking_changes:
  removed:
    - field: "User.email"
      severity: BREAKING
      reason: "Field removed from type"

    - argument: "Query.users(filter: UserFilter)"
      severity: BREAKING
      reason: "Required argument removed"

    - type: "Address"
      severity: BREAKING
      reason: "Type removed from schema"

  modified:
    - field: "User.age"
      from_type: "Int"
      to_type: "String"
      severity: BREAKING
      reason: "Field type changed"

    - field: "User.email"
      from_nullable: true
      to_nullable: false
      severity: BREAKING
      reason: "Field made non-nullable"

    - argument: "Query.user(id: ID)"
      from_optional: true
      to_optional: false
      severity: BREAKING
      reason: "Argument made required"

  interface_changes:
    - interface: "Node"
      removed_implementation: "User"
      severity: BREAKING
      reason: "Type no longer implements interface"
```

### gRPC/Protobuf Breaking Changes

```yaml
grpc_breaking_changes:
  removed:
    - field: "UserMessage.email"
      field_number: 3
      severity: BREAKING
      reason: "Field removed from message"

    - service: "UserService"
      severity: BREAKING
      reason: "Service removed"

    - rpc: "UserService.GetUser"
      severity: BREAKING
      reason: "RPC method removed"

  modified:
    - field: "UserMessage.age"
      from_type: "int32"
      to_type: "string"
      severity: BREAKING
      reason: "Field type changed"

    - field: "UserMessage.name"
      from_label: "optional"
      to_label: "required"
      severity: BREAKING
      reason: "Field made required"

    - field_number: 5
      from_reserved: false
      to_reserved: true
      severity: BREAKING
      reason: "Field number reserved (deletion)"

  renamed:
    - message: "User"
      to: "UserAccount"
      severity: BREAKING
      reason: "Message type renamed"

    - enum: "Status"
      to: "OrderStatus"
      severity: BREAKING
      reason: "Enum renamed"
```

## API Contract Tools Integration

### OpenAPI/REST

```yaml
openapi_tools:
  primary: openapi-diff
  alternatives:
    - oasdiff
    - swagger-diff
    - api-diff

  usage:
    install: "npm install -g openapi-diff"
    compare: |
      openapi-diff \
        .aiwg/api/baselines/openapi-v1.yaml \
        .aiwg/api/current/openapi.yaml \
        --format markdown \
        --breaking-only
    output: ".aiwg/api/compatibility/openapi-diff.md"

  configuration:
    strict_mode: true
    ignore_descriptions: true
    treat_as_breaking:
      - removed_endpoints
      - removed_fields
      - type_changes
      - required_field_additions
      - enum_value_removals
```

### GraphQL

```yaml
graphql_tools:
  primary: graphql-inspector
  alternatives:
    - apollo-cli (schema:check)
    - graphql-schema-diff

  usage:
    install: "npm install -g @graphql-inspector/cli"
    compare: |
      graphql-inspector diff \
        .aiwg/api/baselines/schema-v1.graphql \
        .aiwg/api/current/schema.graphql \
        --onComplete report.json
    output: ".aiwg/api/compatibility/graphql-diff.json"

  configuration:
    fail_on_breaking: true
    include_dangerous: true
    schema_extensions: true
```

### gRPC/Protobuf

```yaml
protobuf_tools:
  primary: buf
  alternatives:
    - prototool
    - protoc-gen-validate

  usage:
    install: "brew install buf" # or "go install github.com/bufbuild/buf/cmd/buf@latest"
    setup: |
      # Create buf.yaml
      version: v1
      breaking:
        use:
          - FILE
      lint:
        use:
          - DEFAULT
    compare: |
      buf breaking \
        .aiwg/api/current \
        --against .aiwg/api/baselines/v1
    output: "Breaking change detection via buf CLI"

  configuration:
    breaking_rules:
      - FIELD_SAME_TYPE
      - FIELD_NO_DELETE
      - ENUM_VALUE_NO_DELETE
      - RPC_NO_DELETE
      - MESSAGE_NO_DELETE
```

## Semantic Versioning Compliance

```yaml
semver_validation:
  rules:
    breaking_change:
      requires: major_version_bump
      examples:
        - "v1.2.3 → v2.0.0"
      violations:
        - detected: breaking_change
          version_change: "v1.2.3 → v1.3.0"
          verdict: VIOLATION
          message: "Breaking change detected but only minor version bumped"

    non_breaking_addition:
      requires: minor_version_bump
      examples:
        - "v1.2.3 → v1.3.0"
      acceptable:
        - "v1.2.3 → v2.0.0"  # Major bump also acceptable

    bug_fix:
      requires: patch_version_bump
      examples:
        - "v1.