Assembly Specification

/**
 * Main interface for JSII assembly specification
 */
interface Assembly extends AssemblyConfiguration, Documentable, ReadMeContainer {
  /** Schema version of this assembly (always 'jsii/0.10.0') */
  schema: SchemaVersion.LATEST;
  /** Assembly name */
  name: string;
  /** Assembly description (required for some package managers) */
  description: string;
  /** Assembly version */
  version: string;
  /** Homepage URL (required) */
  homepage: string;
  /** Repository information (required) */
  repository: {
    /** Repository type (git, svn, etc.) */
    type: string;
    /** Repository URL */
    url: string;
    /** Directory within repo for monorepos */
    directory?: string;
  };
  /** Main author information (required) */
  author: Person;
  /** Additional contributors */
  contributors?: Person[];
  /** Assembly fingerprint for validation (required) */
  fingerprint: string;
  /** jsii compiler version used to produce this assembly */
  jsiiVersion: string;
  /** SPDX license identifier (required) */
  license: string;
  /** Arbitrary metadata key-value pairs */
  metadata?: { [key: string]: any };
  /** Keywords for package discovery */
  keywords?: string[];
  /** Direct dependencies on other assemblies */
  dependencies?: { [assembly: string]: string };
  /** Target configuration for dependency closure */
  dependencyClosure?: { [assembly: string]: DependencyConfiguration };
  /** Bundled dependency versions */
  bundled?: { [module: string]: string };
  /** Type definitions indexed by fully qualified name */
  types?: { [fqn: string]: Type };
  /** Binary scripts */
  bin?: { readonly [script: string]: string };
  /** Features used in this assembly */
  usedFeatures?: JsiiFeature[];
}

/**
 * Configuration shared between assemblies
 */
interface AssemblyConfiguration extends Targetable {
  /** Submodules declared in this assembly */
  submodules?: { [fqn: string]: Submodule };
}

/**
 * Configuration for assembly dependencies
 */
interface DependencyConfiguration extends Targetable {
  /** Submodule dependencies */
  submodules?: { [fqn: string]: Targetable };
}

/**
 * Base interface for all type definitions
 */
interface TypeBase extends Documentable, SourceLocatable {
  /** Fully qualified name */
  fqn: FQN;
  /** Assembly name containing this type */
  assembly: string;
  /** Type namespace/module */
  namespace?: string;
  /** Simple type name */
  name?: string;
  /** Source location */
  locationInModule?: SourceLocation;
  /** Whether type is abstract */
  abstract?: boolean;
  /** Deprecation information */
  deprecated?: string | boolean;
  /** API stability level */
  stability?: Stability;
}

/**
 * Union type for all type definitions
 */
type Type = ClassType | InterfaceType | EnumType;

/**
 * Enumeration of type kinds
 */
enum TypeKind {
  Class = "class",
  Enum = "enum",
  Interface = "interface"
}

/**
 * Represents a class type
 */
interface ClassType extends TypeBase {
  kind: TypeKind.Class;
  /** Whether class is abstract */
  abstract?: boolean;
  /** Base class FQN */
  base?: string;
  /** Implemented interface FQNs */
  interfaces?: string[];
  /** Constructor definition */
  initializer?: Initializer;
  /** Class properties */
  properties?: Property[];
  /** Class methods */
  methods?: Method[];
}

/**
 * Represents an interface type  
 */
interface InterfaceType extends TypeBase {
  kind: TypeKind.Interface;
  /** Interface properties */
  properties?: Property[];
  /** Interface methods */
  methods?: Method[];
  /** Whether this is a data-only interface */
  datatype?: boolean;
  /** Extended interface FQNs */
  interfaces?: string[];
}

/**
 * Represents an enumeration type
 */
interface EnumType extends TypeBase {
  kind: TypeKind.Enum;
  /** Enumeration members */
  members: EnumMember[];
}

/**
 * Enumeration member definition
 */
interface EnumMember extends Documentable {
  /** Member name */
  name: string;
  /** Member value */
  value?: string | number;
}

/**
 * Reference to any type - primitive, collection, or named type
 */
type TypeReference = 
  | PrimitiveTypeReference 
  | NamedTypeReference 
  | CollectionTypeReference 
  | UnionTypeReference 
  | IntersectionTypeReference;

/**
 * Reference to a primitive type
 */
interface PrimitiveTypeReference {
  primitive: PrimitiveType;
}

/**
 * Reference to a named type by FQN
 */
interface NamedTypeReference {
  fqn: FQN;
}

/**
 * Reference to a collection type (Array or Map)
 */
interface CollectionTypeReference {
  collection: {
    kind: CollectionKind;
    elementtype: TypeReference;
  };
}

/**
 * Reference to a union of multiple types
 */
interface UnionTypeReference {
  union: {
    types: TypeReference[];
  };
}

/**
 * Reference to an intersection of multiple types
 */
interface IntersectionTypeReference {
  intersection: {
    types: TypeReference[];
  };
}

/**
 * Primitive type enumeration
 */
enum PrimitiveType {
  Date = "date",
  String = "string", 
  Number = "number",
  Boolean = "boolean",
  Json = "json",
  Any = "any"
}

/**
 * Collection type enumeration
 */
enum CollectionKind {
  Array = "array",
  Map = "map"
}

/**
 * Canonical representation of the 'any' type
 */
const CANONICAL_ANY: PrimitiveTypeReference = { primitive: PrimitiveType.Any };

/**
 * Represents a property on a class or interface
 */
interface Property extends TypeMember, OptionalValue {
  /** Property name */
  name: string;
  /** Property type reference */
  type: TypeReference;
  /** Whether property is static */
  static?: boolean;
  /** Property getter/setter access */
  immutable?: boolean;
  /** Whether property can be overridden */
  override?: boolean;
  /** Protected access modifier */
  protected?: boolean;
  /** Const qualifier */
  const?: boolean;
}

/**
 * Base interface for callable members (methods and constructors)
 */
interface Callable extends Documentable, SourceLocatable {
  /** Method parameters */
  parameters?: Parameter[];
  /** Whether method can be overridden */
  override?: boolean;  
  /** Whether method is protected */
  protected?: boolean;
  /** Whether method is variadic */
  variadic?: boolean;
}

/**
 * Represents a method
 */
interface Method extends Callable, TypeMember {
  /** Method name */
  name: string;
  /** Return type (omit for void) */
  returns?: TypeReference;
  /** Whether method is static */
  static?: boolean;
  /** Whether method is abstract */
  abstract?: boolean;
  /** Whether method is async */
  async?: boolean;
}

/**
 * Type alias for constructor definition
 */
type Initializer = Callable;

/**
 * Method or constructor parameter
 */
interface Parameter extends OptionalValue, Documentable {
  /** Parameter name */
  name: string;
  /** Parameter type */
  type: TypeReference;
  /** Whether parameter is variadic (...args) */
  variadic?: boolean;
}

/**
 * Base for overridable members
 */
interface Overridable {
  /** Whether member can be overridden */
  override?: boolean;
}

/**
 * Base interface for type members
 */
interface TypeMember extends Overridable, Documentable, SourceLocatable {
  /** Member name */
  name: string;
}

/**
 * Interface for optional values
 */
interface OptionalValue {
  /** Whether value is optional */
  optional?: boolean;
}

/**
 * Indicates that an entity can have documentation
 */
interface Documentable {
  /** Associated documentation */
  docs?: Docs;
}

/**
 * Key-value pairs of documentation nodes based on TSDoc
 */
interface Docs {
  /** Brief summary */
  summary?: string;
  /** Extended remarks */
  remarks?: string;
  /** Return value description */
  returns?: string;  
  /** Default value description */
  default?: string;
  /** Deprecation notice */
  deprecated?: string;
  /** Usage example */
  example?: string;
  /** See-also references */
  see?: string;
  /** Since version information */
  since?: string;
  /** Whether type is subclassable */
  subclassable?: boolean;
  /** Custom documentation tags */
  [key: string]: string | boolean | undefined;
}

/**
 * API stability levels
 */
enum Stability {
  /** Deprecated - will be removed */
  Deprecated = "deprecated",
  /** Experimental - may change */
  Experimental = "experimental",
  /** Stable - safe to use */
  Stable = "stable", 
  /** External - not owned by this package */
  External = "external"
}

/**
 * Source location information
 */
interface SourceLocation {
  /** Source file name */
  filename: string;
  /** Line number (1-based) */
  line: number;
  /** Column number (1-based) */
  column: number;
}

/**
 * Indicates entity has source location
 */
interface SourceLocatable {
  /** Location in source module */
  locationInModule?: SourceLocation;
}

/**
 * TypeScript source traceability
 */  
interface TypeScriptLocatable {
  /** Original TypeScript location */
  symbolId?: string;
}

/**
 * Person or organization metadata
 */
interface Person {
  /** Name */
  name: string;
  /** Roles in the project (maintainer, contributor, owner, etc.) */
  roles: string[];
  /** Contact email */
  email?: string;
  /** Website URL */
  url?: string;
}

/**
 * Interface for entities that support targets
 */
interface Targetable {
  /** Target language configurations */
  targets?: AssemblyTargets;
}

/**
 * Target language configurations for an assembly
 */
interface AssemblyTargets {
  /** JavaScript/npm configuration */
  js?: {
    npm?: string;
  };
  /** Python configuration */
  python?: {
    distName?: string;
    module?: string;
    classifiers?: string[];
  };
  /** Java configuration */  
  java?: {
    package?: string;
    maven?: {
      groupId?: string;
      artifactId?: string;
    };
  };
  /** .NET configuration */
  dotnet?: {
    namespace?: string;
    packageId?: string;
    title?: string;
  };
  /** Go configuration */
  go?: {
    moduleName?: string;
    packageName?: string;
  };
}

/**
 * Interface for README-containing entities
 */
interface ReadMeContainer {
  /** README content */
  readme?: ReadMe;
}

/**
 * README information with markdown content
 */
interface ReadMe {
  /** Markdown content */
  markdown: string;
}

/**
 * Submodule definition combining interfaces
 */
type Submodule = Targetable & ReadMeContainer & {
  /** Location in parent module */
  locationInModule?: SourceLocation;
  /** Submodule targets */
  targets?: AssemblyTargets;
};

/**
 * JSON schema for jsii assembly validation
 */
const schema: object;

/**
 * Validate assembly against JSON schema
 * @param assembly Assembly object to validate
 * @param schema JSON schema to validate against
 * @returns Validation result with errors if any
 */
function validateAssembly(assembly: Assembly, schema?: object): { 
  errors?: string[];
  valid: boolean;
};

/**
 * Expected file name for jsii assembly files
 */
const SPEC_FILE_NAME = ".jsii";

/**
 * Expected file name for compressed assemblies
 */  
const SPEC_FILE_NAME_COMPRESSED = ".jsii.gz";

/**
 * Load assembly from directory path
 */
function loadAssemblyFromPath(assemblyDir: string): Assembly;

/**
 * Load assembly from specific file path
 */
function loadAssemblyFromFile(assemblyFile: string): Assembly;

/**
 * Load assembly from buffer with redirect handling
 */
function loadAssemblyFromBuffer(buffer: Buffer): Assembly;

/**
 * Write assembly to file system
 */
function writeAssembly(
  assembly: Assembly, 
  outputPath: string,
  options?: { compress?: boolean }
): void;

/**
 * Replace existing assembly file
 */
function replaceAssembly(assemblyPath: string, assembly: Assembly): void;

/**
 * Find assembly file in directory
 */
function findAssemblyFile(directory: string): string | undefined;

/**
 * Check if compressed assembly exists
 */
function compressedAssemblyExists(directory: string): boolean;

/**
 * Type guard for NamedTypeReference
 */
function isNamedTypeReference(ref: TypeReference): ref is NamedTypeReference;

/**
 * Type guard for PrimitiveTypeReference  
 */
function isPrimitiveTypeReference(ref: TypeReference): ref is PrimitiveTypeReference;

/**
 * Type guard for CollectionTypeReference
 */
function isCollectionTypeReference(ref: TypeReference): ref is CollectionTypeReference;

/**
 * Type guard for UnionTypeReference
 */
function isUnionTypeReference(ref: TypeReference): ref is UnionTypeReference;

/**
 * Type guard for IntersectionTypeReference
 */
function isIntersectionTypeReference(ref: TypeReference): ref is IntersectionTypeReference;

/**
 * Determine whether a Callable is a Method
 */
function isMethod(callable: Callable): callable is Method;

/**
 * Type guard for ClassType
 */
function isClassType(type: Type): type is ClassType;

/**
 * Type guard for InterfaceType  
 */
function isInterfaceType(type: Type): type is InterfaceType;

/**
 * Type guard for EnumType
 */
function isEnumType(type: Type): type is EnumType;

/**
 * Type guard for class or interface types
 */
function isClassOrInterfaceType(type: Type): type is ClassType | InterfaceType;

/**
 * Return string representation of type reference
 */
function describeTypeReference(ref: TypeReference): string;

/**
 * Determine whether an entity is deprecated
 */
function isDeprecated(entity: { docs?: Docs; deprecated?: string | boolean }): boolean;

/**
 * Fully Qualified Name - unique identifier for types
 */
type FQN = string;

/**
 * Schema version enumeration
 */
enum SchemaVersion {
  LATEST = "jsii/0.10.0"
}

/**
 * jsii extension features
 */
type JsiiFeature = 'intersection-types';

/**
 * All available jsii features
 */
const ALL_FEATURES: readonly JsiiFeature[];

/**
 * Type system enforced features
 */
const ALL_TYPESYSTEM_ENFORCED_FEATURES: readonly JsiiFeature[];