Code Generation

/**
 * Generate target language bindings from jsii assemblies
 * @param options Configuration for code generation
 * @returns Promise that resolves when generation completes
 */
function pacmak(options: PacmakOptions): Promise<void>;

/**
 * Configuration options for pacmak code generation
 */
interface PacmakOptions {
  /** Assembly file paths to process */
  assemblies: string[];
  /** Target languages to generate */
  targets: TargetName[];
  /** Output directory for generated code */
  outdir: string;
  /** Generate fingerprints for outputs */
  fingerprint?: boolean;
  /** Force regeneration of existing files */
  force?: boolean;
  /** Whether to validate generated code */
  validate?: boolean;
  /** Parallel generation jobs */
  parallel?: number;
  /** Arguments for specific target builders */
  arguments?: { [target: string]: { [key: string]: any } };
  /** Code examples directory */
  rosetta?: {
    /** Rosetta cache directory */
    cacheDir?: string;
    /** Example source directories */
    exampleDirs?: string[];
    /** Loose mode for examples */
    loose?: boolean;
  };
}

/**
 * Supported target language names
 */
enum TargetName {
  /** .NET/C# bindings */
  DOTNET = "dotnet",
  /** Go bindings */
  GO = "go",
  /** Java bindings */
  JAVA = "java", 
  /** JavaScript/TypeScript bindings */
  JAVASCRIPT = "js",
  /** Python bindings */
  PYTHON = "python"
}

/**
 * Factory function for creating target builders
 */
type BuilderFactory = (options: any) => TargetBuilder;

/**
 * Map of all available target builders
 */
const ALL_BUILDERS: { [target in TargetName]: BuilderFactory };

/**
 * Base interface for target language builders
 */
interface TargetBuilder {
  /** Generate code for the target language */
  build(): Promise<void>;
  
  /** Target language name */
  readonly targetName: TargetName;
  
  /** Output directory */
  readonly outputDir: string;
}

/**
 * Python target configuration options
 */
interface PythonTargetOptions {
  /** Python package distribution name */
  distName?: string;
  /** Python module name */  
  module?: string;
  /** PyPI classifiers */
  classifiers?: string[];
  /** Package description */
  description?: string;
  /** Package homepage URL */
  homepage?: string;
  /** Author information */
  author?: {
    name?: string;
    email?: string;
  };
  /** Package license */
  license?: string;
  /** Additional package data */
  data?: { [path: string]: string[] };
}

/**
 * Python package generation builder
 */
class PythonBuilder implements TargetBuilder {
  readonly targetName = TargetName.PYTHON;
  readonly outputDir: string;

  /**
   * Create Python builder
   * @param assembly jsii assembly to process
   * @param options Python generation options
   */
  constructor(assembly: Assembly, options: PythonTargetOptions);

  /**
   * Generate Python package
   */
  build(): Promise<void>;
}

/**
 * Java target configuration options
 */
interface JavaTargetOptions {
  /** Java package name */
  package?: string;
  /** Maven configuration */
  maven?: {
    /** Maven group ID */
    groupId?: string;
    /** Maven artifact ID */
    artifactId?: string;
    /** Maven version */
    version?: string;
    /** Additional dependencies */
    dependencies?: Array<{
      groupId: string;
      artifactId: string;
      version: string;
      scope?: string;
    }>;
  };
  /** Package description */
  description?: string;
  /** Package URL */
  url?: string;
}

/**
 * Java package generation builder
 */
class JavaBuilder implements TargetBuilder {
  readonly targetName = TargetName.JAVA;
  readonly outputDir: string;

  /**
   * Create Java builder
   * @param assembly jsii assembly to process
   * @param options Java generation options
   */
  constructor(assembly: Assembly, options: JavaTargetOptions);

  /**
   * Generate Java Maven project
   */
  build(): Promise<void>;
}

/**
 * .NET target configuration options
 */
interface DotNetTargetOptions {
  /** .NET namespace */
  namespace?: string;
  /** NuGet package ID */
  packageId?: string;
  /** Package title */
  title?: string;
  /** Package description */
  description?: string;
  /** Package version */
  version?: string;
  /** Package authors */
  authors?: string[];
  /** Company name */
  company?: string;
  /** Package icon URL */
  iconUrl?: string;
  /** Strong naming key file */
  signAssembly?: boolean;
  /** Assembly key file path */
  assemblyOriginatorKeyFile?: string;
}

/**
 * .NET package generation builder
 */
class DotNetBuilder implements TargetBuilder {
  readonly targetName = TargetName.DOTNET;
  readonly outputDir: string;

  /**
   * Create .NET builder
   * @param assembly jsii assembly to process
   * @param options .NET generation options
   */
  constructor(assembly: Assembly, options: DotNetTargetOptions);

  /**
   * Generate .NET/C# project
   */
  build(): Promise<void>;
}

/**
 * Go target configuration options
 */
interface GoTargetOptions {
  /** Go module name */
  moduleName?: string;
  /** Go package name */
  packageName?: string;
  /** Package description */ 
  description?: string;
  /** Package version */
  version?: string;
  /** Git tag prefix */
  gitTagPrefix?: string;
  /** Go version constraint */
  goVersion?: string;
}

/**
 * Go package generation builder
 */
class GoBuilder implements TargetBuilder {
  readonly targetName = TargetName.GO;
  readonly outputDir: string;

  /**
   * Create Go builder
   * @param assembly jsii assembly to process
   * @param options Go generation options
   */
  constructor(assembly: Assembly, options: GoTargetOptions);

  /**
   * Generate Go module
   */
  build(): Promise<void>;
}

/**
 * JavaScript target configuration options
 */
interface JavaScriptTargetOptions {
  /** npm package name */
  npm?: string;
  /** Package description */
  description?: string;
  /** Package homepage */
  homepage?: string;
  /** Package repository */
  repository?: {
    type?: string;
    url?: string;
  };
  /** Package keywords */
  keywords?: string[];
  /** Package author */
  author?: string | {
    name?: string;
    email?: string;
    url?: string;
  };
}

/**
 * JavaScript package generation builder
 */
class JavaScriptBuilder implements TargetBuilder {
  readonly targetName = TargetName.JAVASCRIPT;
  readonly outputDir: string;

  /**
   * Create JavaScript builder
   * @param assembly jsii assembly to process
   * @param options JavaScript generation options
   */
  constructor(assembly: Assembly, options: JavaScriptTargetOptions);

  /**
   * Generate JavaScript/TypeScript npm package
   */
  build(): Promise<void>;
}

/**
 * Configure logging for pacmak operations
 * @param level Log level (error, warn, info, debug)
 * @param format Log format options
 */
function configureLogging(level: string, format?: {
  colors?: boolean;
  timestamp?: boolean;
}): void;

/**
 * Disclaimer text for non-compiling generated examples
 */
const INCOMPLETE_DISCLAIMER_NONCOMPILING: string;

/**
 * Validate target configuration
 * @param target Target name to validate
 * @param options Target-specific options
 * @returns Validation result
 */
function validateTargetOptions(
  target: TargetName, 
  options: any
): { valid: boolean; errors?: string[] };

/**
 * Get default output directory for target
 * @param target Target language
 * @param baseDir Base output directory
 * @returns Target-specific output path
 */
function getTargetOutputDir(target: TargetName, baseDir: string): string;

/**
 * Generate code examples using Rosetta
 * @param assembly jsii assembly
 * @param target Target language
 * @param options Rosetta options
 */
function generateExamples(
  assembly: Assembly,
  target: TargetName, 
  options?: {
    strict?: boolean;
    cacheDir?: string;
  }
): Promise<{ [exampleId: string]: string }>;

/**
 * Load assemblies for code generation
 * @param assemblyPaths Paths to assembly files
 * @returns Loaded assemblies with dependencies
 */
function loadAssemblies(assemblyPaths: string[]): Assembly[];

/**
 * Resolve assembly dependencies
 * @param assemblies Primary assemblies
 * @returns All assemblies including dependencies
 */
function resolveDependencies(assemblies: Assembly[]): Assembly[];

/**
 * Validate assemblies for code generation
 * @param assemblies Assemblies to validate
 * @returns Validation results
 */
function validateAssemblies(assemblies: Assembly[]): {
  valid: boolean;
  errors: Array<{
    assembly: string;
    message: string;
  }>;
};

/**
 * Extract metadata from assembly for target generation
 * @param assembly jsii assembly
 * @param target Target language
 * @returns Target-specific metadata
 */
function extractTargetMetadata(
  assembly: Assembly,
  target: TargetName
): { [key: string]: any };

/**
 * Assembly loaded for code generation
 */
interface Assembly {
  /** Assembly specification */
  spec: import('@jsii/spec').Assembly;
  /** Assembly metadata */
  metadata: { [key: string]: any };
  /** Assembly file path */
  path: string;
  /** Loaded dependencies */
  dependencies: Assembly[];
}

/**
 * Code generation context
 */
interface GenerationContext {
  /** Current assembly */
  assembly: Assembly;
  /** Target language */
  target: TargetName;
  /** Output directory */
  outputDir: string;
  /** Generation options */
  options: any;
  /** Example snippets */
  examples?: { [id: string]: string };
}

/**
 * Generated file information
 */
interface GeneratedFile {
  /** Relative file path */
  path: string;
  /** File content */
  content: string;
  /** File permissions */
  permissions?: number;
  /** Whether file is executable */
  executable?: boolean;
}

/**
 * Generation result
 */
interface GenerationResult {
  /** Generated files */
  files: GeneratedFile[];
  /** Generation warnings */
  warnings?: string[];
  /** Generation metadata */
  metadata?: { [key: string]: any };
}

// Basic code generation for multiple targets
import { pacmak, TargetName } from 'jsii-pacmak';

await pacmak({
  assemblies: ['./lib/my-library/.jsii'],
  targets: [TargetName.PYTHON, TargetName.JAVA, TargetName.DOTNET],
  outdir: './dist'
});

// Advanced configuration with target-specific options
await pacmak({
  assemblies: ['./lib/my-library/.jsii'],
  targets: [TargetName.PYTHON, TargetName.JAVA],
  outdir: './packages',
  arguments: {
    python: {
      distName: 'my-awesome-library',
      classifiers: [
        'Development Status :: 5 - Production/Stable',
        'Programming Language :: Python :: 3.8'
      ]
    },
    java: {
      maven: {
        groupId: 'com.example',
        artifactId: 'my-library'
      }
    }
  },
  rosetta: {
    cacheDir: './rosetta-cache',
    exampleDirs: ['./examples']
  }
});

// Generate single target with validation
import { configureLogging } from 'jsii-pacmak';

configureLogging('info', { colors: true });

await pacmak({
  assemblies: ['./lib/my-library/.jsii'],
  targets: [TargetName.GO],
  outdir: './go-bindings',
  validate: true,
  arguments: {
    go: {
      moduleName: 'github.com/example/my-library-go',
      goVersion: '1.19'
    }
  }
});