0
# jsii-diff
1

2
jsii-diff is a TypeScript library that provides comprehensive API compatibility checking for jsii (JavaScript interop) assemblies. It enables developers to validate that changes between library versions don't break backward compatibility by analyzing type systems, method signatures, and API stability levels with sophisticated breaking change detection.
3

4
## Package Information
5

6
- **Package Name**: jsii-diff
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install jsii-diff`
10

11
## Core Imports
12

13
```typescript
14
import { compareAssemblies } from "jsii-diff";
15
import { 
16
  classifyDiagnostics, 
17
  treatAsError, 
18
  formatDiagnostic,
19
  hasErrors 
20
} from "jsii-diff/lib/diagnostics";
21
import { 
22
  downloadNpmPackage,
23
  showDownloadFailure,
24
  inTempDir,
25
  flatMap,
26
  RecursionBreaker
27
} from "jsii-diff/lib/util";
28
import { validateStabilities } from "jsii-diff/lib/stability";
29
```
30

31
For CommonJS:
32

33
```javascript
34
const { compareAssemblies } = require("jsii-diff");
35
const { 
36
  classifyDiagnostics, 
37
  treatAsError, 
38
  formatDiagnostic,
39
  hasErrors 
40
} = require("jsii-diff/lib/diagnostics");
41
const { 
42
  downloadNpmPackage,
43
  showDownloadFailure,
44
  inTempDir,
45
  flatMap,
46
  RecursionBreaker
47
} = require("jsii-diff/lib/util");
48
const { validateStabilities } = require("jsii-diff/lib/stability");
49
```
50

51
## Basic Usage
52

53
```typescript
54
import { compareAssemblies } from "jsii-diff";
55
import { 
56
  classifyDiagnostics, 
57
  treatAsError, 
58
  formatDiagnostic,
59
  hasErrors 
60
} from "jsii-diff/lib/diagnostics";
61
import * as reflect from "jsii-reflect";
62

63
// Load two jsii assemblies
64
const ts1 = new reflect.TypeSystem();
65
const original = ts1.loadModule("./v1.0.0");
66

67
const ts2 = new reflect.TypeSystem(); 
68
const updated = ts2.loadModule("./v2.0.0");
69

70
// Compare for compatibility
71
const mismatches = compareAssemblies(original, updated, {
72
  defaultExperimental: false // treat unmarked APIs as stable
73
});
74

75
// Classify diagnostics (errors vs warnings)
76
const diagnostics = classifyDiagnostics(
77
  mismatches,
78
  treatAsError('prod') // stable and deprecated APIs cause errors
79
);
80

81
// Check results
82
if (hasErrors(diagnostics)) {
83
  console.error("Breaking changes detected!");
84
  for (const diag of diagnostics) {
85
    console.error(formatDiagnostic(diag));
86
  }
87
  process.exit(1);
88
}
89
```
90

91
## Architecture
92

93
jsii-diff is built around several key components:
94

95
- **Assembly Comparison Engine**: Core logic for comparing two jsii assemblies using type-safe reflection
96
- **Compatibility Rules**: Sophisticated rules for what changes are allowed (strengthening outputs, weakening inputs)
97
- **Stability System**: Different compatibility rules based on API stability levels (stable, experimental, deprecated, external)
98
- **Diagnostic Classification**: Categorizes violations as errors or warnings based on stability and configuration
99
- **CLI Interface**: Full-featured command-line tool for CI/CD integration
100

101
## Capabilities
102

103
### Assembly Comparison
104

105
Core API for comparing two jsii assemblies to detect breaking changes and compatibility violations between library versions.
106

107
```typescript { .api }
108
function compareAssemblies(
109
  original: reflect.Assembly,
110
  updated: reflect.Assembly,
111
  options?: ComparisonOptions
112
): Mismatches;
113

114
interface ComparisonOptions {
115
  /** Whether to treat API elements as experimental if unmarked (default: false/stable) */
116
  defaultExperimental?: boolean;
117
}
118
```
119

120
[Assembly Comparison](./assembly-comparison.md)
121

122
### Diagnostics and Error Handling
123

124
Classification and formatting system for API compatibility violations with configurable error levels and filtering capabilities.
125

126
```typescript { .api }
127
function classifyDiagnostics(
128
  mismatches: Mismatches,
129
  shouldError: Set<Stability>,
130
  skipFilter?: Set<string>
131
): Diagnostic[];
132

133
interface Diagnostic {
134
  level: DiagLevel;
135
  message: string;
136
  suppressionKey: string;
137
}
138

139
enum DiagLevel {
140
  Error = 0,
141
  Warning = 1,
142
  Skipped = 2
143
}
144
```
145

146
[Diagnostics and Error Handling](./diagnostics.md)
147

148
### Command Line Interface
149

150
Full-featured CLI tool for comparing jsii assemblies with support for local files, directories, and NPM packages.
151

152
```bash
153
jsii-diff <original> [updated] [options]
154
```
155

156
Key options:
157
- `--error-on <prod|non-experimental|all>`: Control which stability levels cause errors
158
- `--ignore-file <path>`: File containing violation keys to suppress
159
- `--default-stability <experimental|stable>`: How to treat unmarked APIs
160

161
[Command Line Interface](./cli.md)
162

163
### Utility Functions
164

165
Utility functions for NPM package handling, temporary directory management, and common operations.
166

167
```typescript { .api }
168
function downloadNpmPackage<T>(
169
  pkg: string,
170
  block: (dir: string) => Promise<T>
171
): Promise<NpmDownloadResult<T>>;
172

173
function showDownloadFailure(f: DownloadFailure): string | undefined;
174

175
function inTempDir<T>(block: () => T | Promise<T>): Promise<T>;
176

177
function flatMap<T, U>(xs: T[], fn: (x: T) => U[]): U[];
178

179
class RecursionBreaker<A> {
180
  do(key: A, block: () => void): void;
181
}
182
```
183

184
[Utility Functions](./utilities.md)
185

186
### Stability Validation
187

188
Validation functions for API stability level transitions and consistency checks.
189

190
```typescript { .api }
191
function validateStabilities(
192
  original: reflect.Documentable & ApiElement,
193
  updated: reflect.Documentable,
194
  mismatches: IReport
195
): void;
196
```
197

198
[Stability Validation](./stability.md)
199

200
## Types
201

202
### Core Types
203

204
```typescript { .api }
205
interface ApiMismatch {
206
  message: string;
207
  violationKey: string;
208
  stability: Stability;
209
}
210

211
class Mismatches {
212
  readonly mismatches: Array<ApiMismatch>;
213
  constructor(opts: { defaultStability: Stability });
214
  report(options: ReportOptions): void;
215
  messages(): IterableIterator<string>;
216
  readonly count: number;
217
  filter(pred: (x: ApiMismatch) => boolean): Mismatches;
218
  withMotivation(motivation: string): IReport;
219
}
220

221
interface ReportOptions {
222
  ruleKey: string;
223
  violator: ApiElement;
224
  message: string;
225
}
226
```
227

228
### Stability and Error Classification
229

230
```typescript { .api }
231
type ErrorClass = 'prod' | 'non-experimental' | 'all';
232

233
interface ComparisonContext extends ComparisonOptions {
234
  mismatches: Mismatches;
235
}
236

237
// ApiElement uses types from jsii-reflect package
238
type ApiElement = reflect.Type | reflect.TypeMember | reflect.EnumMember;
239

240
interface IReport {
241
  report(options: ReportOptions): void;
242
  withMotivation(reason: string): IReport;
243
}
244
```
245

246
### Utility Types
247

248
```typescript { .api }
249
type DownloadFailure = 'no_such_package';
250

251
type NpmDownloadResult<T> =
252
  | { success: true; result: T }
253
  | { success: false; reason: DownloadFailure };
254

255
interface LoadOptions {
256
  validate: boolean;
257
}
258
```