Project Configuration

/**
 * Main function for interactive jsii configuration
 * Prompts user for project settings and updates package.json
 * @returns Promise that resolves when configuration is complete
 */
function jsiiConfig(): Promise<void>;

# Run interactive configuration
npx jsii-config

# The tool will prompt for various settings:
# - Project information (name, description, author)
# - Target language configurations
# - Metadata and build settings

/**
 * Structure of jsii configuration in package.json
 */
interface Config {
  /** Project metadata */
  projectInfo?: ProjectInfo;
  /** Target language configurations */
  targets?: Targets;
  /** Additional metadata */
  metadata?: ConfigMetadata;
  /** Excluded TypeScript files */
  excludeTypescript?: string[];
  /** Compression settings */
  compress?: boolean;
  /** Experimental features */
  experimentalFeatures?: {
    [feature: string]: boolean;
  };
  /** Assembly validation */
  validate?: {
    /** Whether to validate assembly */
    assembly?: boolean;
    /** Custom validation options */
    [option: string]: any;
  };
}

/**
 * Project information configuration
 */
interface ProjectInfo {
  /** Project name */
  name?: string;
  /** Project version */
  version?: string;
  /** Project description */
  description?: string;
  /** Project author */
  author?: PersonConfig;
  /** Project license */
  license?: string;
  /** Project homepage */
  homepage?: string;
  /** Project repository */
  repository?: RepositoryConfig;
  /** Project keywords */
  keywords?: string[];
  /** Project stability level */
  stability?: 'experimental' | 'stable' | 'deprecated';
}

/**
 * Person configuration (author, maintainer)
 */
interface PersonConfig {
  /** Person name */
  name?: string;
  /** Contact email */
  email?: string;
  /** Website URL */
  url?: string;
  /** Organization */
  organization?: string;
}

/**
 * Repository configuration
 */
interface RepositoryConfig {
  /** Repository type (git, svn, etc.) */
  type?: string;
  /** Repository URL */
  url?: string;
  /** Directory within repository */
  directory?: string;
}

/**
 * Target language configurations
 */
interface Targets {
  /** JavaScript/TypeScript configuration */
  js?: JavaScriptConfig;
  /** Python configuration */
  python?: PythonConfig;
  /** Java configuration */
  java?: JavaConfig;
  /** .NET configuration */
  dotnet?: DotNetConfig;
  /** Go configuration */
  go?: GoConfig;
}

/**
 * JavaScript/npm target configuration
 */
interface JavaScriptConfig {
  /** npm package name */
  npm?: string;
  /** Package description override */
  description?: string;
  /** Package keywords */
  keywords?: string[];
  /** Package author override */
  author?: PersonConfig;
  /** Package homepage override */
  homepage?: string;
  /** Package repository override */
  repository?: RepositoryConfig;
}

/**
 * Python target configuration
 */
interface PythonConfig {
  /** PyPI distribution name */
  distName?: string;
  /** Python module name */
  module?: string;
  /** Package classifiers for PyPI */
  classifiers?: string[];
  /** Package description override */
  description?: string;
  /** Package homepage override */
  homepage?: string;
  /** Package author override */
  author?: PersonConfig;
  /** Package license override */
  license?: string;
  /** Package keywords */
  keywords?: string[];
  /** Poetry configuration */
  poetry?: {
    /** Poetry package name */
    name?: string;
    /** Include/exclude patterns */
    include?: string[];
    exclude?: string[];
  };
}

/**
 * Java target configuration
 */
interface JavaConfig {
  /** Java package name */
  package?: string;
  /** Maven configuration */
  maven?: {
    /** Maven group ID */
    groupId?: string;
    /** Maven artifact ID */
    artifactId?: string;
    /** Maven version override */
    version?: string;
    /** Package description override */
    description?: string;
    /** Package URL */
    url?: string;
    /** Developer information */
    developers?: Array<{
      name?: string;
      email?: string;
      organization?: string;
      url?: string;
    }>;
    /** SCM information */
    scm?: {
      connection?: string;
      developerConnection?: string;
      url?: string;
    };
    /** License information */
    licenses?: Array<{
      name?: string;
      url?: string;
      distribution?: string;
    }>;
  };
}

/**
 * .NET target configuration
 */
interface DotNetConfig {
  /** .NET namespace */
  namespace?: string;
  /** NuGet package ID */
  packageId?: string;
  /** Package title */
  title?: string;
  /** Package description override */
  description?: string;
  /** Package version override */
  version?: string;
  /** Package authors */
  authors?: string[];
  /** Company name */
  company?: string;
  /** Product name */
  product?: string;
  /** Copyright notice */
  copyright?: string;
  /** Package icon URL */
  iconUrl?: string;
  /** Package project URL */
  projectUrl?: string;
  /** Package license URL */
  licenseUrl?: string;
  /** Package tags */
  tags?: string[];
  /** Strong naming configuration */
  strongNaming?: {
    /** Whether to sign assembly */
    enabled?: boolean;
    /** Key file path */
    keyFile?: string;
  };
  /** XML documentation */
  xmlDoc?: boolean;
  /** Version suffix */
  versionSuffix?: string;
}

/**
 * Go target configuration
 */
interface GoConfig {
  /** Go module name */
  moduleName?: string;
  /** Go package name */
  packageName?: string;
  /** Package description override */
  description?: string;
  /** Package version override */
  version?: string;
  /** Git tag prefix */
  gitTagPrefix?: string;
  /** Go version constraint */
  goVersion?: string;
  /** Package import path */
  importPath?: string;
}

/**
 * Structure of jsii module package.json
 */
interface PackageJson {
  /** Package name */
  name: string;
  /** Package version */
  version: string;
  /** Package description */
  description?: string;
  /** Main entry point */
  main?: string;
  /** TypeScript definitions */
  types?: string;
  /** Package author */
  author?: string | PersonConfig;
  /** Package license */
  license?: string;
  /** Package homepage */
  homepage?: string;
  /** Package repository */
  repository?: string | RepositoryConfig;
  /** Package keywords */
  keywords?: string[];
  /** Runtime dependencies */
  dependencies?: { [name: string]: string };
  /** Development dependencies */
  devDependencies?: { [name: string]: string };
  /** Peer dependencies */
  peerDependencies?: { [name: string]: string };
  /** Bundle dependencies */
  bundledDependencies?: string[];
  /** NPM scripts */
  scripts?: { [name: string]: string };
  /** Package bin commands */
  bin?: string | { [name: string]: string };
  /** Files to include in package */
  files?: string[];
  /** Node.js engine requirements */
  engines?: { [engine: string]: string };
  /** Package exports */
  exports?: any;
  /** ESM type */
  type?: 'module' | 'commonjs';
  /** jsii configuration */
  jsii?: Config;
  /** Additional package.json fields */
  [key: string]: any;
}

/**
 * Additional configuration metadata
 */
interface ConfigMetadata {
  /** jsii compiler version */
  jsiiVersion?: string;
  /** Assembly fingerprint */
  fingerprint?: string;
  /** Assembly compression */
  compression?: {
    /** Enable compression */
    enabled?: boolean;
    /** Compression level */
    level?: number;
  };
  /** Documentation configuration */
  docs?: {
    /** Documentation format */
    format?: 'markdown' | 'restructured-text' | 'html';
    /** Custom documentation metadata */
    [key: string]: any;
  };
  /** Code examples configuration */
  examples?: {
    /** Example source directories */
    sourceDirs?: string[];
    /** Example cache directory */
    cacheDir?: string;
    /** Whether to validate examples */
    validate?: boolean;
  };
}

/**
 * Validation configuration options
 */
interface ValidationConfig {
  /** Whether to validate assembly schema */
  assembly?: boolean;
  /** Whether to validate TypeScript types */
  types?: boolean;
  /** Whether to validate documentation */
  docs?: boolean;
  /** Custom validation rules */
  rules?: {
    [ruleName: string]: boolean | any;
  };
}

/**
 * Interactive prompting for configuration values
 * @param questions Array of prompt questions
 * @returns Promise resolving to user answers
 */
function prompt(questions: PromptQuestion[]): Promise<{ [key: string]: any }>;

/**
 * Prompt question definition
 */
interface PromptQuestion {
  /** Question type */
  type: 'input' | 'confirm' | 'list' | 'checkbox' | 'password';
  /** Question name/key */
  name: string;
  /** Question message */
  message: string;
  /** Default value */
  default?: any;
  /** Available choices for list/checkbox */
  choices?: Array<string | { name: string; value: any }>;
  /** Validation function */
  validate?: (input: any) => boolean | string;
  /** When to show this question */
  when?: (answers: any) => boolean;
  /** Transform function for answer */
  filter?: (input: any) => any;
}

/**
 * Configuration wizard that walks through jsii setup
 * @param packageJsonPath Path to package.json file
 * @param options Wizard options
 */
function configurationWizard(
  packageJsonPath: string,
  options?: {
    /** Skip existing configuration */
    skipExisting?: boolean;
    /** Force overwrite existing settings */
    force?: boolean;
    /** Interactive mode */
    interactive?: boolean;
  }
): Promise<void>;

/**
 * Validate configuration values
 * @param config Configuration to validate
 * @returns Validation result
 */
function validateConfiguration(config: Config): {
  valid: boolean;
  errors?: Array<{
    path: string;
    message: string;
  }>;
  warnings?: Array<{
    path: string;
    message: string;
  }>;
};

/**
 * Promise-based file reading utility
 * @param filePath Path to file to read
 * @returns Promise resolving to file contents
 */
function readFilePromise(filePath: string): Promise<string>;

/**
 * Write package.json with jsii configuration
 * @param filePath Path to package.json
 * @param packageJson Package.json content with jsii config
 * @param options Write options
 */
function writePackageJson(
  filePath: string, 
  packageJson: PackageJson,
  options?: {
    /** Indentation spaces */
    indent?: number;
    /** Sort keys alphabetically */
    sortKeys?: boolean;
  }
): Promise<void>;

/**
 * Validate package.json structure
 * @param packageJson Package.json content
 * @returns Validation result
 */
function validatePackageJson(packageJson: any): {
  valid: boolean;
  errors?: string[];
  warnings?: string[];
};

/**
 * Merge jsii configuration into existing package.json
 * @param existingPackageJson Current package.json content
 * @param jsiiConfig New jsii configuration
 * @returns Merged package.json
 */
function mergeJsiiConfig(
  existingPackageJson: PackageJson,
  jsiiConfig: Config
): PackageJson;

/**
 * Load existing jsii configuration from package.json
 * @param packageJsonPath Path to package.json
 * @returns Existing jsii configuration or undefined
 */
function loadExistingConfig(packageJsonPath: string): Promise<Config | undefined>;

/**
 * Create default jsii configuration
 * @param packageJson Current package.json content
 * @returns Default jsii configuration
 */
function createDefaultConfig(packageJson: PackageJson): Config;

/**
 * Validate target configuration
 * @param target Target name
 * @param config Target configuration
 * @returns Validation result
 */
function validateTargetConfig(
  target: string, 
  config: any
): {
  valid: boolean;
  errors?: string[];
  warnings?: string[];
};

/**
 * Get available target languages
 * @returns Array of supported target language names
 */
function getAvailableTargets(): string[];

/**
 * Get default configuration for target language
 * @param target Target language name
 * @param packageJson Current package.json content
 * @returns Default target configuration
 */
function getDefaultTargetConfig(target: string, packageJson: PackageJson): any;

/**
 * Normalize target configuration
 * @param target Target name
 * @param config Raw target configuration
 * @returns Normalized configuration
 */
function normalizeTargetConfig(target: string, config: any): any;

/**
 * Check if target is supported
 * @param target Target name to check
 * @returns Whether target is supported
 */
function isTargetSupported(target: string): boolean;

/**
 * Configuration wizard step
 */
interface WizardStep {
  /** Step identifier */
  id: string;
  /** Step title */
  title: string;
  /** Step description */
  description?: string;
  /** Step questions */
  questions: PromptQuestion[];
  /** Step completion check */
  isComplete?: (answers: any) => boolean;
}

/**
 * Configuration template
 */
interface ConfigTemplate {
  /** Template name */
  name: string;
  /** Template description */
  description: string;
  /** Template configuration */
  config: Partial<Config>;
  /** Template package.json changes */
  packageJson?: Partial<PackageJson>;
}

/**
 * Available configuration templates
 */
const CONFIG_TEMPLATES: readonly ConfigTemplate[];

// Run interactive configuration
import jsiiConfig from 'jsii-config';

// Interactive setup
await jsiiConfig();

// Programmatic configuration
import { configurationWizard, validateConfiguration } from 'jsii-config';

const config: Config = {
  targets: {
    python: {
      distName: 'my-awesome-library',
      module: 'my_awesome_library',
      classifiers: [
        'Development Status :: 5 - Production/Stable',
        'Programming Language :: Python :: 3.8',
        'Programming Language :: Python :: 3.9'
      ]
    },
    java: {
      package: 'com.example.mylib',
      maven: {
        groupId: 'com.example',
        artifactId: 'my-library'
      }
    },
    dotnet: {
      namespace: 'MyCompany.MyLibrary',
      packageId: 'MyCompany.MyLibrary'
    }
  },
  metadata: {
    jsiiVersion: '^5.0.0',
    docs: {
      format: 'markdown'
    }
  }
};

const validation = validateConfiguration(config);
if (validation.valid) {
  console.log('Configuration is valid');
} else {
  console.error('Validation errors:', validation.errors);
}

// Load and modify existing configuration
import { loadExistingConfig, mergeJsiiConfig } from 'jsii-config';

const existing = await loadExistingConfig('./package.json');
const updated = mergeJsiiConfig(packageJson, {
  targets: {
    go: {
      moduleName: 'github.com/example/my-library-go'
    }
  }
});