tessl/npm-jsii-diff

Assembly comparison for jsii that detects breaking changes and compatibility violations between library versions

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Diagnostics and Error Handling

Name: tessl/npm-jsii-diff
Author: tessl

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

Capabilities

Diagnostic Classification

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

/**
 * Classify API mismatches into a set of warnings and errors
 * @param mismatches - Collection of API compatibility violations
 * @param shouldError - Set of stability levels that should be treated as errors
 * @param skipFilter - Optional set of violation keys to skip
 * @returns Array of classified diagnostics sorted by severity
 */
function classifyDiagnostics(
  mismatches: Mismatches,
  shouldError: Set<Stability>,
  skipFilter?: Set<string>
): Diagnostic[];

Usage Examples:

import { 
  classifyDiagnostics, 
  treatAsError, 
  hasErrors,
  formatDiagnostic 
} from "jsii-diff/lib/diagnostics";
import { Stability } from "@jsii/spec";

// Classify with production error settings (stable + deprecated)
const diags = classifyDiagnostics(
  mismatches, 
  treatAsError('prod')
);

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

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

Error Level Configuration

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

/**
 * Convert error class to set of stabilities that should be treated as errors
 * @param errorClass - Predefined error classification level
 * @param deprecatedExperimentalErrors - Legacy flag for experimental errors
 * @returns Set of stability levels to treat as errors
 */
function treatAsError(
  errorClass: ErrorClass,
  deprecatedExperimentalErrors?: boolean
): Set<Stability>;

Diagnostic Formatting

Format diagnostic messages for display with optional suppression keys.

/**
 * Format a diagnostic for human-readable display
 * @param diag - The diagnostic to format
 * @param includeSuppressionKey - Whether to include suppression key in output
 * @returns Formatted diagnostic string
 */
function formatDiagnostic(
  diag: Diagnostic,
  includeSuppressionKey?: boolean
): string;

Diagnostic Filtering

Utility functions for filtering diagnostics by severity level.

/**
 * Check if any diagnostics are at error level
 * @param diags - Array of diagnostics to check
 * @returns True if any diagnostic is an error
 */
function hasErrors(diags: Diagnostic[]): boolean;

/**
 * Filter diagnostics to only error-level entries
 * @param diags - Array of diagnostics to filter
 * @returns Array containing only error diagnostics
 */
function onlyErrors(diags: Diagnostic[]): Diagnostic[];

/**
 * Filter diagnostics to only warning-level entries  
 * @param diags - Array of diagnostics to filter
 * @returns Array containing only warning diagnostics
 */
function onlyWarnings(diags: Diagnostic[]): Diagnostic[];

Types

Diagnostic

Represents a classified diagnostic message with severity level.

/**
 * A classified diagnostic message with severity and suppression information
 */
interface Diagnostic {
  /** Severity level of the diagnostic */
  level: DiagLevel;
  /** Human-readable diagnostic message */
  message: string;
  /** Key that can be used to suppress this diagnostic */
  suppressionKey: string;
}

Diagnostic Level

Enumeration of diagnostic severity levels.

/**
 * Diagnostic severity levels
 */
enum DiagLevel {
  /** Error level - indicates breaking change that should fail builds */
  Error = 0,
  /** Warning level - indicates potential issue but not breaking */
  Warning = 1,
  /** Skipped level - diagnostic was suppressed via filter */
  Skipped = 2
}

Error Class

Predefined error classification levels for different use cases.

/**
 * Predefined error classification levels
 */
type ErrorClass = 'prod' | 'non-experimental' | 'all';

Error Class Mapping

Mapping between error classes and the stability levels they include.

/**
 * Available error class options
 */
const ERROR_CLASSES: readonly ['prod', 'non-experimental', 'all'];

/**
 * Mapping of error classes to stability arrays
 */
const ERROR_CLASSES_TO_STABILITIES: Record<ErrorClass, Stability[]> = {
  /** Production-ready APIs only: stable and deprecated */
  prod: [Stability.Stable, Stability.Deprecated],
  /** All non-experimental APIs: stable, deprecated, and external */
  'non-experimental': [
    Stability.Stable,
    Stability.Deprecated,
    Stability.External
  ],
  /** All stability levels: stable, experimental, external, deprecated */
  all: [
    Stability.Stable,
    Stability.Experimental,
    Stability.External,
    Stability.Deprecated
  ]
};

Error Classification Levels

Production (`prod`)

Stabilities: Stable, Deprecated
Use Case: Default for production builds - only stable and deprecated API changes cause errors
Behavior: Experimental and external API changes generate warnings

Non-Experimental (`non-experimental`)

Stabilities: Stable, Deprecated, External
Use Case: Stricter validation that includes external dependencies
Behavior: Only experimental API changes generate warnings

All (`all`)

Stabilities: Stable, Experimental, External, Deprecated
Use Case: Maximum validation - all API changes cause errors
Behavior: No warnings, all compatibility violations are errors

Diagnostic Suppression

Diagnostics can be suppressed using violation keys:

Generate Keys: Run with --keys flag to see suppression keys
Create Filter File: List violation keys in a text file (one per line)
Apply Filter: Use --ignore-file option or skipFilter parameter
Key Format: {ruleKey}:{apiElementIdentifier}

Example suppression file:

# Suppress specific method removal
method-removed:MyClass.deprecatedMethod

# Suppress property type changes  
property-type-changed:MyInterface.configValue