0
# Assembly Comparison
1

2
Core API for comparing two jsii assemblies to detect breaking changes and compatibility violations between library versions. This provides the foundational functionality for validating API evolution and ensuring backward compatibility.
3

4
## Capabilities
5

6
### Compare Assemblies Function
7

8
The primary function for comparing two jsii assemblies for API compatibility.
9

10
```typescript { .api }
11
/**
12
 * Compare two assemblies for compatibility
13
 * 
14
 * Checks whether code written against the original assembly will still
15
 * typecheck when compiled against the updated assembly. Validates that:
16
 * - All types in original still exist in updated
17
 * - Enums have only added members  
18
 * - Classes/interfaces have only added members or allowed modifications
19
 * - Property types are same or strengthened
20
 * - Method arguments only added optional, existing weakened, return strengthened
21
 * 
22
 * @param original - The original assembly to compare from
23
 * @param updated - The updated assembly to compare to  
24
 * @param options - Configuration options for comparison
25
 * @returns Mismatches object containing any compatibility violations
26
 */
27
function compareAssemblies(
28
  original: reflect.Assembly,
29
  updated: reflect.Assembly,
30
  options?: ComparisonOptions
31
): Mismatches;
32
```
33

34
**Usage Examples:**
35

36
```typescript
37
import { compareAssemblies } from "jsii-diff";
38
import * as reflect from "jsii-reflect";
39

40
// Compare two local assemblies
41
const ts1 = new reflect.TypeSystem();
42
const original = ts1.loadModule("./packages/my-lib");
43

44
const ts2 = new reflect.TypeSystem();
45
const updated = ts2.loadModule("./packages/my-lib-v2");
46

47
const mismatches = compareAssemblies(original, updated);
48

49
// Check for any compatibility issues
50
if (mismatches.count > 0) {
51
  console.log(`Found ${mismatches.count} compatibility issues:`);
52
  for (const message of mismatches.messages()) {
53
    console.log(`- ${message}`);
54
  }
55
}
56

57
// Compare with custom options
58
const mismatchesExperimental = compareAssemblies(original, updated, {
59
  defaultExperimental: true // treat unmarked APIs as experimental
60
});
61
```
62

63
### Comparison Options
64

65
Configuration interface for customizing assembly comparison behavior.
66

67
```typescript { .api }
68
/**
69
 * Configuration options for assembly comparison
70
 */
71
interface ComparisonOptions {
72
  /** 
73
   * Whether to treat API elements as experimental if unmarked
74
   * When true, unmarked APIs are treated as experimental (more lenient rules)
75
   * When false, unmarked APIs are treated as stable (stricter rules)
76
   * @default false (treat as stable)
77
   */
78
  defaultExperimental?: boolean;
79
}
80
```
81

82
### Mismatches Collection
83

84
Container for collecting and managing API compatibility violations during comparison.
85

86
```typescript { .api }
87
/**
88
 * Collection of API compatibility mismatches with reporting capabilities
89
 */
90
class Mismatches implements IReport {
91
  /** Array of all collected compatibility violations */
92
  readonly mismatches: Array<ApiMismatch>;
93
  
94
  /**
95
   * Create a new mismatches collection
96
   * @param opts - Configuration including default stability level
97
   */
98
  constructor(opts: { defaultStability: Stability });
99
  
100
  /**
101
   * Report a new API compatibility violation
102
   * @param options - Details of the violation to report
103
   */
104
  report(options: ReportOptions): void;
105
  
106
  /**
107
   * Iterate over all mismatch messages
108
   * @returns Iterator of human-readable violation messages
109
   */
110
  messages(): IterableIterator<string>;
111
  
112
  /** Total number of compatibility violations found */
113
  readonly count: number;
114
  
115
  /**
116
   * Create filtered copy of mismatches based on predicate
117
   * @param pred - Function to test each mismatch
118
   * @returns New Mismatches instance with filtered results
119
   */
120
  filter(pred: (x: ApiMismatch) => boolean): Mismatches;
121
  
122
  /**
123
   * Create reporter with additional context for all future reports
124
   * @param motivation - Context string to append to violation messages
125
   * @returns New reporter with motivation context
126
   */
127
  withMotivation(motivation: string): IReport;
128
}
129
```
130

131
### API Mismatch
132

133
Individual API compatibility violation with metadata.
134

135
```typescript { .api }
136
/**
137
 * Represents a single API compatibility violation
138
 */
139
interface ApiMismatch {
140
  /** Human-readable description of the compatibility violation */
141
  message: string;
142
  /** Unique identifier for this violation type and element */
143
  violationKey: string;
144
  /** Stability level of the API element that has the violation */
145
  stability: Stability;
146
}
147
```
148

149
### Report Options
150

151
Configuration for reporting API violations.
152

153
```typescript { .api }
154
/**
155
 * Options for reporting an API compatibility violation
156
 */
157
interface ReportOptions {
158
  /** Identifier for the type of rule that was violated */
159
  ruleKey: string;
160
  /** The specific API element that violates compatibility */
161
  violator: ApiElement;
162
  /** Description of how the element violates compatibility */
163
  message: string;
164
}
165
```
166

167
### Report Interface
168

169
Interface for components that can receive API violation reports.
170

171
```typescript { .api }
172
/**
173
 * Interface for reporting API compatibility violations
174
 */
175
interface IReport {
176
  /**
177
   * Report an API compatibility violation
178
   * @param options - Details of the violation
179
   */
180
  report(options: ReportOptions): void;
181
  
182
  /**
183
   * Create a reporter with additional context
184
   * @param reason - Context to add to future reports
185
   * @returns New reporter with added context
186
   */
187
  withMotivation(reason: string): IReport;
188
}
189
```
190

191
## Compatibility Rules
192

193
jsii-diff implements sophisticated compatibility rules based on the principle that APIs can:
194
- **Weaken inputs** (require less from callers)  
195
- **Strengthen outputs** (guarantee more to callers)
196

197
### Type Evolution Rules
198

199
- **Enums**: May only add new members, never remove or modify existing ones
200
- **Classes/Interfaces**: May add members, modify existing members only in allowed ways
201
- **Properties**: Types may be strengthened (more restrictive)
202
- **Methods**: May add optional parameters, weaken existing parameter types, strengthen return types
203

204
### Stability-Based Rules
205

206
Different rules apply based on API stability:
207
- **Stable**: Strict compatibility rules, breaking changes cause errors
208
- **Experimental**: More lenient rules, breaking changes cause warnings  
209
- **Deprecated**: May be modified before removal
210
- **External**: Compatibility depends on external library evolution
211

212
### Struct vs Reference Types
213

214
- **Structs** (data interfaces): Evaluated based on usage position (input/output)
215
- **Reference Types** (classes/behavioral interfaces): May only add members by default
216
- **@subclassable Types**: Must follow weakening rules to avoid breaking implementors