synthia-shared/dist/index.d.ts

Synthia Engine Shared - 共享工具库和核心优化器

import { Command } from 'commander';

/**
 * Synthia 插件系统核心接口
 * 参考 Rust Cargo 插件设计，支持动态注册命令
 */
/**
 * 插件日志接口
 */
interface PluginLogger {
    info: (message: string, ...args: any[]) => void;
    warn: (message: string, ...args: any[]) => void;
    error: (message: string, ...args: any[]) => void;
    debug: (message: string, ...args: any[]) => void;
    success: (message: string, ...args: any[]) => void;
}
/**
 * 插件文件系统接口
 */
interface PluginFileSystem {
    readFile: (filePath: string, encoding?: string) => Promise<string>;
    writeFile: (filePath: string, content: string, encoding?: string) => Promise<void>;
    exists: (path: string) => Promise<boolean>;
    mkdir: (path: string, recursive?: boolean) => Promise<void>;
    readdir: (path: string) => Promise<string[]>;
    remove: (path: string) => Promise<void>;
    copy: (src: string, dest: string) => Promise<void>;
    move: (src: string, dest: string) => Promise<void>;
}
/**
 * 插件 HTTP 客户端接口
 */
interface PluginHttpClient {
    get: (url: string) => Promise<any>;
    post: (url: string, data?: any) => Promise<any>;
    put: (url: string, data?: any) => Promise<any>;
    delete: (url: string) => Promise<any>;
}
/**
 * 插件缓存接口
 */
interface PluginCache {
    set: (key: string, value: any) => Promise<void>;
    get: (key: string) => Promise<any>;
    delete: (key: string) => Promise<void>;
    clear: () => Promise<void>;
    has: (key: string) => Promise<boolean>;
}
/**
 * 插件 API 接口
 */
interface PluginAPI {
    /** 注册命令 */
    registerCommand: (command: PluginCommand) => void;
    /** 注册钩子 */
    registerHook: (hookName: string, hook: Function) => void;
    /** JSON 参数校验 */
    validateJSON: (schema: any, data: any) => {
        valid: boolean;
        errors: string[];
    };
    /** 日志记录器 */
    logger: PluginLogger;
    /** 文件系统操作 */
    fs: PluginFileSystem;
    /** HTTP 客户端 */
    http: PluginHttpClient;
    /** 缓存操作 */
    cache: PluginCache;
}
/**
 * 插件选项接口
 */
interface PluginOptions {
    /** 插件配置 */
    config: Record<string, any>;
    /** 工程信息 */
    project: {
        name: string;
        version: string;
        root: string;
        description?: string;
    };
    /** 全局选项 */
    globalOptions: Record<string, any>;
}
/**
 * 插件函数类型
 */
type PluginFunction = (api: PluginAPI, options: PluginOptions) => Promise<void> | void;
/**
 * 插件定义接口
 */
interface PluginDefinition {
    /** 插件名称 */
    name: string;
    /** 插件版本 */
    version: string;
    /** 插件描述 */
    description: string;
    /** 插件函数 */
    plugin: PluginFunction;
}
/**
 * 插件元数据（向后兼容）
 */
interface PluginMetadata {
    /** 插件名称 */
    name: string;
    /** 插件版本 */
    version: string;
    /** 插件描述 */
    description: string;
    /** 插件作者 */
    author?: string;
    /** 插件许可证 */
    license?: string;
    /** 插件主页 */
    homepage?: string;
    /** 插件仓库 */
    repository?: string;
    /** 插件关键词 */
    keywords?: string[];
    /** 插件依赖的 Synthia 版本 */
    synthiaVersion?: string;
    /** 插件兼容的平台 */
    platforms?: string[];
}
/**
 * 插件命令定义
 */
interface PluginCommand {
    /** 命令名称 */
    name: string;
    /** 命令描述 */
    description: string;
    /** 命令别名 */
    aliases?: string[];
    /** 命令选项 */
    options?: PluginCommandOption[];
    /** 命令参数 */
    arguments?: PluginCommandArgument[];
    /** 命令执行函数 */
    action: (options: any, ...args: any[]) => Promise<void> | void;
    /** 命令帮助信息 */
    help?: string;
    /** 命令示例 */
    examples?: string[];
}
/**
 * 插件命令选项
 */
interface PluginCommandOption {
    /** 选项标识符 */
    flags: string;
    /** 选项描述 */
    description: string;
    /** 默认值 */
    defaultValue?: any;
    /** 是否必需 */
    required?: boolean;
    /** 选项类型 */
    type?: 'string' | 'number' | 'boolean' | 'array';
    /** 选项验证函数 */
    validator?: (value: any) => boolean | string;
}
/**
 * 插件命令参数
 */
interface PluginCommandArgument {
    /** 参数名称 */
    name: string;
    /** 参数描述 */
    description: string;
    /** 是否必需 */
    required?: boolean;
    /** 参数类型 */
    type?: 'string' | 'number' | 'boolean' | 'array';
    /** 参数验证函数 */
    validator?: (value: any) => boolean | string;
}
/**
 * 插件上下文
 */
interface PluginContext {
    /** 项目根目录 */
    projectRoot: string;
    /** 配置文件路径 */
    configPath?: string;
    /** 插件配置 */
    pluginConfig?: Record<string, any>;
    /** 全局选项 */
    globalOptions: Record<string, any>;
    /** 日志记录器 */
    logger: PluginLogger;
    /** 文件系统操作 */
    fs: PluginFileSystem;
    /** 网络请求 */
    http: PluginHttpClient;
    /** 缓存操作 */
    cache: PluginCache;
}
/**
 * 开发模式上下文
 */
interface DevContext {
    /** 项目信息 */
    project: {
        name: string;
        version: string;
        root: string;
    };
    /** 开发服务器配置 */
    devServer: {
        port: number;
        host: string;
        https: boolean;
        open: boolean;
        hot: boolean;
    };
    /** 命令行选项 */
    options: {
        cache?: boolean;
        port?: number;
        host?: string;
        open?: boolean;
        https?: boolean;
        [key: string]: any;
    };
    /** 缓存接口 */
    cache: PluginCache;
    /** 日志记录器 */
    logger: PluginLogger;
}
/**
 * 构建上下文
 */
interface BuildContext {
    /** 项目信息 */
    project: {
        name: string;
        version: string;
        root: string;
        sourceFiles: string[];
    };
    /** 构建配置 */
    build: {
        platform: string;
        target: string;
        format: string;
        outDir: string;
        assetsDir: string;
        minify: boolean;
        sourcemap: boolean;
        output?: any;
        stats?: any;
    };
    /** 命令行选项 */
    options: {
        cache?: boolean;
        watch?: boolean;
        minify?: boolean;
        sourcemap?: boolean;
        [key: string]: any;
    };
    /** 缓存接口 */
    cache: PluginCache;
    /** 日志记录器 */
    logger: PluginLogger;
}
/**
 * 清理上下文
 */
interface CleanContext {
    /** 项目信息 */
    project: {
        name: string;
        version: string;
        root: string;
    };
    /** 清理目标 */
    targets: string[];
    /** 命令行选项 */
    options: {
        cache?: boolean;
        all?: boolean;
        [key: string]: any;
    };
    /** 缓存接口 */
    cache: PluginCache;
    /** 日志记录器 */
    logger: PluginLogger;
}
/**
 * 插件生命周期钩子
 */
interface PluginHooks {
    /** 插件安装前 */
    beforeInstall?: () => Promise<void>;
    /** 插件安装后 */
    afterInstall?: () => Promise<void>;
    /** 插件卸载前 */
    beforeUninstall?: () => Promise<void>;
    /** 插件卸载后 */
    afterUninstall?: () => Promise<void>;
    /** 插件激活前 */
    beforeActivate?: () => Promise<void>;
    /** 插件激活后 */
    afterActivate?: () => Promise<void>;
    /** 插件停用前 */
    beforeDeactivate?: () => Promise<void>;
    /** 插件停用后 */
    afterDeactivate?: () => Promise<void>;
    /** 开发模式启动前 */
    beforeDev?: (context: DevContext) => Promise<void>;
    /** 开发模式启动后 */
    afterDev?: (context: DevContext) => Promise<void>;
    /** 构建前 */
    beforeBuild?: (context: BuildContext) => Promise<void>;
    /** 构建后 */
    afterBuild?: (context: BuildContext) => Promise<void>;
    /** 清理前 */
    beforeClean?: (context: CleanContext) => Promise<void>;
    /** 清理后 */
    afterClean?: (context: CleanContext) => Promise<void>;
}
/**
 * 插件主接口
 */
interface SynthiaPlugin {
    /** 插件元数据 */
    metadata: PluginMetadata;
    /** 插件命令列表 */
    commands: PluginCommand[];
    /** 插件生命周期钩子 */
    hooks?: PluginHooks;
    /** 插件初始化函数 */
    initialize?: (context: PluginContext) => Promise<void>;
    /** 插件清理函数 */
    cleanup?: () => Promise<void>;
}
/**
 * 插件注册器
 */
interface PluginRegistry {
    /** 注册插件 */
    register: (plugin: SynthiaPlugin) => Promise<void>;
    /** 注销插件 */
    unregister: (pluginName: string) => Promise<void>;
    /** 获取插件 */
    get: (pluginName: string) => SynthiaPlugin | undefined;
    /** 获取所有插件 */
    getAll: () => SynthiaPlugin[];
    /** 检查插件是否存在 */
    has: (pluginName: string) => boolean;
    /** 获取插件命令 */
    getCommands: () => PluginCommand[];
}
/**
 * 插件管理器
 */
interface PluginManager {
    /** 插件注册器 */
    registry: PluginRegistry;
    /** 加载插件 */
    loadPlugin: (pluginPath: string) => Promise<SynthiaPlugin>;
    /** 卸载插件 */
    unloadPlugin: (pluginName: string) => Promise<void>;
    /** 发现插件 */
    discoverPlugins: (searchPaths: string[]) => Promise<string[]>;
    /** 安装插件 */
    installPlugin: (pluginName: string, version?: string) => Promise<void>;
    /** 卸载插件 */
    uninstallPlugin: (pluginName: string) => Promise<void>;
    /** 更新插件 */
    updatePlugin: (pluginName: string, version?: string) => Promise<void>;
    /** 列出已安装的插件 */
    listPlugins: () => Promise<PluginMetadata[]>;
    /** 检查插件状态 */
    checkPluginStatus: (pluginName: string) => Promise<'installed' | 'outdated' | 'missing'>;
}
/**
 * 插件系统配置
 */
interface PluginSystemConfig {
    /** 插件搜索路径 */
    searchPaths: string[];
    /** 插件安装目录 */
    installDir: string;
    /** 插件缓存目录 */
    cacheDir: string;
    /** 是否启用插件 */
    enabled: boolean;
    /** 允许的插件列表 */
    allowedPlugins?: string[];
    /** 禁止的插件列表 */
    blockedPlugins?: string[];
    /** 插件超时时间 */
    timeout: number;
    /** 插件沙箱模式 */
    sandbox: boolean;
}
/**
 * 插件错误类型
 */
declare class PluginError extends Error {
    pluginName?: string | undefined;
    errorCode?: string | undefined;
    constructor(message: string, pluginName?: string | undefined, errorCode?: string | undefined);
}
/**
 * 插件验证结果
 */
interface PluginValidationResult {
    /** 是否有效 */
    valid: boolean;
    /** 错误信息 */
    errors: string[];
    /** 警告信息 */
    warnings: string[];
}
/**
 * 插件验证器
 */
interface PluginValidator {
    /** 验证插件 */
    validate: (plugin: SynthiaPlugin) => PluginValidationResult;
    /** 验证插件元数据 */
    validateMetadata: (metadata: PluginMetadata) => PluginValidationResult;
    /** 验证插件命令 */
    validateCommands: (commands: PluginCommand[]) => PluginValidationResult;
}

/**
 * Synthia Engine 日志系统
 * 提供统一的日志记录功能，支持自定义 logger 实现
 */
type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
/**
 * 日志记录器接口
 */
interface Logger {
    /** 调试级别日志 */
    debug: (message: string, ...args: any[]) => void;
    /** 信息级别日志 */
    info: (message: string, ...args: any[]) => void;
    /** 警告级别日志 */
    warn: (message: string, ...args: any[]) => void;
    /** 错误级别日志 */
    error: (message: string, ...args: any[]) => void;
    /** 成功级别日志 */
    success: (message: string, ...args: any[]) => void;
}
/**
 * 日志配置接口
 */
interface LoggerConfig {
    /** 日志级别 */
    level?: LogLevel;
    /** 是否启用颜色输出 */
    color?: boolean;
    /** 是否显示时间戳 */
    timestamp?: boolean;
    /** 是否显示日志级别 */
    showLevel?: boolean;
    /** 自定义 logger 实现 */
    custom?: Logger;
    /** 文件输出配置 */
    file?: {
        /** 是否启用文件输出 */
        enabled?: boolean;
        /** 日志文件路径 */
        path?: string;
        /** 日志文件目录 */
        dir?: string;
        /** 是否按级别分离文件 */
        separateByLevel?: boolean;
        /** 文件最大大小 (字节) */
        maxSize?: number;
        /** 最大文件数量 */
        maxFiles?: number;
    };
}
/**
 * 创建日志记录器
 */
declare function createLogger(config?: LoggerConfig): Logger;
/**
 * 默认日志记录器实例
 */
declare const defaultLogger: Logger;
/**
 * 日志记录器工厂
 */
declare class LoggerFactory {
    private static instance;
    private loggers;
    static getInstance(): LoggerFactory;
    /**
     * 创建或获取日志记录器
     */
    getLogger(name?: string, config?: LoggerConfig): Logger;
    /**
     * 设置日志记录器
     */
    setLogger(name: string, logger: Logger): void;
    /**
     * 移除日志记录器
     */
    removeLogger(name: string): void;
    /**
     * 获取所有日志记录器名称
     */
    getLoggerNames(): string[];
    /**
     * 清空所有日志记录器
     */
    clear(): void;
}
/**
 * 全局日志记录器工厂实例
 */
declare const loggerFactory: LoggerFactory;
/**
 * 便捷的日志记录器获取函数
 */
declare function getLogger(name?: string, config?: LoggerConfig): Logger;
/**
 * 便捷的日志记录器设置函数
 */
declare function setLogger(name: string, logger: Logger): void;
/**
 * 验证 logger 是否实现了必需的接口
 */
declare function validateLogger(logger: any): logger is Logger;
/**
 * 创建静默日志记录器
 */
declare function createSilentLogger(): Logger;
/**
 * 创建控制台日志记录器（简化版）
 */
declare function createConsoleLogger(level?: LogLevel): Logger;

/**
 * Synthia Engine 配置系统
 * 提供统一的配置管理和验证功能
 */

/**
 * 插件配置项
 */
interface PluginConfigItem {
    /** 插件名称或路径 */
    name: string;
    /** 插件函数 */
    plugin?: PluginFunction;
}
/**
 * 插件配置
 */
type PluginConfig = Array<PluginFunction | PluginConfigItem>;
/**
 * 主配置接口
 */
interface SynthiaConfig {
    /** 项目名称 */
    name: string;
    /** 项目版本 */
    version: string;
    /** 项目描述 */
    description?: string;
    /** 插件配置 */
    plugins?: PluginConfig;
    /** 日志配置 */
    logger?: LoggerConfig;
}
/**
 * 配置验证结果
 */
interface ConfigValidationResult {
    /** 是否有效 */
    valid: boolean;
    /** 错误信息 */
    errors: string[];
    /** 警告信息 */
    warnings: string[];
    /** 建议信息 */
    suggestions: string[];
}
/**
 * 配置加载选项
 */
interface ConfigLoadOptions {
    /** 配置文件路径 */
    configFile?: string;
    /** 环境变量前缀 */
    envPrefix?: string;
    /** 是否合并默认配置 */
    mergeDefaults?: boolean;
    /** 是否验证配置 */
    validate?: boolean;
    /** 是否解析环境变量 */
    resolveEnv?: boolean;
}
/**
 * 默认配置
 */
declare const DEFAULT_CONFIG: SynthiaConfig;
/**
 * 定义 Synthia Engine 配置
 */
declare function defineConfig(config: SynthiaConfig): SynthiaConfig;

interface BuildStats {
    startTime: number;
    endTime: number;
    duration: number;
    bundleSize: number;
    chunkCount: number;
    moduleCount: number;
    optimizationSuggestions: string[];
}
interface CacheInfo {
    hash: string;
    size: number;
    lastModified: number;
    dependencies: string[];
}
interface OptimizationResult {
    /** 是否成功 */
    success: boolean;
    /** 优化建议 */
    suggestions: string[];
    /** 错误信息 */
    errors?: string[];
}

/**
 * Synthia Engine 配置加载器 - 简化版
 * 提供基本的配置文件加载和解析功能
 */

/**
 * 简化的配置加载器类
 */
declare class ConfigLoader {
    private rootDir;
    private configCache;
    constructor(rootDir?: string);
    /**
     * 加载配置文件
     */
    loadConfig(options?: ConfigLoadOptions): Promise<SynthiaConfig>;
    /**
     * 查找配置文件
     */
    private findConfigFile;
    /**
     * 加载配置文件内容
     */
    private loadConfigFile;
    /**
     * 清除配置缓存
     */
    clearCache(): void;
    /**
     * 获取缓存大小
     */
    getCacheSize(): number;
}

/**
 * Synthia Engine 配置验证器 - 简化版
 * 提供基本的配置验证功能
 */

/**
 * 简化的配置验证器类
 */
declare class ConfigValidator {
    private errors;
    private warnings;
    private suggestions;
    /**
     * 验证配置
     */
    validate(config: SynthiaConfig): ConfigValidationResult;
    /**
     * 验证基本配置
     */
    private validateBasicConfig;
    /**
     * 验证插件配置
     */
    private validatePluginConfig;
    /**
     * 验证日志配置
     */
    private validateLoggerConfig;
    /**
     * 重置验证状态
     */
    private reset;
}
/**
 * 快速验证配置
 */
declare function quickValidate(config: SynthiaConfig): boolean;

/**
 * Synthia 插件注册器实现
 * 负责插件的注册、管理和命令注册
 */

/**
 * 插件注册器实现
 */
declare class DefaultPluginRegistry implements PluginRegistry {
    private validator?;
    private plugins;
    private commands;
    private commandToPlugin;
    constructor(validator?: PluginValidator | undefined);
    /**
     * 注册插件
     */
    register(plugin: SynthiaPlugin): Promise<void>;
    /**
     * 注销插件
     */
    unregister(pluginName: string): Promise<void>;
    /**
     * 获取插件
     */
    get(pluginName: string): SynthiaPlugin | undefined;
    /**
     * 获取所有插件
     */
    getAll(): SynthiaPlugin[];
    /**
     * 检查插件是否存在
     */
    has(pluginName: string): boolean;
    /**
     * 获取插件命令
     */
    getCommands(): PluginCommand[];
    /**
     * 注册插件命令
     */
    private registerCommand;
    /**
     * 注销插件命令
     */
    private unregisterCommand;
    /**
     * 获取命令所属的插件
     */
    getCommandPlugin(commandName: string): string | undefined;
    /**
     * 获取插件的命令列表
     */
    getPluginCommands(pluginName: string): PluginCommand[];
}
/**
 * 插件验证器实现
 */
declare class DefaultPluginValidator implements PluginValidator {
    /**
     * 验证插件
     */
    validate(plugin: SynthiaPlugin): PluginValidationResult;
    /**
     * 验证插件元数据
     */
    validateMetadata(metadata: any): PluginValidationResult;
    /**
     * 验证插件命令
     */
    validateCommands(commands: any[]): PluginValidationResult;
}

/**
 * Synthia 插件管理器实现
 * 负责插件的加载、安装、卸载和管理
 */

/**
 * 插件管理器实现
 */
declare class DefaultPluginManager implements PluginManager {
    registry: PluginRegistry;
    private config;
    private context;
    constructor(config?: Partial<PluginSystemConfig>);
    /**
     * 加载插件
     */
    loadPlugin(pluginPath: string): Promise<SynthiaPlugin>;
    /**
     * 卸载插件
     */
    unloadPlugin(pluginName: string): Promise<void>;
    /**
     * 发现插件
     */
    discoverPlugins(searchPaths: string[]): Promise<string[]>;
    /**
     * 安装插件
     */
    installPlugin(pluginName: string, version?: string): Promise<void>;
    /**
     * 卸载插件
     */
    uninstallPlugin(pluginName: string): Promise<void>;
    /**
     * 更新插件
     */
    updatePlugin(pluginName: string, version?: string): Promise<void>;
    /**
     * 列出已安装的插件
     */
    listPlugins(): Promise<PluginMetadata[]>;
    /**
     * 检查插件状态
     */
    checkPluginStatus(pluginName: string): Promise<'installed' | 'outdated' | 'missing'>;
    /**
     * 从 npm 安装插件
     */
    private installFromNpm;
    /**
     * 合并配置
     */
    private mergeConfig;
    /**
     * 创建插件上下文
     */
    private createContext;
    /**
     * 创建日志记录器
     */
    private createLogger;
    /**
     * 创建文件系统操作
     */
    private createFileSystem;
    /**
     * 创建 HTTP 客户端
     */
    private createHttpClient;
    /**
     * 创建缓存操作
     */
    private createCache;
}

/**
 * Synthia 插件加载器实现
 * 负责插件的动态加载和命令集成
 */

/**
 * 插件加载器类
 */
declare class PluginLoader {
    private loadedPlugins;
    private commander;
    private logger;
    private hooks;
    constructor(commander: Command, logger?: Logger);
    /**
     * 从配置加载所有插件
     */
    loadPluginsFromConfig(config: any): Promise<void>;
    /**
     * 从配置项加载单个插件
     */
    private loadPluginFromConfig;
    /**
     * 加载函数式插件
     */
    private loadFunctionPlugin;
    /**
     * 创建插件 API
     */
    private createPluginAPI;
    /**
     * 注册单个命令
     */
    private registerCommand;
    /**
     * 获取已加载的插件列表
     */
    getLoadedPlugins(): PluginFunction[];
    /**
     * 执行钩子
     */
    executeHooks(hookName: string, context?: any): Promise<void>;
}
declare const globalPluginLoader: PluginLoader;

export { type BuildContext, type BuildStats, type CacheInfo, type CleanContext, type ConfigLoadOptions, ConfigLoader, type ConfigValidationResult, ConfigValidator, DEFAULT_CONFIG, DefaultPluginManager, DefaultPluginRegistry, DefaultPluginValidator, type DevContext, type LogLevel, type Logger, type LoggerConfig, LoggerFactory, type OptimizationResult, type PluginAPI, type PluginCache, type PluginCommand, type PluginCommandArgument, type PluginCommandOption, type PluginConfig, type PluginContext, type PluginDefinition, PluginError, type PluginFileSystem, type PluginFunction, type PluginHooks, type PluginHttpClient, PluginLoader, type PluginLogger, type PluginManager, type PluginMetadata, type PluginOptions, type PluginRegistry, type PluginSystemConfig, type PluginValidationResult, type PluginValidator, type SynthiaConfig, type SynthiaPlugin, createConsoleLogger, createLogger, createSilentLogger, defaultLogger, defineConfig, getLogger, globalPluginLoader, loggerFactory, quickValidate, setLogger, validateLogger };