Breaking Change Detector
breaking-change-detector
Detect breaking changes across 6 categories: contracts, database schemas, RPC endpoints, WebSocket protocols, serialized state, and event sourcing.
SKILL.md
Full skill instructions
Breaking Change Detector
Detects breaking changes that could disrupt active sessions or lose client compatibility across 6 categories.
When to use: Modifying shared contract/interface packages, changing database schema or migrations, RPC/API endpoint signature changes, WebSocket message format changes, serialized state schema changes, before merging any contract/schema changes.
When not to use: Adding new optional fields (non-breaking), internal refactoring without API changes, documentation or test-only changes.
Rationalizations (Do Not Skip)
| Rationalization | Why It's Wrong | Required Action |
|---|---|---|
| "Nobody uses the old format" | Active sessions and stored data use the old format right now | Check backward compatibility |
| "We'll fix the clients" | Clients update on their own schedule, not yours | Keep old format supported |
| "It's just a rename" | A rename IS a removal + addition -- all consumers need updating | Deprecate, don't rename |
| "The migration handles it" | Migrations run once; replay/recovery may encounter old data indefinitely | Use tolerant reader pattern |
Included Utilities
// Breaking change classification (zero dependencies)
import { classifyFieldChange, classifySerializedSchema, classifyEventTypeChanges } from './breaking-change.ts';
Backward Compatibility Checklist
When modifying contracts or schemas:
- All existing fields preserved (or deprecated with fallback)
- New fields are optional or have
.catch()defaults - Type changes are widening only
- Database migration handles existing data
- Old event formats still supported for replay
- WebSocket protocol versioned
- API endpoints maintain compatibility
- Tests validate old data still deserializes correctly
- Serialized state schemas use
.catch()for all fields -
fromJSON()methods usesafeParse()with graceful fallback
Violation Rules
| Slug | Rule | Severity |
|---|---|---|
contract_field_removal | Removed/renamed fields in shared interfaces | must-fail |
schema_without_catch | Serialized schema fields missing .catch() default | must-fail |
strict_parse_in_deserialize | Using .parse() instead of .safeParse() in fromJSON | must-fail |
migration_drops_column | Column removal without data migration | must-fail |
endpoint_removed | API endpoint removed without deprecation period | must-fail |
event_type_renamed | Event type name changed (incompatible with replay) | must-fail |
Coverage
| Category | Utility | Status |
|---|---|---|
| 1. Contract fields | classifyFieldChange() | Code + tests |
| 2. Database schema | -- | Doc-only (requires SQL diffing) |
| 3. RPC/API endpoints | -- | Doc-only (requires OpenAPI diffing) |
| 4. WebSocket protocol | -- | Doc-only (requires message schema diffing) |
| 5. Serialized state | classifySerializedSchema() | Code + tests |
| 6. Event sourcing | classifyEventTypeChanges() | Code + tests |
Categories 2-4 require static analysis of SQL migrations, OpenAPI specs, or protocol schemas -- tools beyond the scope of a pure-function utility. See categories.md for detection commands and safe patterns.
Output Format
## CRITICAL -- Will Disrupt Active Sessions
### Contract: Removed UserState.score field
**File**: src/contracts/types.ts:42
**Impact**: Active sessions fail on state load
**Fix**: Deprecate instead:
/** @deprecated Use points instead */
score?: number;
points: number;
## WARNING -- Migration Required
### Database: Renamed column without migration
**File**: migrations/0036_rename_field.sql:5
**Impact**: Existing rows have NULL values
**Fix**: Add data migration step
## SAFE Changes
- Added optional field `UserState.metadata`
- New API endpoint `orders.archive`
- Widened type `Status: 'active' | 'paused'` to include `'archived'`
Framework Adaptation
This skill applies to any system with shared contracts/interfaces, persistent state, event sourcing, real-time protocols, or RPC/API layers with independent client release cycles.
See categories.md for detailed detection patterns, code examples, and safe alternatives for each of the 6 categories.