Assembly Comparison

/**
 * Compare two assemblies for compatibility
 * 
 * Checks whether code written against the original assembly will still
 * typecheck when compiled against the updated assembly. Validates that:
 * - All types in original still exist in updated
 * - Enums have only added members  
 * - Classes/interfaces have only added members or allowed modifications
 * - Property types are same or strengthened
 * - Method arguments only added optional, existing weakened, return strengthened
 * 
 * @param original - The original assembly to compare from
 * @param updated - The updated assembly to compare to  
 * @param options - Configuration options for comparison
 * @returns Mismatches object containing any compatibility violations
 */
function compareAssemblies(
  original: reflect.Assembly,
  updated: reflect.Assembly,
  options?: ComparisonOptions
): Mismatches;

import { compareAssemblies } from "jsii-diff";
import * as reflect from "jsii-reflect";

// Compare two local assemblies
const ts1 = new reflect.TypeSystem();
const original = ts1.loadModule("./packages/my-lib");

const ts2 = new reflect.TypeSystem();
const updated = ts2.loadModule("./packages/my-lib-v2");

const mismatches = compareAssemblies(original, updated);

// Check for any compatibility issues
if (mismatches.count > 0) {
  console.log(`Found ${mismatches.count} compatibility issues:`);
  for (const message of mismatches.messages()) {
    console.log(`- ${message}`);
  }
}

// Compare with custom options
const mismatchesExperimental = compareAssemblies(original, updated, {
  defaultExperimental: true // treat unmarked APIs as experimental
});

/**
 * Configuration options for assembly comparison
 */
interface ComparisonOptions {
  /** 
   * Whether to treat API elements as experimental if unmarked
   * When true, unmarked APIs are treated as experimental (more lenient rules)
   * When false, unmarked APIs are treated as stable (stricter rules)
   * @default false (treat as stable)
   */
  defaultExperimental?: boolean;
}

/**
 * Collection of API compatibility mismatches with reporting capabilities
 */
class Mismatches implements IReport {
  /** Array of all collected compatibility violations */
  readonly mismatches: Array<ApiMismatch>;
  
  /**
   * Create a new mismatches collection
   * @param opts - Configuration including default stability level
   */
  constructor(opts: { defaultStability: Stability });
  
  /**
   * Report a new API compatibility violation
   * @param options - Details of the violation to report
   */
  report(options: ReportOptions): void;
  
  /**
   * Iterate over all mismatch messages
   * @returns Iterator of human-readable violation messages
   */
  messages(): IterableIterator<string>;
  
  /** Total number of compatibility violations found */
  readonly count: number;
  
  /**
   * Create filtered copy of mismatches based on predicate
   * @param pred - Function to test each mismatch
   * @returns New Mismatches instance with filtered results
   */
  filter(pred: (x: ApiMismatch) => boolean): Mismatches;
  
  /**
   * Create reporter with additional context for all future reports
   * @param motivation - Context string to append to violation messages
   * @returns New reporter with motivation context
   */
  withMotivation(motivation: string): IReport;
}

/**
 * Represents a single API compatibility violation
 */
interface ApiMismatch {
  /** Human-readable description of the compatibility violation */
  message: string;
  /** Unique identifier for this violation type and element */
  violationKey: string;
  /** Stability level of the API element that has the violation */
  stability: Stability;
}

/**
 * Options for reporting an API compatibility violation
 */
interface ReportOptions {
  /** Identifier for the type of rule that was violated */
  ruleKey: string;
  /** The specific API element that violates compatibility */
  violator: ApiElement;
  /** Description of how the element violates compatibility */
  message: string;
}

/**
 * Interface for reporting API compatibility violations
 */
interface IReport {
  /**
   * Report an API compatibility violation
   * @param options - Details of the violation
   */
  report(options: ReportOptions): void;
  
  /**
   * Create a reporter with additional context
   * @param reason - Context to add to future reports
   * @returns New reporter with added context
   */
  withMotivation(reason: string): IReport;
}