0
# Stability Validation
1

2
Validation functions for API stability level transitions and consistency checks. This module ensures that stability annotations evolve according to allowed transition rules, preventing invalid stability changes that could confuse consumers.
3

4
## Capabilities
5

6
### Stability Transition Validation
7

8
Validates that API stability level changes follow allowed transition paths.
9

10
```typescript { .api }
11
/**
12
 * Validate that stability level changes between API versions follow allowed rules
13
 * @param original - Original API element with stability annotation
14
 * @param updated - Updated API element with (potentially different) stability
15
 * @param mismatches - Reporter for recording any validation violations
16
 */
17
function validateStabilities(
18
  original: reflect.Documentable & ApiElement,
19
  updated: reflect.Documentable,
20
  mismatches: IReport
21
): void;
22
```
23

24
**Usage Examples:**
25

26
```typescript
27
import { validateStabilities } from "jsii-diff/lib/stability";
28
import { Mismatches } from "jsii-diff/lib/types";
29
import { Stability } from "@jsii/spec";
30

31
// Create a mismatches reporter
32
const mismatches = new Mismatches({ 
33
  defaultStability: Stability.Stable 
34
});
35

36
// Validate stability transition for a method
37
validateStabilities(originalMethod, updatedMethod, mismatches);
38

39
// Check for any reported violations
40
if (mismatches.count > 0) {
41
  for (const message of mismatches.messages()) {
42
    console.log(`Stability violation: ${message}`);
43
  }
44
}
45
```
46

47
## Stability Transition Rules
48

49
The validation enforces the following allowed transitions between stability levels:
50

51
### From Experimental
52
- **→ Stable**: API has matured and is ready for production use
53
- **→ Deprecated**: API is being phased out without going through stable
54
- **→ External**: API depends on external library evolution
55

56
### From Stable  
57
- **→ Deprecated**: API is being phased out in favor of alternatives
58
- **→ External**: API now depends on external library evolution
59

60
### From Deprecated
61
- **→ Stable**: API deprecation was reversed, reinstated as stable
62
- **→ External**: Deprecated API now depends on external library
63

64
### From External
65
- **→ Stable**: External dependency is now managed internally
66
- **→ Deprecated**: External API is being phased out
67

68
## Validation Errors
69

70
The function reports two types of stability violations:
71

72
### Removed Stability (`removed-stability`)
73
- **Trigger**: API had stability annotation in original but none in updated
74
- **Message**: `"stability was '{original}', has been removed"`
75
- **Impact**: Consumers lose important compatibility information
76

77
### Changed Stability (`changed-stability`)
78
- **Trigger**: Stability changed to a disallowed target level
79
- **Message**: `"stability not allowed to go from '{original}' to '{updated}'"`
80
- **Impact**: Indicates invalid API lifecycle management
81

82
## Integration with Comparison System
83

84
Stability validation is automatically performed during assembly comparison and integrated with the diagnostic classification system:
85

86
```typescript
87
import { compareAssemblies } from "jsii-diff";
88
import { classifyDiagnostics, treatAsError } from "jsii-diff/lib/diagnostics";
89

90
// Stability violations are included in compatibility analysis
91
const mismatches = compareAssemblies(original, updated);
92

93
// Stability violations can be classified as errors or warnings
94
const diagnostics = classifyDiagnostics(
95
  mismatches,
96
  treatAsError('prod') // stability violations on prod APIs cause errors
97
);
98
```
99

100
## Best Practices
101

102
### API Lifecycle Management
103

104
1. **Start Experimental**: New APIs should begin as experimental
105
2. **Graduate to Stable**: Promote to stable after proven in practice
106
3. **Deprecate Gracefully**: Mark as deprecated before removal
107
4. **Document External Dependencies**: Use external for third-party dependent APIs
108

109
### Stability Annotation Consistency
110

111
```typescript
112
// Good: Clear progression
113
@experimental → @stable → @deprecated
114

115
// Bad: Invalid transitions
116
@stable → @experimental  // Not allowed
117
@deprecated → @experimental  // Not allowed
118
```
119

120
### Error Handling Strategy
121

122
- **Production Systems**: Treat stability violations as errors
123
- **Development**: May treat as warnings during API design phase
124
- **Documentation**: Always document stability level changes in release notes
125

126
## Implementation Details
127

128
### Validation Logic
129

130
- Checks if original element has stability annotation
131
- Compares with updated element's stability
132
- Ignores cases where both have same stability or original has none
133
- Reports violations through the standard mismatches reporting system
134

135
### Integration Points
136

137
- Called automatically during `compareAssemblies` operation
138
- Results flow through diagnostic classification system
139
- Violation keys follow pattern: `{rule}:{apiElementIdentifier}`
140
- Can be suppressed using standard ignore file mechanisms