@vureact/compiler-core 1.0.0

package/lib/compiler-core.d.cts

@@ -0,0 +1,1344 @@
+import { GeneratorOptions as GeneratorOptions$1 } from '@babel/generator';
+import * as t from '@babel/types';
+import { Expression, ArrayExpression, JSXIdentifier } from '@babel/types';
+import { ParseResult as ParseResult$1 } from '@babel/parser';
+import { RootNode, SourceLocation } from '@vue/compiler-core';
+import { SFCTemplateBlock, SFCScriptBlock, SFCStyleBlock } from '@vue/compiler-sfc';
+import { Options } from 'prettier';
+
+type LangType = 'js' | 'jsx' | 'ts' | 'tsx';
+
+type ReactiveTypes = 'ref' | 'reactive' | 'indirect' | 'none';
+
+interface ICompilationContext {
+    fileId: string;
+    source: string;
+    compName: string;
+    filename: string;
+    imports: Map<string, ImportItem[]>;
+    cssVars: string[];
+    inputType: FileInputType;
+    /** 函数组件的 prop 参数名 */
+    propField: string;
+    /** 是否使用了路由 */
+    route?: boolean;
+    /** 是否将 Less / Sass 样式语言处理为 CSS */
+    preprocessStyles?: boolean;
+    templateData: {
+        lang?: string;
+        /** 用于描述 `<slot>` / `<slot name="" ...props>` */
+        slots: Record<string, SlotNodesContext>;
+        /** 收集模板 ref 对应的 script 绑定元数据 */
+        refBindings: RefBindings;
+        /** 收集所有模板中的响应式变量，其来自 script 的绑定元数据 */
+        reactiveBindings: ReactiveBindinds;
+    };
+    scriptData: {
+        lang: LangType;
+        /** 用于收集 Vue 的 `provide(name, value)` */
+        provide: ProvideData;
+        propsTSIface: IPropsContext;
+        source: string;
+    };
+    styleData: {
+        filePath: string;
+        /** style module 的名称  */
+        moduleName?: string;
+        /** style scoped 对应 id */
+        scopeId?: string;
+    };
+}
+type ImportItem = {
+    name: string;
+    onDemand: boolean;
+};
+type FileInputType = 'sfc' | 'script-js' | 'script-ts';
+interface SlotNodesContext {
+    name: string;
+    isScope: boolean;
+    props: {
+        prop: string;
+        value: string;
+        tsType: t.TSTypeAnnotation;
+    }[];
+}
+interface ReactiveBindinds {
+    [name: string]: {
+        name: string;
+        value: t.Expression;
+        source: string;
+        reactiveType: ReactiveTypes;
+    };
+}
+interface RefBindings {
+    [name: string]: {
+        tag: string;
+        name: string;
+        htmlType: string;
+    };
+}
+interface ProvideData {
+    name: string;
+    value: string;
+    isOccupied: boolean;
+    provide: ProvideData | Record<string, any>;
+}
+interface IPropsContext {
+    /**
+     * props 接口名称
+     */
+    name: string;
+    /**
+     * 标记为疑似有 props 但是在 js 环境下
+     */
+    hasPropsInJsEnv?: boolean;
+    /**
+     * 用于记录源码中对应 API 的 ts 类型
+     *
+     * 1.推导出的属性元数据，如 (defineProps(['foo', 'bar']))
+     * 记录 key 和对应的类型（默认为 any/String 等）
+     *
+     * 2.显式定义的 TS 类型节点，如 (defineProps<{...}>)
+     */
+    propsTypes: t.TSType[];
+    emitTypes: t.TSType[];
+    slotTypes: t.TSType[];
+}
+
+interface ParseResult {
+    template: BlockIR<SFCTemplateBlock, RootNode>;
+    script: BlockIR<SFCScriptBlock, ParseResult$1>;
+    style: BlockIR<SFCStyleBlock, undefined>;
+}
+type BlockIR<S, T> = {
+    source?: S;
+    ast: T;
+} | null;
+interface ParserOptions {
+    plugins?: PluginRegister<ParseResult>;
+}
+/**
+ * 解析 Vue 单文件组件（SFC）源码，生成结构化解析结果。
+ *
+ * 此函数是解析阶段的核心入口，
+ * 负责将 Vue SFC 源码解析为包含模板、脚本、样式等各个块的结构化数据。
+ *
+ * @param source - Vue 单文件组件的源码字符串
+ * @param ctx - 编译上下文对象
+ * @param plugins - 可选的插件注册表，用于对解析结果进行自定义处理和增强
+ * @returns 解析结果对象，包含模板、脚本、样式块的解析信息
+ * @throws 不会直接抛出异常，错误信息会通过日志系统记录
+ *
+ * @remarks
+ * - 函数内部使用 Vue 官方的 `@vue/compiler-sfc` 进行基础解析
+ * - 解析结果会经过后处理阶段，包括脚本元数据扫描
+ * - 插件按照注册顺序依次执行，可以对解析结果进行修改或增强
+ * - 错误处理：语法错误和编译错误会通过日志系统记录，不会中断执行
+ *
+ * @example
+ * ```typescript
+ * // 基础用法：解析一个简单的 Vue 组件
+ *
+ * const vueSource = `
+ * <template>
+ *   <div class="greeting">
+ *     Hello, {{ name }}!
+ *   </div>
+ * </template>
+ *
+ * <script setup lang="ts">
+ * import { ref } from 'vue'
+ *
+ * const name = ref('World')
+ * const count = ref(0)
+ *
+ * function increment() {
+ *   count.value++
+ * }
+ * </script>
+ *
+ * <style scoped>
+ * .greeting {
+ *   color: #42b983;
+ *   font-size: 1.5rem;
+ * }
+ * </style>
+ * `;
+ *
+ * const ctx: ICompilationContext = {
+ *   filename: 'MyComponent.vue',
+ *   // 其他上下文配置...
+ * };
+ *
+ * const result = parseSFC(vueSource, ctx);
+ *
+ * // 访问解析结果
+ * console.log(result.template?.ast); // 模板的 AST 节点
+ * console.log(result.script?.ast);   // 脚本的 Babel 解析结果
+ * console.log(result.style?.source); // 样式块原始信息
+ *
+ * // 使用可选插件配置，进行自定义处理
+ * const options: ParserOptions = {
+ *   plugins: {
+ *     myPlugin: (result, ctx) => {
+ *       // 提取组件元数据
+ *       const componentName = extractComponentName(result);
+ *       // 添加自定义分析结果
+ *       result.metadata = {
+ *         name: componentName,
+ *         analyzedAt: new Date().toISOString()
+ *       };
+ *     }
+ *   }
+ * };
+ *
+ * const resultWithPlugin = parseSFC(vueSource, compilationContext, options);
+ * ```
+ */
+declare function parseSFC(source: string, ctx: ICompilationContext, options?: ParserOptions): ParseResult;
+
+/**
+ * 仅用于解析 script 文件，参数与 parseSFC 一致
+ */
+declare function parseOnlyScript(source: string, ctx: ICompilationContext, options?: ParserOptions): ParseResult;
+
+/**
+ * 解析 Vue 组件源码的统一入口函数。
+ *
+ * 根据输入类型自动选择解析器：
+ * - `sfc`: 解析 Vue 单文件组件（包含 template/script/style）
+ * - `script-*`: 仅解析脚本文件（如 .js、.ts）
+ *
+ * @param source - 源码字符串
+ * @param ctx - 编译上下文，包含输入类型、文件名等信息
+ * @param options - 可选的解析器配置，如插件
+ * @returns 解析结果对象，包含模板、脚本、样式的结构化数据
+ */
+declare function parse(source: string, ctx: ICompilationContext, options?: ParserOptions): ParseResult;
+
+interface ScriptBlockIR {
+    /** Transformed full script AST (used for script-only input). */
+    scriptAST?: ParseResult$1;
+    imports: t.ImportDeclaration[];
+    exports: t.ExportDeclaration[];
+    tsTypes: t.TypeScript[];
+    /** Executable statements extracted from script block. */
+    statement: {
+        /** Statements hoisted outside component function. */
+        global: t.Node[];
+        /** Statements kept inside component function. */
+        local: ParseResult$1<t.File> | null;
+    };
+}
+
+declare const enum NodeTypes {
+    FRAGMENT = 0,
+    ELEMENT = 1,
+    TEXT = 2,
+    COMMENT = 3,
+    JSX_INTERPOLATION = 4
+}
+declare const enum PropTypes {
+    ATTRIBUTE = 1,
+    SLOT = 2,
+    EVENT = 3,
+    DYNAMIC_ATTRIBUTE = 4
+}
+interface BabelExp<T = Expression> {
+    content: string;
+    ast: T;
+}
+
+interface BaseSimpleNodeIR {
+    type: NodeTypes;
+    content: string;
+    babelExp: Expression;
+}
+interface FragmentNodeIR {
+    type: NodeTypes;
+    children: TemplateChildNodeIR[];
+}
+
+interface ElementNodeIR extends BaseElementNodeIR {
+    type: NodeTypes;
+    props: (PropsIR | SlotPropsIR)[];
+    children: TemplateChildNodeIR[];
+    meta: Partial<ElementNodeIRMeta>;
+    conditionIsHandled: boolean;
+    isBuiltIn?: boolean;
+    isRoute?: boolean;
+}
+interface BaseElementNodeIR {
+    tag: string;
+    isComponent?: boolean;
+    isSelfClosing?: boolean;
+    ref?: string;
+    loc?: SourceLocation;
+}
+interface ElementNodeIRMeta {
+    condition: ConditionMeta;
+    loop: LoopMeta;
+    memo: MemoMeta;
+    show: ShowMeta;
+}
+type ConditionMeta = {
+    if?: boolean;
+    elseIf?: boolean;
+    else?: boolean;
+    value: string;
+    babelExp: BabelExp;
+    next?: ElementNodeIR;
+    isHandled: boolean;
+};
+type LoopMeta = {
+    isLoop?: boolean;
+    value: {
+        source: string;
+        value: string;
+        key?: string;
+        index?: string;
+    };
+    isHandled: boolean;
+};
+type MemoMeta = {
+    isMemo?: boolean;
+    value: string;
+    babelExp: BabelExp<ArrayExpression>;
+    isHandled: boolean;
+};
+type ShowMeta = {
+    isShow?: boolean;
+    value: string;
+    babelExp: BabelExp;
+};
+
+interface PropsIR {
+    type: PropTypes;
+    rawName?: string;
+    name: string;
+    isStatic?: boolean;
+    modifiers?: string[];
+    value: PropIRValue;
+    isKeyLessVBind?: boolean;
+    babelExp: BabelExp<JSXIdentifier | Expression>;
+}
+type PropIRValue = {
+    content: string;
+    isStringLiteral?: boolean;
+    merge?: string[];
+    babelExp: BabelExp;
+};
+
+interface SlotPropsIR {
+    type: PropTypes.SLOT;
+    name: string;
+    rawName: string;
+    isStatic: boolean;
+    isScoped: boolean;
+    content?: TemplateChildNodeIR[];
+    callback?: {
+        arg: string;
+        exp: TemplateChildNodeIR[];
+    };
+}
+
+interface TemplateBlockIR {
+    children: TemplateChildNodeIR[];
+}
+type TemplateChildNodeIR = ElementNodeIR | BaseSimpleNodeIR | FragmentNodeIR;
+
+interface ReactIRDescriptor {
+    template: TemplateBlockIR;
+    script: ScriptBlockIR;
+    style?: string;
+}
+interface TransformerOptions {
+    plugins?: PluginRegister<ReactIRDescriptor>;
+}
+/**
+ * 将 Vue SFC 解析结果转换为 React 中间表示（IR）。
+ *
+ * 此函数是转换阶段的核心入口，负责将 Vue 组件的解析结果（AST）转换为
+ * 适合生成 React 代码的中间表示形式。转换过程包括模板转换和脚本转换。
+ *
+ * @param ast - Vue SFC 的解析结果，来自 {@link parse} 函数的返回值
+ * @param ctx - 编译上下文对象
+ * @param plugins - 可选的插件注册表，用于对转换结果进行自定义处理和增强
+ * @returns React 中间表示描述符，包含模板、脚本和样式的转换结果
+ *
+ * @remarks
+ * - 模板转换：将 Vue 模板 AST 转换为 React 可用的模板 IR
+ * - 脚本转换：将 Vue 脚本 AST 转换为 React 可用的脚本 IR
+ * - 样式处理：提取样式块内容，保留原始 CSS 字符串
+ * - 插件支持：支持通过插件对转换结果进行自定义处理
+ *
+ * @example
+ * ```typescript
+ * // 转换示例
+ *
+ * const ctx: ICompilationContext = {
+ *   filename: 'MyComponent.vue',
+ *   // 其他上下文配置...
+ * };
+ *
+ * // 1. 首先解析 Vue SFC
+ * const parseResult = parse(vueSource, ctx);
+ *
+ * // 2. 将解析结果转换为 React IR
+ * const reactIR = transform(parseResult, ctx);
+ *
+ * // 访问转换结果
+ * console.log(reactIR.template); // 模板转换结果
+ * console.log(reactIR.script);   // 脚本转换结果
+ * console.log(reactIR.style);    // 样式内容字符串
+ *
+ * // 使用可选插件配置，进行自定义处理
+ * const options: TransformerOptions = {
+ *   plugins: {
+ *     extractMetadata: (result, ctx) => {
+ *       const componentName = extractComponentNameFromScript(result.script);
+ *       const propsCount = countProps(result.script);
+ *
+ *       result.metadata = {
+ *         name: componentName,
+ *         propsCount,
+ *         hasStyle: !!result.style,
+ *         convertedAt: new Date().toISOString(),
+ *       };
+ *     },
+ *
+ *     // 插2：样式预处理
+ *     preprocessStyles: (result, ctx) => {
+ *       if (result.style) {
+ *         // 对样式进行预处理，如添加前缀等
+ *         result.style = addVendorPrefixes(result.style);
+ *         result.style = minifyCSS(result.style);
+ *       }
+ *     },
+ *   }
+ * }
+ *
+ * // 使用多个插件进行转换
+ * const reactIRWithPlugins = transform(parseResult, ctx, plugins);
+ *
+ * // 插件处理后的结果包含自定义数据
+ * console.log(reactIRWithPlugins.metadata);
+ * ```
+ */
+declare function transform(ast: ParseResult, ctx: ICompilationContext, options?: TransformerOptions): ReactIRDescriptor;
+
+interface GeneratorOptions extends GeneratorOptions$1 {
+    plugins?: PluginRegister<GeneratorResult>;
+}
+interface GeneratorResult {
+    ast: t.Program | ParseResult$1;
+    code: string;
+    source: string;
+}
+/**
+ * 将 React 中间表示（IR）生成为可执行的 JSX/TSX 代码。
+ *
+ * 此函数是代码生成阶段的核心入口，负责将转换后的 React IR 转换为
+ * 完整的 AST 并最终生成源代码。生成过程包括 JSX 构建和脚本构建。
+ *
+ * @param ir - React 中间表示描述符，来自 {@link transform} 函数的返回值
+ * @param ctx - 编译上下文对象
+ * @param options - 可选的生成选项，包括 Babel 生成器选项和插件
+ * @returns 生成结果对象，包含 AST、生成的代码和原始源码引用
+ *
+ * @remarks
+ * - JSX 构建：将模板 IR 转换为 JSX AST 节点
+ * - 脚本构建：将脚本 IR 与 JSX 结合，构建完整的程序 AST
+ * - 代码生成：使用 Babel 生成器将 AST 转换为源代码字符串
+ * - 插件支持：支持通过插件对生成结果进行自定义处理
+ *
+ * @example
+ * ```typescript
+ * // 生成示例
+ *
+ * const ctx: ICompilationContext = {
+ *   filename: 'MyComponent.vue',
+ *   source: vueSource,
+ *   // 其他上下文配置...
+ * };
+ *
+ * // 1. 解析 Vue SFC
+ * const parseResult = parse(vueSource, ctx);
+ *
+ * // 2. 转换为 React IR
+ * const reactIR = transform(parseResult, ctx);
+ *
+ * // 使用可选配置项进行自定义处理
+ * const generatorOptions: GeneratorOptions = {
+ *   // 配置 jsesc 避免 Unicode 转义
+ *   jsescOption: {
+ *     minimal: true,
+ *     quotes: 'single'
+ *   },
+ *   minified: true,
+ *
+ *   // 自定义插件
+ *   plugins: {
+ *     // 插件1：代码格式化
+ *     formatCode: (result, ctx) => {
+ *       // 使用 prettier 格式化生成的代码
+ *       result.code = prettier.format(result.code, {
+ *         parser: 'babel',
+ *         semi: true,
+ *         singleQuote: true,
+ *       });
+ *     },
+ *
+ *     // 插件2：代码质量检查
+ *     lintGeneratedCode: (result, ctx) => {
+ *       const issues = eslint.verify(result.code, {
+ *         rules: {
+ *           'react/react-in-jsx-scope': 'off',
+ *           'no-unused-vars': 'warn',
+ *         },
+ *       });
+ *
+ *       if (issues.length > 0) {
+ *         result.lintIssues = issues;
+ *         console.warn(`Found ${issues.length} lint issues in generated code`);
+ *       }
+ *     },
+ *   },
+ * };
+ *
+ * // 3. 生成 React 组件
+ * const generated = generateComponent(reactIR, ctx, generatorOptions);
+ *
+ * // 访问生成结果
+ * console.log(generated.ast);   // 完整的 Babel AST
+ * console.log(generated.code);  // 生成的 React 代码
+ * console.log(generated.source); // 原始 Vue 源码
+ * ```
+ */
+declare function generateComponent(ir: ReactIRDescriptor, ctx: ICompilationContext, options?: GeneratorOptions): GeneratorResult;
+
+declare function generateOnlyScript(ir: ReactIRDescriptor, ctx: ICompilationContext, options?: GeneratorOptions): GeneratorResult;
+
+/**
+ * 代码生成的统一入口函数。
+ *
+ * 根据输入类型自动选择生成器：
+ * - `sfc`: 生成完整的 React 组件（包含 JSX 和脚本）
+ * - `script-*`: 仅生成脚本代码（如 .js、.ts）
+ *
+ * @param ir - React 中间表示描述符，来自转换阶段的结果
+ * @param ctx - 编译上下文，包含输入类型、源码等信息
+ * @param options - 可选的生成器配置，如 Babel 生成选项和插件
+ * @returns 生成结果对象，包含 AST、生成的代码和原始源码
+ */
+declare function generate(ir: ReactIRDescriptor, ctx: ICompilationContext, options?: GeneratorOptions): GeneratorResult;
+
+interface CompilerOptions {
+    /**
+     * Manually specify the root directory.
+     * @default process.cwd()
+     */
+    root?: string;
+    /**
+     * Path to the source file or directory.
+     * - If it is a file, compile the single file.
+     * - If it is a directory, recursively compile all .vue files under the directory.
+     *
+     * @default
+     * 'src/' // The src directory under the root directory
+     */
+    input?: string;
+    /**
+     * Whether to enable build cache and reuse the previous cache results
+     * @default true
+     */
+    cache?: boolean;
+    output?: {
+        /**
+         * Output the name of the root directory corresponding to the file's location.
+         * @default '.vureact'
+         */
+        workspace?: string;
+        /**
+         * Output directory name, relative to `output.workspace`
+         * @default 'dist'
+         */
+        outDir?: string;
+        /**
+         * Whether to automatically call Vite to initialize a standard
+         * React project environment before compilation.
+         * @default true
+         */
+        bootstrapVite?: boolean | {
+            /**
+             * @default 'react-ts'
+             */
+            template: 'react-ts' | 'react';
+        };
+        /**
+         * Specify asset files that do not need to be copied.
+         * They can be filenames or paths, using fuzzy matching.
+         * @default
+         * [
+         *  'package.json',
+         *  'package-lock.json',
+         *  'pnpm-lock.yaml',
+         *  'index.html',
+         *  'tsconfig.',
+         *  'vite.config.',
+         *  'eslint.config.',
+         *  'readme.',
+         *  'vue.',
+         *  'vureact.config.js',
+         * ]
+         */
+        ignoreAssets?: string[];
+    };
+    /**
+     * Excluded file/directory matching patterns (glob syntax supported).
+     * @default
+     * [
+     *  'node_modules/**',
+     *  'dist/**',
+     *  'build/**',
+     *  '.git/**',
+     *  '.vureact/**'
+     * ]
+     */
+    exclude?: string[];
+    /**
+     * Whether to recursively search subdirectories.
+     * @default true
+     */
+    recursive?: boolean;
+    /**
+     * Options passed through to babel-generator.
+     */
+    generate?: GeneratorOptions$1;
+    /**
+     * Watch files in real time and auto-recompile on changes.
+     * @default false
+     */
+    watch?: boolean;
+    /**
+     * Whether to process Less/Sass style languages into CSS
+     * @default true
+     */
+    preprocessStyles?: boolean;
+    /**
+     * Can be used to add plugins and customize the output results of
+     * the parse/transform/codegen/compiled stages respectively.
+     *
+     * @example
+     * ```ts
+     * plugins: {
+     *  // For example, add custom data to the parsing results.
+     *  parser: {
+     *   myPlugin: (result, ctx) => {
+     *     result.metadata = {
+     *       timestamp: Date.now()
+     *     }
+     *   },
+     *  },
+     *
+     *  // If the key names parse/transform/codegen are not specified,
+     *  // the plugin will execute upon completion of compilation.
+     *  yourPlguin: (result) => {
+     *    console.log(result)
+     *  }
+     * }
+     * ```
+     */
+    plugins?: PluginRegister<CompilationResult> & {
+        /**
+         * Register parser plugins
+         */
+        parser?: PluginRegister<ParseResult>;
+        /**
+         * Register transformer plugins
+         */
+        transformer?: PluginRegister<ReactIRDescriptor>;
+        /**
+         * Register codegen plugins
+         */
+        codegen?: PluginRegister<GeneratorResult>;
+    };
+    format?: {
+        /**
+         * @default false
+         */
+        enabled?: boolean;
+        /**
+         * @default 'prettier'
+         */
+        formatter?: 'prettier' | 'builtin';
+        /**
+         * Configure the formatting options for Prettier,
+         * which takes effect only when the formatter is set to 'prettier'.
+         */
+        prettierOptions?: Options;
+    };
+    /**
+     * Log Control Options
+     */
+    logging?: {
+        /**
+         * @default true
+         */
+        enabled?: boolean;
+        /** Whether to output warning messages. */
+        warnings?: boolean;
+        /** Whether to output info messages. */
+        info?: boolean;
+        /** Whether to output error messages. */
+        errors?: boolean;
+    };
+    /**
+     * Execute only after the first successful full compilation.
+     */
+    onSuccess?: () => Promise<void | undefined>;
+    /**
+     * Execute after file are added or recompiled in `watch` mode.
+     *
+     * @param event Add or modify file
+     * @param unit Current sfc or script file compilation unit
+     */
+    onChange?: (event: 'add' | 'change', unit: SFCUnit | ScriptUnit) => Promise<void | undefined>;
+}
+interface PluginRegister<T> {
+    [name: string]: (result: T, ctx: ICompilationContext) => void;
+}
+type CompilationResult = SFCCompilationResult | ScriptCompilationResult;
+interface SFCCompilationResult extends BaseCompilationResult {
+    fileInfo: {
+        jsx: {
+            file: string;
+            lang: string;
+        };
+        css: {
+            file?: string;
+            hash?: string;
+            code?: string;
+        };
+    };
+}
+interface ScriptCompilationResult extends BaseCompilationResult {
+    fileInfo: {
+        script: {
+            file: string;
+            lang: string;
+        };
+    };
+}
+interface BaseCompilationResult extends GeneratorResult {
+    fileId: string;
+    hasRoute?: boolean;
+}
+interface ScriptUnit extends CompilationUnit {
+    output: {
+        script: OutputItem;
+    } | null;
+}
+interface SFCUnit extends CompilationUnit {
+    output: {
+        jsx: OutputItem;
+        css: Partial<OutputItem>;
+    } | null;
+}
+interface OutputItem {
+    file: string;
+    code: string;
+}
+interface AssetUnit extends Omit<CompilationUnit, 'fileId' | 'source'> {
+}
+interface CompilationUnit extends FileMeta {
+    file: string;
+    fileId: string;
+    source: string;
+    hasRoute?: boolean;
+}
+type LoadedCache<T = CacheMeta> = {
+    key: CacheKey;
+    target: T[];
+    source: CacheList;
+};
+type CacheMeta = Vue2ReactCacheMeta | FileCacheMeta;
+declare enum CacheKey {
+    SFC = "sfc",
+    SCRIPT = "script",
+    ASSET = "copied"
+}
+interface CacheList {
+    [CacheKey.SFC]: Vue2ReactCacheMeta[];
+    [CacheKey.SCRIPT]: FileCacheMeta[];
+    [CacheKey.ASSET]: FileCacheMeta[];
+}
+type Vue2ReactCacheMeta = Omit<SFCUnit, 'source'>;
+interface FileCacheMeta extends FileMeta {
+    file: string;
+}
+interface FileMeta {
+    fileSize: number;
+    mtime: number;
+    hash?: string;
+}
+interface CacheCheckResult {
+    shouldCompile: boolean;
+    hash?: string;
+}
+
+declare class Helper {
+    private compilerOpts;
+    private pathFilter;
+    private workspaceDir;
+    private outDir;
+    constructor(opts: CompilerOptions);
+    /**
+     * 获取用户的项目根目录
+     */
+    getProjectRoot(): string;
+    /**
+     * 获取输入文件的路径
+     */
+    getInputPath(): string;
+    /**
+     * 检查 input 路径是否是单个文件
+     */
+    isSingleFile(): boolean;
+    /**
+     * 获取输出文件的路径。如：'[root]/.vureact/dist/'
+     */
+    getOuputPath(): string;
+    getOutDirName(): string;
+    getWorkspaceDir(): string;
+    /**
+     * 根据相对输出路径反推源文件路径
+     */
+    getSourcePath(outputPath: string): string;
+    getIgnoreAssets(): Set<string>;
+    getIsCache(): boolean;
+    /**
+     * 返回原始目录下的 package.json 路径
+     */
+    getRootPkgPath(): string;
+    /**
+     * 返回 output 的 package.json 路径
+     */
+    getOutputPkgPath(): string;
+    /**
+     * 返回文件相对工作区的路径
+     */
+    relativePath(filePath: string): string;
+    /**
+     * 替换 .vue 文件名后缀为 .jsx/.tsx
+     * @param filePath 文件完整路径
+     * @param ext 文件拓展名
+     * @returns 返回文件的相对路径，不包含当前工作区路径
+     */
+    replaceVueFileExt(filePath: string, ext: string): string;
+    /**
+     * 判断是否应该跳过不需要进行文件搜索的路径
+     */
+    shouldSkipPath(filePath: string): boolean;
+    /**
+     * 自动根据项目结构推导 react-app 目录下的对应位置
+     */
+    resolveOutputPath(filePath: string, extname?: string): string;
+    /**
+     * 格式化代码
+     */
+    formatCode({ code, fileInfo }: CompilationResult): Promise<string>;
+    /**
+     * 通用的缓存校验工具函数
+     * @param current 当前文件元数据
+     * @param cached  缓存中的旧数据
+     * @param getSource 获取文件内容的函数（仅在元数据不一致时才调用，避免多余 I/O）
+     */
+    checkCacheStatus(current: FileMeta, cached: CacheMeta | undefined, getSource: () => Promise<string>): Promise<CacheCheckResult>;
+    /**
+     * 对比相同两个文件的基础元数据
+     */
+    compareFileMeta(a: FileMeta, b: FileMeta): boolean;
+    /**
+     * 统一的写文件方法，包含自动创建目录
+     */
+    writeFileWithDir(filePath: string, content: string): Promise<void>;
+    /**
+     * 加载指定文件的缓存内容
+     * @param key 缓存键
+     */
+    loadCache(key: CacheKey.SFC): Promise<LoadedCache<Vue2ReactCacheMeta>>;
+    loadCache(key: CacheKey.SCRIPT | CacheKey.ASSET): Promise<LoadedCache<FileCacheMeta>>;
+    loadCache(key: CacheKey.SFC | CacheKey.SCRIPT | CacheKey.ASSET): Promise<LoadedCache<Vue2ReactCacheMeta | FileCacheMeta>>;
+    createCacheData(key: CacheKey): LoadedCache;
+    /**
+     * 获取缓存文件路径
+     */
+    getCachePath(): string;
+    saveCache(data?: LoadedCache): Promise<void>;
+    genHash(content: string): string;
+    /**
+     * 扫描指定目录下的所有文件
+     * @param dir 目标目录
+     * @param filter 筛选指定的文件后缀名
+     */
+    scanFiles(dir: string, filter: (file: string) => boolean): string[];
+    getAbsPath(filePath: string): string;
+    getFileMeta(filePath: string): Promise<FileMeta>;
+    removeOutputFile(filePath: string, resolveOutputPath?: boolean): Promise<void>;
+    updateCache(targetFile: string, newData: any, cache: LoadedCache): void;
+    resolveViteCreateApp(): void;
+    /**
+     * 获取需要排除编译的文件
+     */
+    getExcludes(): string[];
+    /**
+     * 打印 core 模块执行过程中收集的日志
+     */
+    printCoreLogs(): void;
+    printCompileInfo(file: string, duration: string): void;
+    print(...message: any[]): void;
+    /**
+     * 读取 package.json 文件内容，并处理成对象返回
+     */
+    resolvePackageFile(path: string): Promise<Record<string, any>>;
+}
+
+/**
+ * 基础编译器类，提供 Vue 到 React 代码转换的核心编译功能。
+ *
+ * 此类继承自 {@link Helper}，是 VuReact 编译器的核心实现，负责：
+ * 1. 初始化编译上下文：为每次编译创建独立的上下文环境
+ * 2. 执行完整的编译流程：解析（parse）→ 转换（transform）→ 生成（generate）
+ * 3. 管理编译选项和配置：处理用户传入的编译器配置
+ * 4. 插件系统集成：支持解析、转换、生成各阶段的插件扩展
+ * 5. 错误处理和日志记录：通过日志系统记录编译过程中的信息
+ *
+ * 主要用途：
+ * - 供 {@link FileCompiler} 继承使用，实现文件系统级别的批量编译
+ * - 直接实例化用于单文件编译，适合集成到其他工具链中
+ *
+ * 核心特性：
+ * - 三阶段编译流水线：严格遵循解析→转换→生成的编译模型
+ * - 插件化架构：支持在编译各阶段插入自定义逻辑
+ * - 上下文隔离：每次编译创建独立上下文，避免状态污染
+ * - 资源感知：自动处理样式预处理和路由依赖检测
+ * - 错误恢复：编译错误通过日志记录，不会中断整个流程
+ *
+ * 编译流程详解：
+ * 1. 解析阶段：使用 {@link parse} 将 Vue 代码解析为抽象语法树（AST）
+ * 2. 转换阶段：使用 {@link transform} 将 Vue AST 转换为 React 中间表示（IR）
+ * 3. 生成阶段：使用 {@link generate} 将 React IR 生成为目标代码
+ * 4. 插件执行：在各阶段执行注册的插件，支持自定义扩展
+ *
+ * @example
+ * ```typescript
+ * // 创建基础编译器实例
+ * const compiler = new BaseCompiler({
+ *   cache: true,
+ *   preprocessStyles: true,
+ *   plugins: {
+ *     parser: {
+ *       myParserPlugin: (result, ctx) => {
+ *         // 解析阶段插件
+ *       }
+ *     },
+ *     transformer: {
+ *       myTransformerPlugin: (result, ctx) => {
+ *         // 转换阶段插件
+ *       }
+ *     }
+ *   }
+ * });
+ *
+ * // 编译单个 Vue 文件
+ * const result = compiler.compile(vueSourceCode, '/path/to/Component.vue');
+ *
+ * // 获取编译结果
+ * console.log(result.fileInfo); // 包含 JSX 和 CSS 文件信息
+ * console.log(result.code);     // 生成的 React 代码
+ * ```
+ *
+ * @remarks
+ * - 上下文管理：使用 {@link CompilationAdapter.createContext} 创建编译上下文
+ * - 错误处理：编译过程中的错误通过 {@link logger} 记录，不会抛出异常
+ * - 配置继承：继承 {@link Helper} 类的文件路径处理、缓存管理、格式化等工具方法
+ * - 版本管理：自动读取 package.json 中的版本号，便于调试和日志记录
+ *
+ * @see {@link FileCompiler} 用于文件系统级别的批量编译和增量构建
+ * @see {@link Helper} 提供基础的文件路径处理、缓存管理和格式化工具
+ * @see {@link CompilerOptions} 查看完整的编译器配置选项
+ * @see {@link CompilationResult} 编译结果的数据结构
+ */
+declare class BaseCompiler extends Helper {
+    version: string;
+    options: CompilerOptions;
+    private createContext;
+    /**
+     * 创建基础编译器实例
+     *
+     * @param options - 编译器配置选项，包括缓存设置、插件配置、样式预处理等，
+     * 所有选项都会传递给父类 {@link Helper} 进行初始化
+     *
+     * @see {@link CompilerOptions} 查看完整的配置选项说明
+     */
+    constructor(options?: CompilerOptions);
+    /**
+     * 编译 Vue 源代码为 React 代码
+     *
+     * 该方法执行完整的编译流程，包括：
+     * 1. 上下文初始化：创建独立的编译上下文
+     * 2. 解析阶段：将 Vue 源代码解析为抽象语法树（AST）
+     * 3. 转换阶段：将 Vue AST 转换为 React 中间表示（IR）
+     * 4. 生成阶段：将 React IR 生成为目标代码
+     * 5. 插件执行：在各阶段执行注册的插件
+     * 6. 结果处理：整理编译结果并返回
+     *
+     * 编译过程使用 try-finally 确保上下文资源被正确清理，
+     * 即使编译过程中发生错误也不会导致资源泄漏。
+     *
+     * @param source - Vue 源代码字符串
+     * @param filename - 源文件名，用于生成文件ID和输出路径
+     * @returns {CompilationResult} 编译结果，包含生成的代码和文件信息
+     *
+     * @example
+     * ```typescript
+     * const vueCode = `
+     * <template>
+     *   <div class="container">{{ message }}</div>
+     * </template>
+     *
+     * <script setup lang="ts">
+     * import { ref } from 'vue;
+     * const message = ref('Hello Vue')
+     * </script>
+     *
+     * <style scoped>
+     * .container {
+     *   padding: 20px;
+     * }
+     * </style>
+     * `;
+     *
+     * const result = compiler.compile(vueCode, 'MyComponent.vue');
+     * console.log(result.code); // 生成的 React JSX 代码
+     * console.log(result.fileInfo.jsx.file); // 输出文件路径
+     * ```
+     *
+     * @throws 不会直接抛出异常，错误通过日志系统记录
+     * @see {@link parse} 解析函数
+     * @see {@link transform} 转换函数
+     * @see {@link generate} 生成函数
+     * @see {@link executePlugins} 插件执行函数
+     */
+    compile(source: string, filename: string): CompilationResult;
+    /**
+     * 处理 SFC 和 Script 文件的编译结果
+     *
+     * 根据编译上下文中的输入类型（SFC 或 Script），整理并返回相应的编译结果。
+     * 对于 SFC 文件，返回包含 JSX 和 CSS 信息的完整结果；
+     * 对于 Script 文件，返回仅包含脚本信息的结果。
+     *
+     * 关键处理逻辑：
+     * 1. 构建基础结果：包含文件ID、路由信息和生成的代码
+     * 2. 确定输出路径：根据源文件路径和语言类型生成输出文件路径
+     * 3. 区分文件类型：
+     *    - SFC 文件：生成 .tsx 扩展名，包含样式信息
+     *    - Script 文件：保持原扩展名，不包含样式信息
+     * 4. 样式处理：提取样式文件路径、作用域ID和样式代码
+     *
+     * @private
+     * @param ir - React 中间表示（IR）描述符，包含转换后的组件信息
+     * @param gen - 代码生成结果，包含生成的代码和源码映射
+     * @param ctxData - 编译上下文数据，包含文件信息和编译状态
+     * @returns {CompilationResult} 整理后的编译结果
+     *
+     * @remarks
+     * - 文件扩展名处理：Vue SFC 文件会转换为 .tsx 或 .jsx 文件
+     * - 样式分离：SFC 中的样式会被提取到独立的 CSS 文件中
+     * - 路由检测：自动检测组件是否使用路由，用于依赖注入
+     * - 作用域样式：为 Scoped CSS 生成唯一的作用域ID
+     *
+     * @see {@link SFCCompilationResult} SFC 编译结果类型
+     * @see {@link ScriptCompilationResult} Script 编译结果类型
+     */
+    private resolveResult;
+    /**
+     * 初始化 Babel 代码生成选项
+     *
+     * 合并用户自定义的生成选项与默认选项，确保代码生成的一致性和正确性。
+     * 默认配置优化了代码的可读性和性能：
+     * 1. 最小化 Unicode 转义：只转义必要的字符，保持代码可读性
+     * 2. 统一引号风格：使用单引号，符合 JavaScript 社区常见约定
+     * 3. 代码压缩：启用最小化，移除不必要的空白字符
+     *
+     * 如果用户提供了自定义选项，会与默认选项进行深度合并，
+     * 用户选项的优先级高于默认选项。
+     *
+     * @private
+     * @param filename - 可选的文件名，用于源码映射配置
+     * @returns {GeneratorOptions} 合并后的 Babel 生成选项
+     *
+     * @remarks
+     * - 源码映射支持：如果启用了 sourceMaps 且提供了文件名，会自动设置 sourceFileName
+     * - 选项合并策略：用户选项会覆盖默认选项，实现灵活的配置
+     * - 性能优化：默认启用 minified 以减少生成代码的体积
+     * - 编码安全：使用 jsesc 确保特殊字符的正确转义
+     *
+     * @example
+     * ```typescript
+     * // 默认选项
+     * const defaultOptions = {
+     *   jsescOption: { minimal: true, quotes: 'single' },
+     *   minified: true
+     * };
+     *
+     * // 用户自定义选项
+     * const userOptions = {
+     *   minified: false, // 覆盖默认值
+     *   sourceMaps: true // 新增选项
+     * };
+     *
+     * // 合并结果
+     * const merged = {
+     *   jsescOption: { minimal: true, quotes: 'single' },
+     *   minified: false, // 用户值
+     *   sourceMaps: true // 用户值
+     * };
+     * ```
+     *
+     * @see {@link GeneratorOptions} Babel 生成选项类型定义
+     */
+    private prepareGenerateOptions;
+}
+
+/**
+ * 文件系统编译器，负责将 Vue 项目批量转换为 React 项目。
+ *
+ * 此类继承自 {@link BaseCompiler}，提供完整的文件系统级别编译功能，包括：
+ * 1. 批量扫描和编译 Vue 单文件组件（SFC）
+ * 2. 处理 JavaScript/TypeScript 脚本文件
+ * 3. 资源文件（图片、样式、字体等）的智能拷贝
+ * 4. 增量编译和高效的缓存管理
+ * 5. 文件系统监控和自动清理
+ * 6. Vite 项目环境自动初始化
+ *
+ * 主要特性：
+ * - 增量编译：基于文件哈希、大小和修改时间进行变更检测，跳过未变更的文件
+ * - 智能缓存：维护编译缓存，支持清理过期文件，提高编译效率
+ * - 资源处理：自动识别并拷贝非编译文件，保持目录结构
+ * - 错误隔离：单个文件编译失败不影响其他文件处理
+ * - 并发处理：支持 Promise.all 并发处理多个文件，提升编译速度
+ * - 路由感知：自动检测并注入 Vue Router 到 React Router 的转换依赖
+ *
+ * 架构设计：
+ * 该类采用管理器模式，将不同职责分解到独立的子管理器中：
+ * - {@link PipelineManager}: 管理编译管线流程
+ * - {@link FileProcessor}: 处理单个文件的编译逻辑
+ * - {@link CacheManager}: 管理编译缓存
+ * - {@link AssetManager}: 处理资源文件拷贝
+ * - {@link CleanupManager}: 清理过期文件和缓存
+ * - {@link ViteBootstrapper}: 初始化 Vite React 项目环境
+ *
+ * @example
+ * ```typescript
+ * // 创建文件编译器实例
+ * const compiler = new FileCompiler({
+ *   input: 'src',
+ *   exclude: ['src/main.ts'],
+ *   output: {
+ *     workspace: '.vureact',
+ *     outDir: 'react-app',
+ *     bootstrapVite: true
+ *   },
+ *   cache: true,
+ *   watch: false
+ * });
+ *
+ * // 执行完整编译
+ * await compiler.execute();
+ *
+ * // 处理单个 Vue 文件（适用于 watch 模式）
+ * await compiler.processSFC('/path/to/Component.vue');
+ *
+ * // 处理单个 Script 文件
+ * await compiler.processScript('/path/to/foo.ts');
+ *
+ * // 处理单个资源文件
+ * await compiler.processAsset('/path/to/image.png');
+ *
+ * // 清理指定路径的输出文件
+ * await compiler.removeOutputPath('/path/to/old-component.vue', CacheKey.SFC);
+ * ```
+ *
+ * @remarks
+ * - 编译流程：遵循 "环境初始化 → SFC编译 → Script编译 → 资源拷贝" 的顺序
+ * - 缓存机制：使用文件哈希、大小和修改时间三重验证确保准确性
+ * - 目录结构：保持输入目录结构到输出目录，便于项目迁移
+ * - 错误处理：编译错误会记录到日志系统，但不会中断整个编译流程
+ * - 性能优化：支持并发处理和增量编译，大幅提升大型项目编译速度
+ *
+ * @see {@link BaseCompiler} 提供核心的单文件编译功能
+ * @see {@link Helper} 提供基础的文件路径处理和工具方法
+ * @see {@link CompilerOptions} 完整的编译器配置选项
+ */
+declare class FileCompiler extends BaseCompiler {
+    private skippedCount;
+    private spinner;
+    private viteBootstrapper;
+    private pipelineManager;
+    private fileProcessor;
+    private compilationUnitProcessor;
+    private cacheManager;
+    private assetManager;
+    private cleanupManager;
+    /**
+     * 创建文件系统编译器实例
+     *
+     * @param options - 编译器配置选项，继承自 BaseCompiler 的选项
+     *                 包括输入路径、输出配置、缓存设置、排除模式等
+     * @see {@link CompilerOptions} 查看完整的选项说明
+     */
+    constructor(options?: CompilerOptions);
+    /**
+     * 初始化所有管理器实例
+     *
+     * 按照依赖关系顺序创建各个管理器：
+     * 1. 基础管理器（无依赖）
+     * 2. 依赖基础管理器的管理器
+     * 3. 依赖其他管理器的管理器
+     *
+     * @private
+     */
+    private initializeManagers;
+    /**
+     * 执行完整的编译流程
+     *
+     * 该方法执行以下步骤：
+     * 1. 环境初始化：清理旧输出（如果禁用缓存）并初始化 Vite 项目环境
+     * 2. Vue 文件编译：批量处理所有 .vue 文件
+     * 3. Script 文件编译：批量处理所有 .js/.ts 文件
+     * 4. 资源文件拷贝：处理剩余的非编译文件
+     * 5. 统计输出：显示编译结果和性能统计
+     *
+     * @async
+     * @throws {Error} 当编译过程中发生致命错误时抛出
+     * @returns {Promise<void>}
+     */
+    execute(): Promise<void>;
+    /**
+     * 处理单个 Vue 单文件组件（SFC）
+     *
+     * 此方法主要用于 CLI 的 watch 模式，当检测到文件变更时调用。
+     * 支持增量编译，如果文件未变更则跳过编译。
+     *
+     * @async
+     * @param filePath - Vue 文件的绝对路径
+     * @param existingCache - 可选的预加载缓存对象，用于增量编译
+     * @returns {Promise<SFCUnit | undefined>} 编译单元对象，如果跳过编译则返回 undefined
+     * @see {@link FileProcessor.processSFC}
+     */
+    processSFC(filePath: string, existingCache?: LoadedCache<Vue2ReactCacheMeta>): Promise<SFCUnit | undefined>;
+    /**
+     * 处理单个 JavaScript/TypeScript 脚本文件
+     *
+     * 此方法主要用于 CLI 的 watch 模式，当检测到文件变更时调用。
+     * 支持增量编译，如果文件未变更则跳过编译。
+     *
+     * @async
+     * @param filePath - 脚本文件的绝对路径
+     * @param existingCache - 可选的预加载缓存对象，用于增量编译
+     * @returns {Promise<ScriptUnit | undefined>} 编译单元对象，如果跳过编译则返回 undefined
+     * @see {@link FileProcessor.processScript}
+     */
+    processScript(filePath: string, existingCache?: LoadedCache<FileCacheMeta>): Promise<ScriptUnit | undefined>;
+    /**
+     * 处理单个文件（Vue 或 Script）
+     *
+     * 通用的文件处理方法，根据 CacheKey 类型自动选择处理逻辑。
+     * 主要用于内部调用和统一的文件处理接口。
+     *
+     * @async
+     * @param key - 文件类型标识（SFC 或 SCRIPT）
+     * @param filePath - 文件的绝对路径
+     * @param existingCache - 可选的预加载缓存对象
+     * @returns {Promise<SFCUnit | ScriptUnit | undefined>} 编译单元对象
+     * @see {@link FileProcessor.processFile}
+     */
+    processFile(key: CacheKey, filePath: string, existingCache?: LoadedCache): Promise<SFCUnit | ScriptUnit | undefined>;
+    /**
+     * 处理单个资源文件
+     *
+     * 比较文件与缓存，决定是否需要拷贝。
+     * 资源文件包括图片、字体、样式文件等非编译文件。
+     *
+     * @async
+     * @param filePath - 资源文件的绝对路径
+     * @param existingCache - 可选的预加载缓存对象
+     * @returns {Promise<FileCacheMeta>} 资源文件的缓存元数据
+     * @see {@link AssetManager.processAsset}
+     */
+    processAsset(filePath: string, existingCache?: LoadedCache<FileCacheMeta>): Promise<FileCacheMeta>;
+    /**
+     * 删除指定路径对应的输出文件和缓存
+     *
+     * 当源文件被删除或重命名时，需要清理对应的输出文件。
+     * 主要用于 watch 模式下的文件删除处理。
+     *
+     * @async
+     * @param targetPath - 源代码的路径（文件或文件夹）
+     * @param type - 清理类型，指定是 SFC、SCRIPT 还是 ASSET
+     * @returns {Promise<void>}
+     * @see {@link CleanupManager.removeOutputPath}
+     */
+    removeOutputPath(targetPath: string, type: CacheKey): Promise<void>;
+    /**
+     * 获取跳过的文件数量
+     *
+     * 在增量编译中，未变更的文件会被跳过。
+     * 此方法返回当前编译会话中跳过的文件数量。
+     *
+     * @returns {number} 跳过的文件数量
+     */
+    getSkippedCount(): number;
+    /**
+     * 重置跳过的文件数量
+     *
+     * 在每次新的编译会话开始时调用，重置计数器。
+     */
+    resetSkippedCount(): void;
+    /**
+     * 显示编译统计信息
+     *
+     * 在编译完成后调用，显示以下信息：
+     * 1. 编译耗时
+     * 2. 输出目录
+     * 3. 跳过的文件数量
+     * 4. 处理的文件分类统计
+     *
+     * @private
+     * @param endTime - 格式化后的编译耗时字符串
+     * @param sfcCount - 处理的 Vue 文件数量
+     * @param scriptCount - 处理的脚本文件数量
+     * @param assetCount - 处理的资源文件数量
+     */
+    private showCompileStats;
+}
+
+/**
+ * @see {@link CompilerOptions}
+ */
+declare function defineConfig(options: CompilerOptions): CompilerOptions;
+
+/**
+ * Next Vue to React compiler, compiles Vue 3 syntax into runnable React 18+ code.
+ *
+ * @extends FileCompiler
+ *
+ * @see {@link FileCompiler}
+ * @see https://vureact.top
+ */
+declare class VuReact extends FileCompiler {
+}
+
+export { type AssetUnit, type BaseCompilationResult, BaseCompiler, type CacheCheckResult, CacheKey, type CacheList, type CacheMeta, type CompilationResult, type CompilationUnit, type CompilerOptions, type FileCacheMeta, FileCompiler, type FileMeta, type GeneratorOptions, type GeneratorResult, Helper, type LoadedCache, type ParseResult, type ParserOptions, type PluginRegister, type ReactIRDescriptor, type SFCCompilationResult, type SFCUnit, type ScriptCompilationResult, type ScriptUnit, type TransformerOptions, VuReact, type Vue2ReactCacheMeta, defineConfig, generate, generateComponent, generateOnlyScript, parse, parseOnlyScript, parseSFC, transform };