0
# Diagnostics and Error Handling
1

2
Classification and formatting system for API compatibility violations with configurable error levels, filtering capabilities, and stability-aware diagnostic categorization.
3

4
## Capabilities
5

6
### Diagnostic Classification
7

8
Classify API mismatches into errors, warnings, or skipped diagnostics based on stability levels and configuration.
9

10
```typescript { .api }
11
/**
12
 * Classify API mismatches into a set of warnings and errors
13
 * @param mismatches - Collection of API compatibility violations
14
 * @param shouldError - Set of stability levels that should be treated as errors
15
 * @param skipFilter - Optional set of violation keys to skip
16
 * @returns Array of classified diagnostics sorted by severity
17
 */
18
function classifyDiagnostics(
19
  mismatches: Mismatches,
20
  shouldError: Set<Stability>,
21
  skipFilter?: Set<string>
22
): Diagnostic[];
23
```
24

25
**Usage Examples:**
26

27
```typescript
28
import { 
29
  classifyDiagnostics, 
30
  treatAsError, 
31
  hasErrors,
32
  formatDiagnostic 
33
} from "jsii-diff/lib/diagnostics";
34
import { Stability } from "@jsii/spec";
35

36
// Classify with production error settings (stable + deprecated)
37
const diags = classifyDiagnostics(
38
  mismatches, 
39
  treatAsError('prod')
40
);
41

42
// Check if any errors were found
43
if (hasErrors(diags)) {
44
  console.error("Breaking changes detected!");
45
  for (const diag of diags) {
46
    console.error(formatDiagnostic(diag, true)); // include suppression keys
47
  }
48
}
49

50
// Classify with custom error settings and filtering
51
const filteredDiags = classifyDiagnostics(
52
  mismatches,
53
  treatAsError('all'), // treat all stability levels as errors
54
  new Set(['method-removed:MyClass.oldMethod']) // skip specific violations
55
);
56
```
57

58
### Error Level Configuration
59

60
Convert error class names to sets of stability levels that should be treated as errors.
61

62
```typescript { .api }
63
/**
64
 * Convert error class to set of stabilities that should be treated as errors
65
 * @param errorClass - Predefined error classification level
66
 * @param deprecatedExperimentalErrors - Legacy flag for experimental errors
67
 * @returns Set of stability levels to treat as errors
68
 */
69
function treatAsError(
70
  errorClass: ErrorClass,
71
  deprecatedExperimentalErrors?: boolean
72
): Set<Stability>;
73
```
74

75
### Diagnostic Formatting
76

77
Format diagnostic messages for display with optional suppression keys.
78

79
```typescript { .api }
80
/**
81
 * Format a diagnostic for human-readable display
82
 * @param diag - The diagnostic to format
83
 * @param includeSuppressionKey - Whether to include suppression key in output
84
 * @returns Formatted diagnostic string
85
 */
86
function formatDiagnostic(
87
  diag: Diagnostic,
88
  includeSuppressionKey?: boolean
89
): string;
90
```
91

92
### Diagnostic Filtering
93

94
Utility functions for filtering diagnostics by severity level.
95

96
```typescript { .api }
97
/**
98
 * Check if any diagnostics are at error level
99
 * @param diags - Array of diagnostics to check
100
 * @returns True if any diagnostic is an error
101
 */
102
function hasErrors(diags: Diagnostic[]): boolean;
103

104
/**
105
 * Filter diagnostics to only error-level entries
106
 * @param diags - Array of diagnostics to filter
107
 * @returns Array containing only error diagnostics
108
 */
109
function onlyErrors(diags: Diagnostic[]): Diagnostic[];
110

111
/**
112
 * Filter diagnostics to only warning-level entries  
113
 * @param diags - Array of diagnostics to filter
114
 * @returns Array containing only warning diagnostics
115
 */
116
function onlyWarnings(diags: Diagnostic[]): Diagnostic[];
117
```
118

119
## Types
120

121
### Diagnostic
122

123
Represents a classified diagnostic message with severity level.
124

125
```typescript { .api }
126
/**
127
 * A classified diagnostic message with severity and suppression information
128
 */
129
interface Diagnostic {
130
  /** Severity level of the diagnostic */
131
  level: DiagLevel;
132
  /** Human-readable diagnostic message */
133
  message: string;
134
  /** Key that can be used to suppress this diagnostic */
135
  suppressionKey: string;
136
}
137
```
138

139
### Diagnostic Level
140

141
Enumeration of diagnostic severity levels.
142

143
```typescript { .api }
144
/**
145
 * Diagnostic severity levels
146
 */
147
enum DiagLevel {
148
  /** Error level - indicates breaking change that should fail builds */
149
  Error = 0,
150
  /** Warning level - indicates potential issue but not breaking */
151
  Warning = 1,
152
  /** Skipped level - diagnostic was suppressed via filter */
153
  Skipped = 2
154
}
155
```
156

157
### Error Class
158

159
Predefined error classification levels for different use cases.
160

161
```typescript { .api }
162
/**
163
 * Predefined error classification levels
164
 */
165
type ErrorClass = 'prod' | 'non-experimental' | 'all';
166
```
167

168
### Error Class Mapping
169

170
Mapping between error classes and the stability levels they include.
171

172
```typescript { .api }
173
/**
174
 * Available error class options
175
 */
176
const ERROR_CLASSES: readonly ['prod', 'non-experimental', 'all'];
177

178
/**
179
 * Mapping of error classes to stability arrays
180
 */
181
const ERROR_CLASSES_TO_STABILITIES: Record<ErrorClass, Stability[]> = {
182
  /** Production-ready APIs only: stable and deprecated */
183
  prod: [Stability.Stable, Stability.Deprecated],
184
  /** All non-experimental APIs: stable, deprecated, and external */
185
  'non-experimental': [
186
    Stability.Stable,
187
    Stability.Deprecated,
188
    Stability.External
189
  ],
190
  /** All stability levels: stable, experimental, external, deprecated */
191
  all: [
192
    Stability.Stable,
193
    Stability.Experimental,
194
    Stability.External,
195
    Stability.Deprecated
196
  ]
197
};
198
```
199

200
## Error Classification Levels
201

202
### Production (`prod`)
203
- **Stabilities**: Stable, Deprecated
204
- **Use Case**: Default for production builds - only stable and deprecated API changes cause errors
205
- **Behavior**: Experimental and external API changes generate warnings
206

207
### Non-Experimental (`non-experimental`) 
208
- **Stabilities**: Stable, Deprecated, External
209
- **Use Case**: Stricter validation that includes external dependencies
210
- **Behavior**: Only experimental API changes generate warnings
211

212
### All (`all`)
213
- **Stabilities**: Stable, Experimental, External, Deprecated  
214
- **Use Case**: Maximum validation - all API changes cause errors
215
- **Behavior**: No warnings, all compatibility violations are errors
216

217
## Diagnostic Suppression
218

219
Diagnostics can be suppressed using violation keys:
220

221
1. **Generate Keys**: Run with `--keys` flag to see suppression keys
222
2. **Create Filter File**: List violation keys in a text file (one per line)  
223
3. **Apply Filter**: Use `--ignore-file` option or `skipFilter` parameter
224
4. **Key Format**: `{ruleKey}:{apiElementIdentifier}`
225

226
**Example suppression file:**
227
```
228
# Suppress specific method removal
229
method-removed:MyClass.deprecatedMethod
230

231
# Suppress property type changes  
232
property-type-changed:MyInterface.configValue
233
```