@vureact/compiler-core 1.3.0 → 1.5.0

package/lib/compiler-core.d.cts

@@ -1,11 +1,150 @@
 import { GeneratorOptions as GeneratorOptions$1 } from '@babel/generator';
+import { ParseResult as ParseResult$1 } from '@babel/parser';
 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';
 
+interface FileLockOptions {
+    /**
+     * 锁过期时间（毫秒）
+     * 默认: 10000 (10秒)
+     */
+    stale?: number;
+    /**
+     * 锁更新间隔（毫秒）
+     * 默认: stale / 2
+     */
+    update?: number;
+    /**
+     * 重试配置
+     * 可以是重试次数或 retry 选项对象
+     * 默认: 5
+     */
+    retries?: number | {
+        retries?: number;
+        factor?: number;
+        minTimeout?: number;
+        maxTimeout?: number;
+        randomize?: boolean;
+    };
+    /**
+     * 是否解析符号链接
+     * 默认: true
+     */
+    realpath?: boolean;
+    /**
+     * 自定义锁文件路径
+     * 默认: `${filePath}.lock`
+     */
+    lockfilePath?: string;
+}
+
+type CompilationUnit = SFCUnit | ScriptUnit | StyleUnit;
+interface SFCUnit extends BaseUnit {
+    type: CacheKey.SFC;
+    output?: {
+        jsx: OutputItem;
+        css: Partial<OutputItem>;
+    };
+}
+interface ScriptUnit extends BaseUnit {
+    type: CacheKey.SCRIPT;
+    output?: {
+        script: OutputItem;
+    };
+}
+interface StyleUnit extends Omit<BaseUnit, 'hasRoute'> {
+    type: CacheKey.STYLE;
+    output?: {
+        style: OutputItem;
+    };
+}
+interface AssetUnit extends Omit<BaseUnit, 'fileId' | 'source' | 'hasRoute'> {
+    type: CacheKey.ASSET;
+}
+interface BaseUnit extends FileMeta {
+    file: string;
+    fileId: string;
+    source: string;
+    hasRoute?: boolean;
+}
+interface OutputItem {
+    file: string;
+    code: string;
+}
+
+type LoadedCache<T = CacheMeta> = {
+    key: CacheKey;
+    target: T[];
+    source: CacheList;
+};
+type CacheMeta = Vue2ReactCacheMeta | FileCacheMeta;
+declare enum CacheKey {
+    SFC = "sfc",
+    SCRIPT = "script",
+    STYLE = "style",
+    ASSET = "copied"
+}
+interface CacheList {
+    [CacheKey.SFC]: Vue2ReactCacheMeta[];
+    [CacheKey.SCRIPT]: ScriptCacheMeta[];
+    [CacheKey.STYLE]: StyleCacheMeta[];
+    [CacheKey.ASSET]: FileCacheMeta[];
+}
+type Vue2ReactCacheMeta = Omit<SFCUnit, 'source'>;
+type ScriptCacheMeta = Omit<ScriptUnit, 'source'>;
+type StyleCacheMeta = Omit<StyleUnit, 'source'>;
+interface FileCacheMeta extends FileMeta {
+    file: string;
+}
+interface FileMeta {
+    fileSize: number;
+    mtime: number;
+    hash?: string;
+}
+interface CacheCheckResult {
+    shouldCompile: boolean;
+    hash?: string;
+}
+
+type CompilationResult = SFCCompilationResult | ScriptCompilationResult | StyleCompilationResult;
+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 StyleCompilationResult extends Omit<BaseCompilationResult, 'hasRoute' | keyof GeneratorResult> {
+    code: string;
+    fileInfo: {
+        style: {
+            file: string;
+            lang: string;
+        };
+    };
+}
+interface BaseCompilationResult extends GeneratorResult {
+    fileId: string;
+    hasRoute?: boolean;
+}
+
 type LangType = 'js' | 'jsx' | 'ts' | 'tsx';
 
 type ReactiveTypes = 'ref' | 'reactive' | 'indirect' | 'none';
@@ -122,434 +261,24 @@ interface IPropsContext {
     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[];
+type CompilerPlugins = PluginRegister<CompilationResult> & {
+    /**
+     * Register parser plugins
+     */
+    parser?: PluginRegister<ParseResult>;
+    /**
+     * Register transformer plugins
+     */
+    transformer?: PluginRegister<ReactIRDescriptor>;
+    /**
+     * Register codegen plugins
+     */
+    codegen?: PluginRegister<GeneratorResult>;
+};
+interface PluginRegister<T> {
+    [name: string]: (result: T, ctx: ICompilationContext) => void;
 }
 
-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.
@@ -570,47 +299,10 @@ interface CompilerOptions {
      * @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[];
-    };
+    /**
+     * @see {@link OutputConfig}
+     */
+    output?: OutputConfig;
     /**
      * Excluded file/directory matching patterns (glob syntax supported).
      * @default
@@ -630,6 +322,7 @@ interface CompilerOptions {
     recursive?: boolean;
     /**
      * Options passed through to babel-generator.
+     * @see {@link GeneratorOptions}
      */
     generate?: GeneratorOptions$1;
     /**
@@ -642,10 +335,36 @@ interface CompilerOptions {
      * @default true
      */
     preprocessStyles?: boolean;
+    /**
+     * Specify the path to the Vue Router config file
+     * The file must default export createRouter
+     * Used to inject Router Provider in React's main.tsx or main.jsx
+     *
+     *
+     *
+     * @see {@link RouterConfig}
+     *
+     * @example
+     * ```js
+     * router: {
+     *   configFile: 'src/router/index.ts'
+     * }
+     * ```
+     *
+     * Assumes the config file default exports createRouter:
+     *
+     * ```js
+     * // src/router/index.ts
+     * export default createRouter({ ... })
+     * ```
+     */
+    router?: RouterConfig;
     /**
      * Can be used to add plugins and customize the output results of
      * the parse/transform/codegen/compiled stages respectively.
      *
+     * @see {@link CompilerPlugins}
+     *
      * @example
      * ```ts
      * plugins: {
@@ -666,50 +385,16 @@ interface CompilerOptions {
      * }
      * ```
      */
-    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;
-    };
+    plugins?: CompilerPlugins;
+    /**
+     * @see {@link FormatConfig}
+     */
+    format?: FormatConfig;
     /**
      * Log Control Options
+     * @see {@link LoggingConfig}
      */
-    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;
-    };
+    logging?: LoggingConfig;
     /**
      * Execute only after the first successful full compilation.
      */
@@ -722,107 +407,130 @@ interface CompilerOptions {
      */
     onChange?: (event: 'add' | 'change', unit: CompilationUnit) => Promise<void | undefined>;
 }
-interface PluginRegister<T> {
-    [name: string]: (result: T, ctx: ICompilationContext) => void;
-}
-type CompilationResult = SFCCompilationResult | ScriptCompilationResult | StyleCompilationResult;
-interface SFCCompilationResult extends BaseCompilationResult {
-    fileInfo: {
-        jsx: {
-            file: string;
-            lang: string;
-        };
-        css: {
-            file?: string;
-            hash?: string;
-            code?: string;
-        };
+interface OutputConfig {
+    /**
+     * 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 | {
+        /**
+         * Specify the React template type.
+         * @default 'react-ts'
+         */
+        template?: 'react-ts' | 'react';
+        /**
+         * Specify the Vite version for initial installation, which must start with '@'.
+         * @default '@latest'
+         *
+         * @example
+         *
+         * ```js
+         * { vite: '@7' }
+         * ```
+         */
+        vite?: string;
+        /**
+         * Specify the React version for initial installation.
+         * @default 'latest'
+         *
+         * @example
+         *
+         * ```js
+         * { react: '^19.2.0' }
+         * ```
+         */
+        react?: string;
     };
+    /**
+     * 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.',
+     *  '.vue',
+     *  'vureact.config.js',
+     *  'vureact.config.ts',
+     * ]
+     */
+    ignoreAssets?: string[];
+    /**
+     * Customize the generated package.json file.
+     * This function receives the default package.json object
+     * and should return the modified version.
+     *
+     * @note This option only takes effect when `bootstrapVite` is enabled.
+     *
+     * @example
+     * ```js
+     * packageJson: (defaultPkg) => {
+     *   // Modify and return the copy
+     *   defaultPkg.dependencies['my-library'] = '^1.0.0';
+     *   return defaultPkg;
+     * }
+     * ```
+     */
+    packageJson?: (defaultPkg: Record<string, any>) => Record<string, any>;
 }
-interface ScriptCompilationResult extends BaseCompilationResult {
-    fileInfo: {
-        script: {
-            file: string;
-            lang: string;
-        };
-    };
+interface RouterConfig {
+    /**
+     * Path to the Vue Router config file.
+     * Must be the location where `createRouter` is **exported as default**.
+     */
+    configFile: string;
+    /**
+     * Automatically update the react app entry file to use the VuReact Router Provider.
+     *
+     * Note: Injection only occurs when `output.bootstrapVite` is enabled.
+     *
+     * @default true
+     */
+    autoUpdateEntry?: boolean;
 }
-interface StyleCompilationResult extends Omit<BaseCompilationResult, 'hasRoute' | keyof GeneratorResult> {
-    code: string;
-    fileInfo: {
-        style: {
-            file: string;
-            lang: string;
-        };
-    };
+interface FormatConfig {
+    /**
+     * @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;
 }
-interface BaseCompilationResult extends GeneratorResult {
-    fileId: string;
-    hasRoute?: boolean;
-}
-type CompilationUnit = SFCUnit | ScriptUnit | StyleUnit;
-interface SFCUnit extends BaseUnit {
-    type: CacheKey.SFC;
-    output?: {
-        jsx: OutputItem;
-        css: Partial<OutputItem>;
-    };
-}
-interface ScriptUnit extends BaseUnit {
-    type: CacheKey.SCRIPT;
-    output?: {
-        script: OutputItem;
-    };
-}
-interface StyleUnit extends Omit<BaseUnit, 'hasRoute'> {
-    type: CacheKey.STYLE;
-    output?: {
-        style: OutputItem;
-    };
-}
-interface AssetUnit extends Omit<BaseUnit, 'fileId' | 'source' | 'hasRoute'> {
-    type: CacheKey.ASSET;
-}
-interface BaseUnit extends FileMeta {
-    file: string;
-    fileId: string;
-    source: string;
-    hasRoute?: boolean;
-}
-interface OutputItem {
-    file: string;
-    code: string;
-}
-type LoadedCache<T = CacheMeta> = {
-    key: CacheKey;
-    target: T[];
-    source: CacheList;
-};
-type CacheMeta = Vue2ReactCacheMeta | FileCacheMeta;
-declare enum CacheKey {
-    SFC = "sfc",
-    SCRIPT = "script",
-    STYLE = "style",
-    ASSET = "copied"
-}
-interface CacheList {
-    [CacheKey.SFC]: Vue2ReactCacheMeta[];
-    [CacheKey.SCRIPT]: FileCacheMeta[];
-    [CacheKey.STYLE]: 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;
+interface LoggingConfig {
+    /**
+     * @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;
 }
 
 declare class Helper {
@@ -845,8 +553,9 @@ declare class Helper {
     isSingleFile(): boolean;
     /**
      * 获取输出文件的路径。如：'[root]/.vureact/dist/'
+     * @param addInput 会输出如：'[root]/.vureact/dist/[input]/'
      */
-    getOuputPath(): string;
+    getOuputPath(addInput?: boolean): string;
     getOutDirName(): string;
     getWorkspaceDir(): string;
     /**
@@ -898,9 +607,16 @@ declare class Helper {
      */
     compareFileMeta(a: FileMeta, b: FileMeta): boolean;
     /**
-     * 统一的写文件方法，包含自动创建目录
+     * 统一的写文件方法，包含自动创建目录（带文件互斥锁可选）
+     * @param filePath - 要写入的文件路径
+     * @param content - 要写入的内容
+     * @param options - 可选配置项
+     * @param options.lock - 是否启用文件锁（默认false）
      */
-    writeFileWithDir(filePath: string, content: string): Promise<void>;
+    writeFileWithDir(filePath: string, content: string, options?: FileLockOptions & {
+        lock?: boolean;
+    }): Promise<void>;
+    rmFile(filePath: string): Promise<void>;
     /**
      * 加载指定文件的缓存内容
      * @param key 缓存键
@@ -925,7 +641,6 @@ declare class Helper {
     getFileMeta(filePath: string): Promise<FileMeta>;
     removeOutputFile(filePath: string, resolveOutputPath?: boolean): Promise<void>;
     updateCache(targetFile: string, newData: any, cache: LoadedCache): void;
-    resolveViteCreateApp(): void;
     /**
      * 获取需要排除编译的文件
      */
@@ -940,460 +655,263 @@ declare class Helper {
      * 读取 package.json 文件内容，并处理成对象返回
      */
     resolvePackageFile(path: string): Promise<Record<string, any>>;
+    /**
+     * 获取目录到文件的相对路径
+     * @returns 结果路径不包含文件拓展名，并以诸如 ./ 开头
+     */
+    resolveRelativePath(from: string, to: string): string;
 }
 
 /**
- * 基础编译器类，提供 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. 插件执行：在各阶段执行注册的插件，支持自定义扩展
+ * 基础编译器类 - Vue 到 React 代码转换的核心实现
  *
- * @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} 编译结果的数据结构
+ * 继承自 Helper，提供单文件编译功能，支持插件系统和三阶段编译流程。
+ * 主要用于文件系统批量编译和单文件编译场景。
  */
 declare class BaseCompiler extends Helper {
     version: string;
     options: CompilerOptions;
     private createContext;
+    constructor(options?: CompilerOptions);
+    /** 编译 Vue 源代码为 React 代码 */
+    compile(source: string, filename: string): CompilationResult;
+    private prepareGenerateOptions;
+    private resolveMainResult;
+    private resolveStyleResult;
+}
+
+declare class CleanupManager {
+    private fileCompiler;
+    constructor(fileCompiler: FileCompiler);
     /**
-     * 创建基础编译器实例
-     *
-     * @param options - 编译器配置选项，包括缓存设置、插件配置、样式预处理等，
-     * 所有选项都会传递给父类 {@link Helper} 进行初始化
-     *
-     * @see {@link CompilerOptions} 查看完整的配置选项说明
+     * Delete the build artifacts and cache corresponding to the specified path.
      */
-    constructor(options?: CompilerOptions);
+    removeOutputPath(targetPath: string, type: CacheKey): Promise<void>;
     /**
-     * 编译 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);
-     * ```
-     *
-     * @throws 不会直接抛出异常，错误通过日志系统记录
-     * @see {@link parse} 解析函数
-     * @see {@link transform} 转换函数
-     * @see {@link generate} 生成函数
-     * @see {@link executePlugins} 插件执行函数
+     * Delete the build artifacts or asset files and cache corresponding to the specified path.
      */
-    compile(source: string, filename: string): CompilationResult;
+    cleanupOldOutput(key: CacheKey, filter: (m: CacheMeta) => boolean): Promise<void>;
+}
+
+declare class AssetManager {
+    private fileCompiler;
+    private cleanupManager;
+    pipelineFiles: string[];
+    private skippedCount;
+    constructor(fileCompiler: FileCompiler, cleanupManager: CleanupManager);
     /**
-     * 初始化 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;
+    runAssetPipeline(): Promise<number>;
     /**
-     * 处理 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 编译结果类型
+     * Process single asset file, compare with cache and decide whether to copy.
      */
-    private resolveMainResult;
+    processAsset(filePath: string, existingCache?: LoadedCache<FileCacheMeta>): Promise<FileCacheMeta | undefined>;
     /**
-     * 处理 Style 文件的编译结果
-     * @param data style 文件解析结果
-     * @param ctxData 上下文数据
+     * 更新缓存
      */
-    private resolveStyleResult;
+    private updateCache;
+    /**
+     * 获取跳过的文件数量
+     */
+    getSkippedCount(): number;
+    /**
+     * 重置跳过的文件数量
+     */
+    resetSkippedCount(): void;
 }
 
-/**
- * 文件系统编译器，负责将 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;
+declare class CacheManager {
+    private fileCompiler;
+    private pendingUpdates;
+    constructor(fileCompiler: FileCompiler);
     /**
-     * 创建文件系统编译器实例
-     *
-     * @param options - 编译器配置选项，继承自 BaseCompiler 的选项
-     *                 包括输入路径、输出配置、缓存设置、排除模式等
-     * @see {@link CompilerOptions} 查看完整的选项说明
+     * 批量更新缓存记录
      */
-    constructor(options?: CompilerOptions);
+    updateCacheIncrementally(unit: CompilationUnit, key: CacheKey): Promise<void>;
     /**
-     * 初始化所有管理器实例
-     *
-     * 按照依赖关系顺序创建各个管理器：
-     * 1. 基础管理器（无依赖）
-     * 2. 依赖基础管理器的管理器
-     * 3. 依赖其他管理器的管理器
-     *
-     * @private
+     * 批量保存缓存
      */
-    private initializeManagers;
+    flushCache(key: CacheKey): Promise<void>;
     /**
-     * 执行完整的编译流程
-     *
-     * 该方法执行以下步骤：
-     * 1. 环境初始化：清理旧输出（如果禁用缓存）并初始化 Vite 项目环境
-     * 2. Vue 文件编译：批量处理所有 .vue 文件
-     * 3. Script 文件编译：批量处理所有 .js/.ts 文件
-     * 4. 资源文件拷贝：处理剩余的非编译文件
-     * 5. 统计输出：显示编译结果和性能统计
-     *
-     * @async
-     * @throws {Error} 当编译过程中发生致命错误时抛出
-     * @returns {Promise<void>}
+     * 更新缓存
      */
-    execute(): Promise<void>;
+    private updateCache;
+}
+
+declare class CompilationUnitProcessor {
+    private fileCompiler;
+    constructor(fileCompiler: FileCompiler);
     /**
-     * 运行管线并显示加载动画
-     *
-     * @private
-     * @param text - 加载动画显示的文本
-     * @param pipelineFn - 要执行的管线函数
-     * @returns 返回的处理的文件数
+     * 处理编译单元，落地成对应代码和文件
      */
-    private runPipelineWithSpinner;
+    resolve(unit: CompilationUnit, key: CacheKey): Promise<CompilationUnit>;
+    private resolveResult;
     /**
-     * 处理单个 Vue 单文件组件（SFC）
-     *
-     * 此方法主要用于 CLI 的 watch 模式，当检测到文件变更时调用。
-     * 支持增量编译，如果文件未变更则跳过编译。
-     *
-     * @async
-     * @param filePath - Vue 文件的绝对路径
-     * @param existingCache - 可选的预加载缓存对象，用于增量编译
-     * @returns {Promise<SFCUnit | undefined>} 编译单元对象，如果跳过编译则返回 undefined
-     * @see {@link FileProcessor.processSFC}
+     * 将编译产物写入磁盘
+     */
+    saveCompiledFiles(unit: CompilationUnit, key: CacheKey): Promise<void>;
+}
+
+declare class FileProcessor {
+    private fileCompiler;
+    private compilationUnitProcessor;
+    private cacheManager;
+    private skippedCount;
+    constructor(fileCompiler: FileCompiler, compilationUnitProcessor: CompilationUnitProcessor, cacheManager: CacheManager);
+    /**
+     * Process a single Vue file (this method is called directly in CLI Watch mode)
      */
     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}
+     * Process a single script file (this method is called directly in CLI Watch mode)
      */
     processScript(filePath: string, existingCache?: LoadedCache<FileCacheMeta>): Promise<ScriptUnit | undefined>;
     /**
-     * 处理单个 CSS/LESS/SCSS 样式文件
-     *
-     * 此方法主要用于 CLI 的 watch 模式，当检测到文件变更时调用。
-     * 支持增量编译，如果文件未变更则跳过编译。
-     *
-     * @async
-     * @param filePath - style 文件的绝对路径
-     * @param existingCache - 可选的预加载缓存对象，用于增量编译
-     * @returns {Promise<ScriptUnit | undefined>} 编译单元对象，如果跳过编译则返回 undefined
-     * @see {@link FileProcessor.processStyle}
+     * Process a single style file (this method is called directly in CLI Watch mode)
      */
     processStyle(filePath: string, existingCache?: LoadedCache<FileCacheMeta>): Promise<StyleUnit | undefined>;
     /**
-     * 处理单个文件（Vue 或 Script）
-     *
-     * 通用的文件处理方法，根据 CacheKey 类型自动选择处理逻辑。
-     * 主要用于内部调用和统一的文件处理接口。
-     *
-     * @async
-     * @param key - 文件类型标识（SFC 或 SCRIPT）
-     * @param filePath - 文件的绝对路径
-     * @param existingCache - 可选的预加载缓存对象
-     * @returns {Promise<SFCUnit | ScriptUnit | undefined>} 编译单元对象
-     * @see {@link FileProcessor.processFile}
+     * Process a single vue file
      */
-    processFile(key: CacheKey, filePath: string, existingCache?: LoadedCache): Promise<CompilationUnit | undefined>;
+    processFile(key: CacheKey.SFC, filePath: string, existingCache?: LoadedCache<Vue2ReactCacheMeta>): Promise<SFCUnit | undefined>;
     /**
-     * 处理单个资源文件
-     *
-     * 比较文件与缓存，决定是否需要拷贝。
-     * 资源文件包括图片、字体、样式文件等非编译文件。
-     *
-     * @async
-     * @param filePath - 资源文件的绝对路径
-     * @param existingCache - 可选的预加载缓存对象
-     * @returns {Promise<FileCacheMeta>} 资源文件的缓存元数据
-     * @see {@link AssetManager.processAsset}
+     * Process a single script file
      */
-    processAsset(filePath: string, existingCache?: LoadedCache<FileCacheMeta>): Promise<FileCacheMeta>;
+    processFile(key: CacheKey.SCRIPT, filePath: string, existingCache?: LoadedCache<FileCacheMeta>): Promise<ScriptUnit | undefined>;
     /**
-     * 删除指定路径对应的输出文件和缓存
-     *
-     * 当源文件被删除或重命名时，需要清理对应的输出文件。
-     * 主要用于 watch 模式下的文件删除处理。
-     *
-     * @async
-     * @param targetPath - 源代码的路径（文件或文件夹）
-     * @param type - 清理类型，指定是 SFC、SCRIPT 还是 ASSET
-     * @returns {Promise<void>}
-     * @see {@link CleanupManager.removeOutputPath}
+     * Process a single style file
      */
-    removeOutputPath(targetPath: string, type: CacheKey): Promise<void>;
+    processFile(key: CacheKey.STYLE, filePath: string, existingCache?: LoadedCache<FileCacheMeta>): Promise<StyleUnit | undefined>;
+    /**
+     * Process a single vue/script/style file
+     */
+    processFile(key: CacheKey, filePath: string, existingCache?: LoadedCache<FileCacheMeta>): Promise<CompilationUnit | undefined>;
+    /**
+     * 对 package.json 注入路由依赖项
+     */
+    private addRouterToPackageJson;
+    /**
+     * 注入路由提供器到 React 应用的入口文件（如 main.tsx）
+     */
+    private updateEntryWithRouterProvider;
     /**
      * 获取跳过的文件数量
-     *
-     * 在增量编译中，未变更的文件会被跳过。
-     * 此方法返回当前编译会话中跳过的文件数量。
-     *
-     * @returns {number} 跳过的文件数量
      */
     getSkippedCount(): number;
     /**
      * 重置跳过的文件数量
-     *
-     * 在每次新的编译会话开始时调用，重置计数器。
      */
     resetSkippedCount(): void;
+}
+
+declare class PipelineManager {
+    private fileCompiler;
+    private fileProcessor;
+    private skippedCount;
+    private cleanupManager;
+    constructor(fileCompiler: FileCompiler, fileProcessor: FileProcessor);
     /**
-     * 显示编译统计信息
-     *
-     * 在编译完成后调用，显示以下信息：
-     * 1. 编译耗时
-     * 2. 输出目录
-     * 3. 跳过的文件数量
-     * 4. 处理的文件分类统计
-     *
-     * @private
-     * @param endTime - 格式化后的编译耗时字符串
-     * @param sfcCount - 处理的 Vue 文件数量
-     * @param scriptCount - 处理的脚本文件数量
-     * @param assetCount - 处理的资源文件数量
+     * 运行 SFC 编译管线
      */
+    runSfcPipeline(): Promise<number>;
+    /**
+     * 运行 Script 编译管线
+     */
+    runScriptPipeline(): Promise<number>;
+    /**
+     * 运行 Style 编译管线
+     */
+    runStylePipeline(): Promise<number>;
+    /**
+     * 核心编译管线
+     */
+    private runCorePipeline;
+    /**
+     * 获取跳过的文件数量
+     */
+    getSkippedCount(): number;
+    /**
+     * 重置跳过的文件数量
+     */
+    resetSkippedCount(): void;
+}
+
+/**
+ * Vite 环境初始化管理器
+ */
+declare class ViteBootstrapper {
+    private fileCompiler;
+    private options;
+    private spinner;
+    private defaultConfig;
+    constructor(fileCompiler: FileCompiler, options: CompilerOptions);
+    /**
+     * 检查是否需要初始化 Vite 环境
+     */
+    private isSingleFile;
+    /**
+     * 利用 Vite 官方脚手架创建标准 React 环境
+     */
+    bootstrapIfNeeded(): Promise<boolean | undefined>;
+    /**
+     * 执行 vite 创建命令
+     */
+    private resolveViteCreateApp;
+    /**
+     * 处理 React 包版本
+     * @param ver 版本号
+     */
+    private resolveReactVersion;
+}
+
+interface CompilerManager {
+    viteBootstrapper: ViteBootstrapper;
+    fileProcessor: FileProcessor;
+    pipelineManager: PipelineManager;
+    assetManager: AssetManager;
+    cacheManager: CacheManager;
+    cleanupManager: CleanupManager;
+}
+
+/**
+ * 文件系统编译器 - 将 Vue 项目批量转换为 React 项目
+ *
+ * 提供完整的文件系统级别编译功能，包括 SFC、脚本、样式编译，
+ * 资源拷贝、增量编译、缓存管理和 Vite 环境初始化。
+ */
+declare class FileCompiler extends BaseCompiler {
+    manager: CompilerManager;
+    private spinner;
+    constructor(options?: CompilerOptions);
+    /** 执行完整的编译流程 */
+    execute(): Promise<void>;
+    /** 处理单个 Vue 单文件组件（SFC） */
+    processSFC(filePath: string, existingCache?: LoadedCache<Vue2ReactCacheMeta>): Promise<SFCUnit | undefined>;
+    /** 处理单个 JavaScript/TypeScript 脚本文件 */
+    processScript(filePath: string, existingCache?: LoadedCache<FileCacheMeta>): Promise<ScriptUnit | undefined>;
+    /** 处理单个 CSS/LESS/SCSS 样式文件 */
+    processStyle(filePath: string, existingCache?: LoadedCache<FileCacheMeta>): Promise<StyleUnit | undefined>;
+    /** 处理单个文件（Vue 或 Script） */
+    processFile(key: CacheKey, filePath: string, existingCache?: LoadedCache): Promise<CompilationUnit | undefined>;
+    /** 处理单个资源文件 */
+    processAsset(filePath: string, existingCache?: LoadedCache<FileCacheMeta>): Promise<FileCacheMeta | undefined>;
+    /** 批量保存缓存 */
+    flushCache(key: CacheKey): Promise<void>;
+    /** 删除指定路径对应的输出文件和缓存 */
+    removeOutputPath(targetPath: string, type: CacheKey): Promise<void>;
+    private runPipelineWithSpinner;
     private showCompileStats;
+    private resetSkippedCount;
 }
 
 /**
- * @see {@link CompilerOptions}
+ * Type helper to make it easier to use vureact.config.js
+ * accepts a direct {@link UserConfig} object, or a function that returns it.
  */
-declare function defineConfig(options: CompilerOptions): CompilerOptions;
+declare function defineConfig(config: CompilerOptions): CompilerOptions;
+declare function defineConfig(config: UserConfigFnObject): CompilerOptions;
+type UserConfigFnObject = () => CompilerOptions;
 
 /**
  * Next Vue to React compiler, compiles Vue 3 syntax into runnable React 18+ code.
@@ -1406,4 +924,241 @@ declare function defineConfig(options: CompilerOptions): CompilerOptions;
 declare class VuReact extends FileCompiler {
 }
 
-export { type AssetUnit, type BaseCompilationResult, BaseCompiler, type BaseUnit, 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 StyleCompilationResult, type StyleUnit, type TransformerOptions, VuReact, type Vue2ReactCacheMeta, defineConfig, generate, generateComponent, generateOnlyScript, parse, parseOnlyScript, parseSFC, transform };
+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 不会直接抛出异常，错误信息会通过日志系统记录
+ */
+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 中间表示描述符，包含模板、脚本和样式的转换结果
+ */
+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、生成的代码和原始源码引用
+ */
+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;
+
+export { type AssetUnit, type BaseCompilationResult, BaseCompiler, type BaseUnit, type CacheCheckResult, CacheKey, type CacheList, type CacheMeta, type CompilationResult, type CompilationUnit, type CompilerOptions, type CompilerPlugins, type FileCacheMeta, FileCompiler, type FileMeta, type FormatConfig, type GeneratorOptions, type GeneratorResult, Helper, type LoadedCache, type LoggingConfig, type OutputConfig, type ParseResult, type ParserOptions, type PluginRegister, type ReactIRDescriptor, type RouterConfig, type SFCCompilationResult, type SFCUnit, type ScriptCacheMeta, type ScriptCompilationResult, type ScriptUnit, type StyleCacheMeta, type StyleCompilationResult, type StyleUnit, type TransformerOptions, type UserConfigFnObject, VuReact, type Vue2ReactCacheMeta, defineConfig, generate, generateComponent, generateOnlyScript, parse, parseOnlyScript, parseSFC, transform };