Breaking Change Detection

Utilities to detect and report breaking changes. (v1.11.0)

Overview

Breaking change detection utilities help you identify, analyze, and plan migrations for breaking changes between type versions.

Breaking Change Types

BreakingChangeReport

Report of breaking changes between types.

interface BreakingChangeReport<_T = unknown> {
  id: string
  sourceType: string
  targetType: string
  breakingChanges: BreakingChange[]
  nonBreakingChanges: Change[]
  timestamp: Date
  summary: BreakingChangeSummary
}

BreakingChange

A single breaking change.

interface BreakingChange {
  id: string
  type: BreakingChangeType
  severity: BreakingChangeSeverity
  path: string
  description: string
  oldValue?: unknown
  newValue?: unknown
  migrationPath?: string
  codeExample?: string
}

BreakingChangeType

Type of breaking change.

type BreakingChangeType =
  | 'removed'
  | 'renamed'
  | 'restructured'
  | 'behavior'
  | 'signature'
  | 'nullability'
  | 'optionality'
  | 'constraint'
  | 'generic'
  | 'inheritance'

BreakingChangeSeverity

Severity of breaking change.

type BreakingChangeSeverity = 'major' | 'minor' | 'patch'

BreakingChangeSummary

Summary of breaking changes.

interface BreakingChangeSummary {
  totalChanges: number
  majorChanges: number
  minorChanges: number
  patchChanges: number
  impactScore: number
  migrationEffort: MigrationEffort
}

MigrationEffort

Effort required for migration.

type MigrationEffort = 'trivial' | 'low' | 'medium' | 'high' | 'extreme'

API Diff

APIDiff

Difference between two API types.

type APIDiff<T, U> = {
  added: AddedAPI<U>
  removed: RemovedAPI<T>
  changed: ChangedAPI<T, U>
}

AddedAPI

Added API properties.

type AddedAPI<T> = {
  [K in keyof T]: {
    type: 'added'
    description?: string
  }
}

RemovedAPI

Removed API properties.

type RemovedAPI<T> = {
  [K in keyof T]: {
    type: 'removed'
    description?: string
    replacement?: string
  }
}

ChangedAPI

Changed API properties.

type ChangedAPI<T, U> = {
  [K in keyof T & keyof U]: {
    type: 'changed'
    from: T[K]
    to: U[K]
    breaking: boolean
    description?: string
  }
}

Compatibility Check

CompatibilityCheck

Check compatibility between types.

type CompatibilityCheck<T, U> = T extends U
  ? U extends T
    ? { compatible: true; level: 'full' }
    : { compatible: false; level: 'partial'; details: string }
  : { compatible: false; level: 'none'; details: string }

BreakingChangeCompatibilityReport

Detailed compatibility report.

interface BreakingChangeCompatibilityReport<_T = unknown> {
  source: string
  target: string
  level: CompatibilityLevel
  percentage: number
  issues: CompatibilityIssue[]
  warnings: string[]
  recommendations: string[]
}

CompatibilityLevel

Level of compatibility.

type CompatibilityLevel = 'full' | 'partial' | 'none'

CompatibilityIssue

A compatibility issue.

interface CompatibilityIssue {
  id: string
  type: CompatibilityIssueType
  path: string
  description: string
  suggestion?: string
  severity: 'error' | 'warning' | 'info'
}

CompatibilityIssueType

Type of compatibility issue.

type CompatibilityIssueType =
  | 'missing_property'
  | 'type_mismatch'
  | 'signature_change'
  | 'nullability_change'
  | 'optionality_change'
  | 'constraint_violation'
  | 'generic_incompatibility'
  | 'inheritance_change'
  | 'removed_api'
  | 'renamed_api'

Migration Path

BreakingChangeMigrationPath

Path to migrate through breaking changes.

type BreakingChangeMigrationPath<T, _U> = BreakingChangeMigrationStep<T>[]

BreakingChangeMigrationStep

A step in the migration path.

interface BreakingChangeMigrationStep<T> {
  step: number
  name: string
  description: string
  transform: (input: T) => unknown
  required: boolean
  breaking: boolean
  estimatedTime: number
  dependsOn?: number[]
  validate?: (input: T) => boolean
}

BreakingChangeMigrationComplexity

Complexity of migration.

type BreakingChangeMigrationComplexity = 'trivial' | 'moderate' | 'complex' | 'breaking'

MigrationPlan

Full migration plan.

interface MigrationPlan {
  id: string
  fromVersion: string
  toVersion: string
  steps: BreakingChangeMigrationStep<unknown>[]
  totalTime: number
  complexity: BreakingChangeMigrationComplexity
  requiredChanges: number
  optionalChanges: number
  breakingChanges: number
  prerequisites?: string[]
  postMigration?: string[]
}

Change Detection

ChangeDetectionOptions

Options for change detection.

interface ChangeDetectionOptions {
  deep: boolean
  includePrivate: boolean
  includeDeprecated: boolean
  ignore?: string[]
  equality?: (a: unknown, b: unknown) => boolean
}

Change

A detected change.

interface Change {
  id: string
  type: ChangeType
  path: string
  oldValue?: unknown
  newValue?: unknown
  isBreaking: boolean
  description: string
}

ChangeType

Type of change.

type ChangeType =
  | 'added'
  | 'removed'
  | 'modified'
  | 'renamed'
  | 'moved'
  | 'deprecated'
  | 'restored'

Impact Analysis

ImpactAnalysis

Analysis of change impact.

interface ImpactAnalysis {
  id: string
  changes: BreakingChange[]
  scope: ImpactScope
  affectedComponents: AffectedComponent[]
  riskLevel: RiskLevel
  recommendations: ImpactRecommendation[]
  mitigations: MitigationStrategy[]
}

ImpactScope

Scope of impact.

type ImpactScope = 'type' | 'module' | 'package' | 'project' | 'ecosystem'

AffectedComponent

An affected component.

interface AffectedComponent {
  name: string
  type: 'function' | 'class' | 'interface' | 'type' | 'module' | 'package'
  usageCount: number
  severity: 'low' | 'medium' | 'high' | 'critical'
  requiredChanges: string[]
}

RiskLevel

Risk level of changes.

type RiskLevel = 'none' | 'low' | 'medium' | 'high' | 'critical'

MitigationStrategy

Strategy to mitigate impact.

interface MitigationStrategy {
  name: string
  description: string
  steps: string[]
  appliesTo: string[]
  effectiveness: number
}

Prevention

BreakingChangeRule

Rule for detecting breaking changes.

interface BreakingChangeRule {
  id: string
  name: string
  description: string
  check: (change: Change) => boolean
  severity: BreakingChangeSeverity
  autoFix: boolean
}

BreakingChangeGuard

Guard to prevent breaking changes.

interface BreakingChangeGuard {
  name: string
  rules: BreakingChangeRule[]
  exceptions?: string[]
  customChecks?: ((change: Change) => boolean)[]
}

Related Types

• Migration Utilities - Type migration tools
• Deprecation Management - Deprecation warnings
• Enhanced Error Messages - Better error messages