Assembly Reflection

/**
 * Main entry point for loading and managing assemblies
 */
class TypeSystem {
  /**
   * The root assemblies (explicitly loaded)
   */
  readonly roots: readonly Assembly[];

  /**
   * Whether the TypeSystem is locked from further changes
   */
  readonly isLocked: boolean;

  /**
   * All assemblies in this type system
   */
  get assemblies(): readonly Assembly[];

  /**
   * Create new TypeSystem instance
   */
  constructor();

  /**
   * Lock the TypeSystem from further changes for optimization
   */
  lock(): void;

  /**
   * Load JSII dependencies of NPM package directory
   * @param packageRoot Path to package directory
   * @param options Loading options
   */
  async loadNpmDependencies(
    packageRoot: string, 
    options?: { validate?: boolean }
  ): Promise<void>;

  /**
   * Load jsii module or .jsii file with dependencies
   * @param fileOrDirectory Path to .jsii file or module directory
   * @param options Loading options
   */
  async load(
    fileOrDirectory: string, 
    options?: { validate?: boolean }
  ): Promise<Assembly>;

  /**
   * Load jsii module by directory
   * @param dir Module directory path
   * @param options Loading options
   */
  async loadModule(
    dir: string, 
    options?: { validate?: boolean }
  ): Promise<Assembly>;

  /**
   * Load assembly file directly
   * @param file Path to .jsii file
   * @param options Loading options
   */
  async loadFile(
    file: string,
    options?: { isRoot?: boolean; validate?: boolean }
  ): Promise<Assembly>;

  /**
   * Find assembly by name (throws if not found)
   * @param name Assembly name to find
   * @returns Assembly instance
   */
  findAssembly(name: string): Assembly;

  /**
   * Try to find assembly by name
   * @param name Assembly name to find
   * @returns Assembly instance or undefined
   */
  tryFindAssembly(name: string): Assembly | undefined;

  /**
   * Find type by fully qualified name (throws if not found)
   * @param fqn Fully qualified type name
   * @returns Type instance
   */
  findFqn(fqn: string): Type;

  /**
   * Try to find type by fully qualified name
   * @param fqn Fully qualified type name
   * @returns Type instance or undefined
   */
  tryFindFqn(fqn: string): Type | undefined;

  /**
   * Find class by fully qualified name (throws if not found)
   * @param fqn Fully qualified class name
   * @returns Class instance
   */
  findClass(fqn: string): Class;

  /**
   * Check if assembly is included
   * @param name Assembly name
   * @returns True if assembly is loaded
   */
  includesAssembly(name: string): boolean;
}

/**
 * Represents a loaded jsii assembly
 */
class Assembly extends ModuleLike {
  /**
   * Assembly name
   */
  readonly name: string;

  /**
   * Assembly version
   */
  readonly version: string;

  /**
   * Assembly description
   */
  readonly description?: string;

  /**
   * Assembly homepage URL
   */
  readonly homepage?: string;

  /**
   * Assembly repository information
   */
  readonly repository?: {
    type?: string;
    url?: string;
    directory?: string;
  };

  /**
   * Assembly author
   */
  readonly author?: {
    name?: string;
    email?: string;
    url?: string;
  };

  /**
   * Assembly license
   */
  readonly license?: string;

  /**
   * All classes in this assembly
   */
  readonly classes: readonly Class[];

  /**
   * All interfaces in this assembly
   */
  readonly interfaces: readonly Interface[];

  /**
   * All enums in this assembly
   */
  readonly enums: readonly Enum[];

  /**
   * Assembly dependencies
   */
  readonly dependencies: readonly Dependency[];

  /**
   * Assembly submodules
   */
  readonly submodules: readonly Submodule[];

  /**
   * Assembly targets configuration
   */
  readonly targets?: { [language: string]: any };

  /**
   * Assembly bundled dependencies
   */
  readonly bundled?: { [name: string]: string };

  /**
   * Assembly metadata
   */
  readonly metadata?: { [key: string]: any };

  /**
   * Assembly fingerprint
   */
  readonly fingerprint?: string;

  /**
   * Get assembly specification object
   */
  get spec(): import('@jsii/spec').Assembly;

  /**
   * Find class by name within this assembly
   * @param name Class name (can be FQN or simple name)
   */
  findClass(name: string): Class | undefined;

  /**
   * Find interface by name within this assembly  
   * @param name Interface name (can be FQN or simple name)
   */
  findInterface(name: string): Interface | undefined;

  /**
   * Find enum by name within this assembly
   * @param name Enum name (can be FQN or simple name)
   */
  findEnum(name: string): Enum | undefined;

  /**
   * Find type by name within this assembly
   * @param name Type name (can be FQN or simple name)
   */
  findType(name: string): Type | undefined;
}

/**
 * Represents a class type in an assembly
 */
class Class extends ReferenceType {
  /**
   * Class constructor/initializer
   */
  readonly initializer?: Initializer;

  /**
   * Whether the class is abstract
   */
  readonly abstract: boolean;

  /**
   * Base class (superclass)
   */
  readonly base?: Class;

  /**
   * All implemented interfaces
   */
  readonly interfaces: readonly Interface[];

  /**
   * Properties defined directly on this class (not inherited)
   */
  readonly ownProperties: readonly Property[];

  /**
   * Methods defined directly on this class (not inherited)
   */
  readonly ownMethods: readonly Method[];

  /**
   * All properties including inherited ones
   */
  readonly allProperties: readonly Property[];

  /**
   * All methods including inherited ones
   */
  readonly allMethods: readonly Method[];

  /**
   * Whether this class can be instantiated
   */
  get isInstantiable(): boolean;

  /**
   * Get all superclasses in inheritance chain
   */
  get ancestors(): readonly Class[];

  /**
   * Check if this class extends another class
   * @param other Class to check inheritance from
   */
  extends(other: Class): boolean;

  /**
   * Check if this class implements an interface
   * @param iface Interface to check implementation of
   */
  implements(iface: Interface): boolean;

  /**
   * Find property by name (including inherited)
   * @param name Property name
   */
  findProperty(name: string): Property | undefined;

  /**
   * Find method by name (including inherited)
   * @param name Method name
   */
  findMethod(name: string): Method | undefined;
}

/**
 * Represents an interface type in an assembly
 */
class Interface extends ReferenceType {
  /**
   * Whether this is a data-only interface (struct)
   */
  readonly datatype: boolean;

  /**
   * Extended interfaces
   */
  readonly interfaces: readonly Interface[];

  /**
   * Properties defined on this interface
   */
  readonly ownProperties: readonly Property[];

  /**
   * Methods defined on this interface
   */
  readonly ownMethods: readonly Method[];

  /**
   * All properties including inherited ones
   */
  readonly allProperties: readonly Property[];

  /**
   * All methods including inherited ones
   */
  readonly allMethods: readonly Method[];

  /**
   * Get all extended interfaces in inheritance chain
   */
  get extends(): readonly Interface[];

  /**
   * Check if this interface extends another interface
   * @param other Interface to check inheritance from
   */
  extendsInterface(other: Interface): boolean;

  /**
   * Find property by name (including inherited)
   * @param name Property name
   */
  findProperty(name: string): Property | undefined;

  /**
   * Find method by name (including inherited)
   * @param name Method name
   */
  findMethod(name: string): Method | undefined;
}

/**
 * Represents a method on a class or interface
 */
class Method extends Callable {
  /**
   * Method name
   */
  readonly name: string;

  /**
   * Return type reference (undefined for void methods)
   */
  readonly returns?: TypeRef;

  /**
   * Whether method is static
   */
  readonly static: boolean;

  /**
   * Whether method is abstract
   */
  readonly abstract: boolean;

  /**
   * Whether method is protected
   */
  readonly protected: boolean;

  /**
   * Whether method is async
   */
  readonly async: boolean;

  /**
   * Method signature as string
   */
  get signature(): string;

  /**
   * Whether method returns a value
   */
  get returnsValue(): boolean;

  /**
   * Whether method can be overridden
   */
  get canOverride(): boolean;
}

/**
 * Base class for callable members (methods and constructors)
 */
class Callable extends TypeMember {
  /**
   * Method parameters
   */
  readonly parameters: readonly Parameter[];

  /**
   * Whether callable is variadic (has ...args)
   */
  readonly variadic: boolean;

  /**
   * Parameter signature string
   */
  get parameterSignature(): string;

  /**
   * Find parameter by name
   * @param name Parameter name
   */
  findParameter(name: string): Parameter | undefined;
}

/**
 * Represents a constructor/initializer
 */
class Initializer extends Callable {
  /**
   * Whether constructor is protected
   */
  readonly protected: boolean;
}

/**
 * Represents a property on a class or interface
 */
class Property extends TypeMember {
  /**
   * Property name
   */
  readonly name: string;

  /**
   * Property type reference
   */
  readonly type: TypeRef;

  /**
   * Whether property is static
   */
  readonly static: boolean;

  /**
   * Whether property is immutable (readonly)
   */
  readonly immutable: boolean;

  /**
   * Whether property is abstract
   */
  readonly abstract: boolean;

  /**
   * Whether property is protected
   */
  readonly protected: boolean;

  /**
   * Whether property is optional
   */
  readonly optional: boolean;

  /**
   * Whether property is const
   */
  readonly const: boolean;

  /**
   * Property type as string
   */
  get typeSignature(): string;

  /**
   * Whether property has a getter
   */
  get hasGetter(): boolean;

  /**
   * Whether property has a setter
   */
  get hasSetter(): boolean;

  /**
   * Whether property can be overridden
   */
  get canOverride(): boolean;
}

/**
 * Represents a method parameter
 */
class Parameter extends OptionalValue {
  /**
   * Parameter name
   */
  readonly name: string;

  /**
   * Parameter type reference
   */
  readonly type: TypeRef;

  /**
   * Whether parameter is variadic (...args)
   */
  readonly variadic: boolean;

  /**
   * Parameter signature string
   */
  get signature(): string;
}

/**
 * Represents an enumeration type
 */
class Enum extends Type {
  /**
   * Enumeration members
   */
  readonly members: readonly EnumMember[];

  /**
   * Find member by name
   * @param name Member name
   */
  findMember(name: string): EnumMember | undefined;

  /**
   * Find member by value
   * @param value Member value
   */
  findMemberByValue(value: string | number): EnumMember | undefined;
}

/**
 * Represents an enumeration member
 */
class EnumMember {
  /**
   * Member name
   */
  readonly name: string;

  /**
   * Member value
   */
  readonly value?: string | number;

  /**
   * Parent enum
   */
  readonly enum: Enum;

  /**
   * Member documentation
   */
  readonly docs: Docs;

  /**
   * Whether member is deprecated
   */
  get isDeprecated(): boolean;
}

/**
 * Type reference representation
 */
class TypeRef {
  /**
   * Create type reference from spec
   * @param system Type system for resolution
   * @param spec Type reference specification
   */
  constructor(system: TypeSystem, spec: import('@jsii/spec').TypeReference);

  /**
   * Whether this is a primitive type
   */
  get isPrimitive(): boolean;

  /**
   * Whether this is a collection type
   */
  get isCollection(): boolean;

  /**
   * Whether this is a union type
   */
  get isUnion(): boolean;

  /**
   * Whether this is an intersection type
   */
  get isIntersection(): boolean;

  /**
   * Primitive type (if isPrimitive)
   */
  get primitive(): import('@jsii/spec').PrimitiveType | undefined;

  /**
   * Array element type (if isCollection && kind=Array)
   */
  get arrayOfType(): TypeRef | undefined;

  /**
   * Map value type (if isCollection && kind=Map)
   */
  get mapOfType(): TypeRef | undefined;

  /**
   * Union member types (if isUnion)
   */
  get unionOfTypes(): readonly TypeRef[] | undefined;

  /**
   * Intersection member types (if isIntersection)
   */
  get intersectionOfTypes(): readonly TypeRef[] | undefined;

  /**
   * Referenced type (if type reference)
   */
  get type(): Type | undefined;

  /**
   * String representation of this type
   */
  toString(): string;

  /**
   * Type specification object
   */
  get spec(): import('@jsii/spec').TypeReference;
}

/**
 * Base class for reference types (classes and interfaces)
 */
class ReferenceType extends Type {
  /**
   * All members (properties and methods) on this type
   */
  readonly allMembers: readonly TypeMember[];

  /**
   * Find member by name
   * @param name Member name
   */
  findMember(name: string): TypeMember | undefined;
}

/**
 * Documentation information
 */
class Docs {
  /**
   * Create docs from specification
   * @param spec Documentation specification
   */
  constructor(spec?: import('@jsii/spec').Docs);

  /**
   * Brief summary
   */
  readonly summary?: string;

  /**
   * Extended remarks
   */
  readonly remarks?: string;

  /**
   * Return value description
   */
  readonly returns?: string;

  /**
   * Default value description
   */
  readonly default?: string;

  /**
   * Deprecation notice
   */
  readonly deprecated?: string;

  /**
   * Usage example
   */
  readonly example?: string;

  /**
   * See-also references
   */
  readonly see?: string;

  /**
   * Since version
   */
  readonly since?: string;

  /**
   * Whether type is subclassable
   */
  readonly subclassable?: boolean;

  /**
   * Custom documentation tags
   */
  readonly customTags: { [key: string]: string };

  /**
   * Whether documentation exists
   */
  get exists(): boolean;

  /**
   * Full documentation as string
   */
  toString(): string;
}

/**
 * Source location information
 */
class Source {
  /**
   * Source file name
   */
  readonly filename: string;

  /**
   * Line number (1-based)
   */
  readonly line: number;

  /**
   * Column number (1-based)
   */
  readonly column: number;

  /**
   * Source location as string
   */
  toString(): string;
}

/**
 * Assembly dependency information
 */
class Dependency {
  /**
   * Dependency name
   */
  readonly name: string;

  /**
   * Dependency version
   */
  readonly version: string;

  /**
   * Loaded assembly for this dependency
   */
  readonly assembly?: Assembly;

  /**
   * Dependency submodules
   */
  readonly submodules?: readonly string[];
}

/**
 * Base class for all types
 */
class Type {
  /**
   * Type system this type belongs to
   */
  readonly system: TypeSystem;

  /**
   * Parent assembly
   */
  readonly assembly: Assembly;

  /**
   * Fully qualified name
   */
  readonly fqn: string;

  /**
   * Simple type name
   */
  readonly name: string;

  /**
   * Type namespace
   */
  readonly namespace?: string;

  /**
   * Type documentation
   */
  readonly docs: Docs;

  /**
   * Source location
   */
  readonly source?: Source;

  /**
   * Whether type is deprecated
   */
  get isDeprecated(): boolean;

  /**
   * API stability level
   */
  readonly stability?: import('@jsii/spec').Stability;

  /**
   * Type specification
   */
  get spec(): import('@jsii/spec').Type;

  /**
   * String representation
   */
  toString(): string;
}

/**
 * Base class for type members
 */
class TypeMember {
  /**
   * Member name
   */
  readonly name: string;

  /**
   * Parent type
   */
  readonly parentType: ReferenceType;

  /**
   * Member documentation
   */
  readonly docs: Docs;

  /**
   * Source location
   */
  readonly source?: Source;

  /**
   * Whether member is deprecated
   */
  get isDeprecated(): boolean;

  /**
   * Whether member can be overridden
   */
  readonly override: boolean;

  /**
   * String representation
   */
  toString(): string;
}

/**
 * Base for optional values
 */
class OptionalValue {
  /**
   * Whether value is optional
   */
  readonly optional: boolean;
}

/**
 * Base for module-like entities
 */
class ModuleLike {
  /**
   * Submodules
   */
  readonly submodules: readonly Submodule[];

  /**
   * Find submodule by name
   * @param name Submodule name
   */
  findSubmodule(name: string): Submodule | undefined;
}

/**
 * Represents a submodule
 */
class Submodule extends ModuleLike {
  /**
   * Submodule name
   */
  readonly name: string;

  /**
   * Parent assembly
   */
  readonly assembly: Assembly;

  /**
   * Submodule documentation
   */
  readonly docs: Docs;

  /**
   * Submodule README
   */
  readonly readme?: string;

  /**
   * Target configurations
   */
  readonly targets?: { [language: string]: any };
}

/**
 * Tree representation for assemblies
 */
class Tree {
  /**
   * Create tree from assembly
   * @param assembly Assembly to visualize
   * @param options Tree generation options
   */
  static fromAssembly(assembly: Assembly, options?: {
    types?: boolean;
    members?: boolean;
    inherited?: boolean;
  }): Tree;

  /**
   * Render tree as ASCII art
   * @returns ASCII tree string
   */
  toString(): string;

  /**
   * Print tree to console
   */
  print(): void;
}

/**
 * Assembly loading options
 */
interface LoadOptions {
  /** Whether to validate assembly */
  validate?: boolean;
  /** Whether to load dependencies */
  loadDependencies?: boolean;
  /** Dependency search paths */
  searchPaths?: string[];
}

/**
 * Type visitor interface
 */
interface TypeVisitor {
  /** Visit a class */
  visitClass?(cls: Class): void;
  /** Visit an interface */
  visitInterface?(iface: Interface): void;
  /** Visit an enum */
  visitEnum?(enumType: Enum): void;
  /** Visit a method */
  visitMethod?(method: Method): void;
  /** Visit a property */
  visitProperty?(property: Property): void;
}

/**
 * Assembly analysis result
 */
interface AnalysisResult {
  /** Total types */
  typeCount: number;
  /** Class count */
  classCount: number;
  /** Interface count */  
  interfaceCount: number;
  /** Enum count */
  enumCount: number;
  /** Method count */
  methodCount: number;
  /** Property count */
  propertyCount: number;
  /** Dependencies */
  dependencies: string[];
}

// Load and analyze an assembly
import { TypeSystem } from 'jsii-reflect';

const typeSystem = new TypeSystem();
const assembly = typeSystem.loadAssembly('./my-lib/.jsii');

// Explore classes
for (const cls of assembly.classes) {
  console.log(`Class: ${cls.name}`);
  
  if (cls.base) {
    console.log(`  Extends: ${cls.base.name}`);
  }
  
  for (const iface of cls.interfaces) {
    console.log(`  Implements: ${iface.name}`);
  }
  
  // Examine methods
  for (const method of cls.ownMethods) {
    console.log(`  Method: ${method.signature}`);
    if (method.docs.summary) {
      console.log(`    ${method.docs.summary}`);
    }
  }
}

// Find specific types
const myClass = assembly.findClass('MyClass');
if (myClass) {
  const myMethod = myClass.findMethod('doSomething');
  if (myMethod) {
    console.log(`Found method: ${myMethod.signature}`);
    for (const param of myMethod.parameters) {
      console.log(`  Parameter: ${param.name}: ${param.type}`);
    }
  }
}

// Visualize assembly structure
import { Tree } from 'jsii-reflect';

const tree = Tree.fromAssembly(assembly, {
  types: true,
  members: true,
  inherited: false
});

tree.print();