Stability Validation

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.

Capabilities

Stability Transition Validation

Validates that API stability level changes follow allowed transition paths.

/**
 * Validate that stability level changes between API versions follow allowed rules
 * @param original - Original API element with stability annotation
 * @param updated - Updated API element with (potentially different) stability
 * @param mismatches - Reporter for recording any validation violations
 */
function validateStabilities(
  original: reflect.Documentable & ApiElement,
  updated: reflect.Documentable,
  mismatches: IReport
): void;

Usage Examples:

import { validateStabilities } from "jsii-diff/lib/stability";
import { Mismatches } from "jsii-diff/lib/types";
import { Stability } from "@jsii/spec";

// Create a mismatches reporter
const mismatches = new Mismatches({ 
  defaultStability: Stability.Stable 
});

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

// Check for any reported violations
if (mismatches.count > 0) {
  for (const message of mismatches.messages()) {
    console.log(`Stability violation: ${message}`);
  }
}

Stability Transition Rules

The validation enforces the following allowed transitions between stability levels:

From Experimental

• → Stable: API has matured and is ready for production use
• → Deprecated: API is being phased out without going through stable
• → External: API depends on external library evolution

From Stable

• → Deprecated: API is being phased out in favor of alternatives
• → External: API now depends on external library evolution

From Deprecated

• → Stable: API deprecation was reversed, reinstated as stable
• → External: Deprecated API now depends on external library

From External

• → Stable: External dependency is now managed internally
• → Deprecated: External API is being phased out

Validation Errors

The function reports two types of stability violations:

Removed Stability (removed-stability)

• Trigger: API had stability annotation in original but none in updated
• Message: "stability was '{original}', has been removed"
• Impact: Consumers lose important compatibility information

Changed Stability (changed-stability)

• Trigger: Stability changed to a disallowed target level
• Message: "stability not allowed to go from '{original}' to '{updated}'"
• Impact: Indicates invalid API lifecycle management

Integration with Comparison System

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

import { compareAssemblies } from "jsii-diff";
import { classifyDiagnostics, treatAsError } from "jsii-diff/lib/diagnostics";

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

// Stability violations can be classified as errors or warnings
const diagnostics = classifyDiagnostics(
  mismatches,
  treatAsError('prod') // stability violations on prod APIs cause errors
);

Best Practices

API Lifecycle Management

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

Stability Annotation Consistency

// Good: Clear progression
@experimental → @stable → @deprecated

// Bad: Invalid transitions
@stable → @experimental  // Not allowed
@deprecated → @experimental  // Not allowed

Error Handling Strategy

• Production Systems: Treat stability violations as errors
• Development: May treat as warnings during API design phase
• Documentation: Always document stability level changes in release notes

Implementation Details

Validation Logic

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

Integration Points

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