Type Definitions

interface UserConfig {
  /** Build output directory (default: 'build') */
  outputDir?: string;
  /** Public path for assets (default: '/') */
  publicPath?: string;
  /** Development public path override */
  devPublicPath?: string;
  /** Enable filename hashing for cache busting */
  hash?: boolean | string;
  /** Code minification settings */
  minify?: boolean | MinifyOptions;
  /** Source map generation configuration */
  sourceMap?: boolean | 'inline' | 'hidden' | 'nosources-cheap-source-map';
  /** Cross-origin loading for dynamic imports */
  crossOriginLoading?: 'anonymous' | 'use-credentials' | false;
  /** Output filename pattern for built bundles */
  filename?: string;
  
  /** Module path aliases for import resolution */
  alias?: Record<string, string>;
  /** External dependencies to exclude from bundle */
  externals?: Record<string, string> | string[];
  /** Dependencies to compile instead of treating as external */
  compileDependencies?: string[];
  /** Global constant definitions for DefinePlugin */
  define?: Record<string, any>;
  /** Legacy browser polyfill configuration */
  polyfill?: boolean | 'entry' | 'usage';
  
  /** Development server proxy configuration */
  proxy?: Record<string, ProxyConfig>;
  /** Mock service configuration */
  mock?: MockConfig | boolean;
  
  /** CSS Modules configuration */
  cssModules?: boolean | CSSModulesConfig;
  /** PostCSS configuration */
  postcss?: PostCSSConfig;
  
  /** Routing configuration */
  routes?: RoutesConfig;
  /** Enable server-side rendering */
  ssr?: boolean;
  /** Enable static site generation */
  ssg?: boolean;
  /** Data loading capabilities */
  dataLoader?: boolean;
  /** HTML generation configuration */
  htmlGenerating?: HtmlGeneratingConfig;
  
  /** Server-side configuration */
  server?: ServerConfig;
  /** Plugin configuration */
  plugins?: Plugin[];
  
  /** Build optimization settings */
  optimization?: OptimizationConfig;
  /** Code splitting configuration */
  codeSplitting?: boolean | 'page-only' | 'depot-granular';
  
  /** TypeScript type checking */
  tsChecker?: boolean;
  /** ESLint integration */
  eslint?: boolean | ESLintConfig;
  /** Console log levels to drop in production */
  dropLogLevel?: DropType[];
  /** Bundle analyzer integration */
  analyzer?: boolean;
  /** Enable Rust-based build optimization */
  speedup?: boolean;
  
  /** Experimental features */
  experimental?: ExperimentalConfig;
  /** Code transformation rules */
  transform?: TransformConfig;
  /** Syntax feature flags */
  syntaxFeatures?: SyntaxFeatures;
  /** Feature polyfill configuration */
  featurePolyfill?: PolyfillConfig;
  /** Direct webpack configuration modification (not recommended) */
  webpack?: (config: WebpackConfig, { webpack }: { webpack: any }) => WebpackConfig;
  /** Data loading configuration for SSR/SSG */
  dataLoader?: boolean | DataLoaderConfig;
}

interface MinifyOptions {
  type: 'terser' | 'swc';
  options?: MinimizerOptions<Record<string, any>>;
}

type DropType = 'trace' | 'debug' | 'log' | 'info' | 'warn' | 'error';

interface CreateServiceOptions {
  /** Project root directory path */
  rootDir: string;
  /** Command to execute */
  command: CommandName;
  /** Command-line arguments and options */
  commandArgs: CommandArgs;
}

type CommandName = 'start' | 'build' | 'test';

interface CommandArgs {
  /** Build/start target platform */
  target?: BuildTarget;
  /** Build mode */
  mode?: 'development' | 'production';
  /** Configuration file path */
  config?: string;
  /** Development server host */
  host?: string;
  /** Development server port */
  port?: number;
  /** Enable bundle analyzer */
  analyzer?: boolean;
  /** Enable HTTPS */
  https?: boolean | 'self-signed';
  /** Force cache clear */
  force?: boolean;
  /** Enable speedup mode */
  speedup?: boolean;
  /** Browser opening behavior */
  open?: boolean | string;
  /** Disable browser opening */
  'no-open'?: boolean;
  /** Disable mock service */
  'no-mock'?: boolean;
  /** List available pages */
  list?: boolean;
  /** Custom plugin */
  plugin?: string;
  /** Additional unknown options */
  [key: string]: any;
}

type BuildTarget = 
  | 'web'
  | 'weex'
  | 'ali-miniapp'
  | 'wechat-miniprogram'
  | 'bytedance-microapp'
  | 'baidu-smartprogram'
  | 'kuaishou-miniprogram';

interface ServiceInstance {
  /** Execute the service operation */
  run(): Promise<any>;
}

interface ProxyConfig {
  /** Target server URL */
  target: string;
  /** Change origin header */
  changeOrigin?: boolean;
  /** Path rewriting rules */
  pathRewrite?: Record<string, string>;
  /** Custom headers */
  headers?: Record<string, string>;
  /** WebSocket proxying */
  ws?: boolean;
  /** Secure connection */
  secure?: boolean;
  /** Log level */
  logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent';
}

interface MockConfig {
  /** Files to exclude from mocking */
  exclude?: string[];
  /** Files to include in mocking */
  include?: string[];
  /** Mock data directory */
  dir?: string;
  /** Enable/disable mock middleware */
  enable?: boolean;
}

interface CSSModulesConfig {
  /** Local class name generation pattern */
  localIdentName?: string;
  /** Hash digest method */
  hashPrefix?: string;
  /** Generate scoped name function */
  generateScopedName?: (name: string, filename: string, css: string) => string;
  /** Export globals */
  exportGlobals?: boolean;
  /** CSS Modules mode */
  mode?: 'local' | 'global' | 'pure';
}

interface PostCSSConfig {
  /** PostCSS plugins */
  plugins?: any[];
  /** PostCSS options */
  options?: Record<string, any>;
  /** Custom PostCSS config file path */
  config?: string;
}

interface RoutesConfig {
  /** Files to ignore during route generation */
  ignoreFiles?: string[];
  /** Custom route definitions */
  defineRoutes?: (defineRoute: DefineRouteFunction) => void;
  /** Route-specific configuration */
  config?: Record<string, RouteConfig>;
  /** Initial entry injection configuration */
  injectInitialEntry?: boolean | InjectInitialEntryConfig;
}

interface RouteConfig {
  /** Page title */
  title?: string;
  /** Meta tags */
  meta?: Record<string, any>;
  /** Authentication requirements */
  auth?: boolean | string[];
  /** Layout component */
  layout?: string;
  /** Route-specific data loading */
  dataLoader?: boolean;
}

interface DefineRouteFunction {
  (path: string, file: string, options?: RouteOptions): void;
}

interface RouteOptions {
  /** Index route flag */
  index?: boolean;
  /** Case-sensitive matching */
  caseSensitive?: boolean;
  /** Route ID */
  id?: string;
}

interface InjectInitialEntryConfig {
  /** Enable injection */
  enable?: boolean;
  /** Custom injection logic */
  inject?: (entry: string) => string;
}

interface ServerConfig {
  /** Enable server-side rendering */
  onDemand?: boolean;
  /** Server output format */
  format?: 'esm' | 'cjs';
  /** Server bundling configuration */
  bundle?: boolean;
  /** Files to ignore in server compilation */
  ignores?: string[];
  /** Server external dependencies */
  externals?: string[];
  /** Bundler selection for server */
  bundler?: 'webpack' | 'rspack';
  /** Custom webpack configuration for server */
  webpackConfig?: ModifyWebpackConfig;
  /** Server entry file */
  entry?: string;
  /** Server output directory */
  outputDir?: string;
}

type ModifyWebpackConfig = (config: WebpackConfig, options: WebpackConfigOptions) => WebpackConfig;

interface WebpackConfigOptions {
  /** Build context */
  context: BuildContext;
  /** Command being executed */
  command: CommandName;
  /** Task configuration */
  taskConfig: TaskConfig;
}

interface Plugin<Options = any> {
  (api: PluginAPI, options?: Options): void;
}

interface PluginAPI extends ExtendsPluginAPI {
  /** Register build hooks */
  onHook: (name: string, fn: Function) => void;
  /** Modify webpack configuration */
  modifyWebpackConfig: ModifyWebpackConfig;
  /** Add runtime options */
  addRuntimeOptions: (options: RuntimeOptions) => void;
  /** Register generator plugins */
  addPlugin: (plugin: GeneratorPlugin) => void;
  /** Add entry code */
  addEntryCode: (code: string) => void;
  /** Add entry imports */
  addEntryImport: (importDeclaration: string) => void;
}

interface ExtendsPluginAPI {
  /** Add export declarations */
  addExport: (declarationData: DeclarationData) => void;
  /** Add export type declarations */
  addExportTypes: (declarationData: DeclarationData) => void;
  /** Add runtime options */
  addRuntimeOptions: (declarationData: DeclarationData) => void;
  /** Remove runtime options */
  removeRuntimeOptions: (removeSource: string | string[]) => void;
  /** Add route types */
  addRouteTypes: (declarationData: DeclarationData) => void;
  /** Add render files */
  addRenderFile: (templateFile: string, targetFile: string) => void;
  /** Add render templates */
  addRenderTemplate: (templates: RenderTemplate[]) => void;
}

interface PluginData {
  /** Plugin name */
  name: string;
  /** Plugin setup function */
  setup: (api: PluginAPI) => void;
  /** Plugin options */
  options?: any;
}

interface AnalyzeOptions {
  /** Number of parallel analysis operations (default: 10) */
  parallel?: number;
  /** Whether to analyze relative imports (default: false) */
  analyzeRelativeImport?: boolean;
  /** Module path aliases for import resolution */
  alias?: Alias;
}

interface ScanOptions {
  /** Project root directory */
  rootDir?: string;
  /** Module path aliases */
  alias?: Alias;
  /** Existing dependency imports to merge with */
  depImports?: Record<string, DepScanData>;
  /** ESBuild plugins for custom file processing */
  plugins?: Plugin[];
  /** Patterns to exclude from scanning */
  exclude?: string[];
  /** Files to ignore during scanning */
  ignores?: string[];
}

interface DepScanData {
  /** Imported module specifiers */
  imports: Set<string>;
  /** Dynamic import specifiers */
  dynamicImports: Set<string>;
  /** Export names from the module */
  exports: Set<string>;
  /** File dependencies */
  deps: Set<string>;
  /** Whether the module has side effects */
  hasSideEffects: boolean;
}

interface FileExportOptions {
  /** File path (relative or absolute) */
  file: string;
  /** Project root directory */
  rootDir: string;
}

type Alias = Record<string, string>;
type AliasWithEmpty = Record<string, string | false>;

interface DeclarationData {
  /** Import source */
  source: string;
  /** Import specifier */
  specifier?: string;
  /** Import type */
  type?: 'default' | 'namespace' | 'named';
  /** Export name */
  exportName?: string;
  /** Type only import */
  typeOnly?: boolean;
}

interface RenderData {
  /** Template variables */
  [key: string]: any;
}

interface TemplateOptions {
  /** Template engine options */
  engine?: 'ejs' | 'handlebars';
  /** Template data */
  data?: RenderData;
  /** Template helpers */
  helpers?: Record<string, Function>;
}

type RenderTemplate = [string, string, TemplateOptions?];

interface ExtraData {
  /** Additional template data */
  [key: string]: any;
}

interface OptimizationConfig {
  /** Router optimization (remove when single route) */
  router?: boolean;
  /** Force disable router dependencies */
  disableRouter?: boolean;
  /** Package import optimization for barrel files */
  optimizePackageImport?: string[] | boolean;
}

interface SyntaxFeatures {
  /** Export default from syntax support */
  exportDefaultFrom?: boolean;
  /** Function bind operator support */
  functionBind?: boolean;
}

interface ExperimentalConfig {
  /** Experimental router features */
  router?: boolean;
  /** Experimental build features */
  build?: Record<string, any>;
  /** Experimental development features */
  dev?: Record<string, any>;
}

interface TransformConfig {
  /** File pattern to transformer mapping */
  [pattern: string]: {
    /** Loader to use */
    loader?: string;
    /** Loader options */
    options?: Record<string, any>;
  };
}

interface PolyfillConfig {
  /** Feature polyfills */
  features?: string[];
  /** Polyfill mode */
  mode?: 'usage' | 'entry';
  /** Core-js version */
  corejs?: string;
}

interface DataLoaderConfig {
  /** Custom fetcher configuration */
  fetcher?: {
    packageName: string;
    method?: string;
  };
}

interface HtmlGeneratingConfig {
  /** Generation mode */
  mode?: HtmlGeneratingMode;
  /** Custom HTML template */
  template?: string;
  /** Inject runtime configuration */
  inject?: boolean;
  /** Meta tag configuration */
  meta?: Record<string, string>;
  /** Link tag configuration */
  links?: Array<{ rel: string; href: string; [key: string]: string }>;
  /** Script tag configuration */
  scripts?: Array<{ src: string; [key: string]: string }>;
}

type HtmlGeneratingMode = 'cleanUrl' | 'compat';

interface CreateLoggerReturnType {
  /** Debug logging */
  debug: (...args: any[]) => void;
  /** Info logging */
  info: (...args: any[]) => void;
  /** Warning logging */
  warn: (...args: any[]) => void;
  /** Error logging */
  error: (...args: any[]) => void;
}

interface Urls {
  /** Local development URL */
  localUrlForTerminal: string;
  /** Local development URL for browser */
  localUrlForBrowser: string;
  /** Network URL for terminal */
  lanUrlForTerminal?: string;
  /** Network URL for browser */
  lanUrlForBrowser?: string;
}

interface WatchEvent {
  /** Event type */
  type: 'add' | 'change' | 'unlink';
  /** File path */
  file: string;
  /** Additional event data */
  data?: any;
}

interface BuildContext {
  /** Command being executed */
  command: CommandName;
  /** Command arguments */
  commandArgs: CommandArgs;
  /** Root directory */
  rootDir: string;
  /** User configuration */
  userConfig: UserConfig;
}

interface TaskConfig {
  /** Task name */
  name: string;
  /** Task configuration */
  config: any;
  /** Task context */
  context: BuildContext;
}

interface Logger {
  /** Fatal level logging */
  fatal(message: any, ...args: any[]): void;
  /** Error level logging */
  error(message: any, ...args: any[]): void;
  /** Warning level logging */
  warn(message: any, ...args: any[]): void;
  /** Standard logging */
  log(message: any, ...args: any[]): void;
  /** Info level logging */
  info(message: any, ...args: any[]): void;
  /** Start event logging */
  start(message: any, ...args: any[]): void;
  /** Success event logging */
  success(message: any, ...args: any[]): void;
  /** Ready event logging */
  ready(message: any, ...args: any[]): void;
  /** Debug level logging */
  debug(message: any, ...args: any[]): void;
  /** Trace level logging */
  trace(message: any, ...args: any[]): void;
  /** Brief error logging with debug instructions */
  briefError(message: any, ...args: any[]): void;
}

type ICELogNamespace = string;
type CreateLogger = (namespace?: ICELogNamespace) => Logger;

// Re-exported from @ice/shared-config/types
interface Config {
  /** Webpack configuration */
  webpack?: WebpackConfiguration;
  /** Build configuration */
  build?: BuildConfig;
  /** Development configuration */
  dev?: DevConfig;
}

// Re-exported from Express for mock functionality
interface Request {
  /** Request body */
  body: any;
  /** Request headers */
  headers: Record<string, string>;
  /** Request parameters */
  params: Record<string, string>;
  /** Request query */
  query: Record<string, any>;
  /** Request URL */
  url: string;
  /** Request method */
  method: string;
}

interface Response {
  /** Send response */
  send: (data: any) => void;
  /** Send JSON response */
  json: (data: any) => void;
  /** Set response status */
  status: (code: number) => Response;
  /** Set response headers */
  set: (headers: Record<string, string>) => Response;
}