@vitarx/plugin-vite 1.0.0 → 1.0.2-alpha.0

package/dist/utils/component-collect.js

@@ -5,56 +5,121 @@
  */
 import * as t from '@babel/types';
 import { DEFAULT_EXPORT_BASE_NAME } from '../constants/index.js';
+// 导入名称收集相关工具函数
+import { collectAllBindingNames, collectBuilderWrappedNames, collectExportedNames, isBuilderCall } from './collect-names.js';
 import { generateUniqueAlias } from './generate.js';
-import { collectExportedNames, collectAllBindingNames, collectBuilderWrappedNames, isBuilderCall } from './collect-names.js';
 /**
  * 生成唯一的默认导出组件名称
  * 避免与已存在的名称冲突
  */
 function generateUniqueDefaultName(exportedNames) {
+    // 如果默认名称未被占用，直接返回
     if (!exportedNames.has(DEFAULT_EXPORT_BASE_NAME)) {
         return DEFAULT_EXPORT_BASE_NAME;
     }
+    // 否则生成唯一别名
     return generateUniqueAlias(DEFAULT_EXPORT_BASE_NAME, exportedNames);
 }
 /**
  * 检查名称是否为有效的组件名称
- * 必须以大写字母开头
+ * 必须以大写字母开头（符合 React/Vue 组件命名规范）
  */
 function isValidComponentName(name) {
+    // 使用正则表达式检查首字母是否为大写
     return /^[A-Z]/.test(name);
 }
+/**
+ * 尝试添加组件信息到组件列表中
+ *
+ * @param name 组件名称
+ * @param node 函数声明节点，可以是函数声明、箭头函数表达式或函数表达式
+ * @param exportedNames 已导出的名称集合
+ * @param components 组件信息数组，用于存储符合条件的组件信息
+ * @param builderWrappedNames 已被包装器包装的函数名称集合，默认为空集合
+ */
 function tryAddComponent(name, node, exportedNames, components, builderWrappedNames = new Set()) {
+    // 检查组件名称是否有效（大写开头）且是否已导出
     if (isValidComponentName(name) && exportedNames.has(name)) {
+        // 判断组件是否已被 builder/defineComponent 等包装器包装
         const isWrapped = builderWrappedNames.has(name);
+        // 将组件信息添加到组件数组中
         components.push({ name, node, isWrapped });
     }
 }
 /**
  * 处理变量声明中的组件
+ * 提取变量赋值中的箭头函数、函数表达式或 builder 包装调用作为组件
+ * @param declaration - 变量声明节点
+ * @param exportedNames - 已导出的名称集合
+ * @param components - 组件信息数组
+ * @param builderWrappedNames - 已被包装器包装的函数名称集合
+ * @param program - AST Program 节点，用于插入提取的函数声明
+ * @param builderAlias - builder 的本地别名
+ * @param allBindingNames - 所有绑定名称集合（用于生成唯一名称时避免冲突）
  */
-function processVariableDeclaration(declaration, exportedNames, components, builderWrappedNames = new Set()) {
+function processVariableDeclaration(declaration, exportedNames, components, builderWrappedNames = new Set(), program, builderAlias, allBindingNames) {
+    // 遍历变量声明中的每个声明
     for (const decl of declaration.declarations) {
+        // 跳过非标识符的变量名（如解构赋值）
         if (decl.id.type !== 'Identifier')
             continue;
         const init = decl.init;
         if (init?.type === 'ArrowFunctionExpression' || init?.type === 'FunctionExpression') {
+            // 检查初始值是否为箭头函数或函数表达式
             tryAddComponent(decl.id.name, init, exportedNames, components, builderWrappedNames);
         }
+        else if (init?.type === 'CallExpression' &&
+            program &&
+            builderAlias != null &&
+            allBindingNames) {
+            // 处理 builder 包装的变量声明：const App = builder(() => <div/>)
+            // 仅处理已导出且名称合法的变量
+            if (!isValidComponentName(decl.id.name) || !exportedNames.has(decl.id.name))
+                continue;
+            const result = extractFunctionFromVariableInit(init, decl.id.name, allBindingNames, builderAlias);
+            if (result) {
+                // 找到包含该变量声明的语句在 program.body 中的位置
+                const stmtIndex = program.body.findIndex(stmt => {
+                    if (stmt === declaration)
+                        return true;
+                    // 变量声明可能在 ExportNamedDeclaration 内部
+                    return stmt.type === 'ExportNamedDeclaration' && stmt.declaration === declaration;
+                });
+                // 将提取的函数声明插入到变量声明之前
+                if (stmtIndex !== -1) {
+                    program.body.splice(stmtIndex, 0, result.funcNode);
+                }
+                // 直接添加为包装组件（不经过 tryAddComponent，因为内部函数名不在 exportedNames 中）
+                components.push({
+                    name: result.name,
+                    node: result.funcNode,
+                    isWrapped: result.isBuilderWrapped
+                });
+            }
+        }
     }
 }
 /**
  * 将函数表达式或箭头函数转换为命名函数声明
+ * 用于将匿名函数转换为可追踪的命名函数
  */
 function convertToNamedFunctionDeclaration(func, name) {
     let body;
+    // 处理箭头函数的隐式返回：将表达式体包装为显式 return 语句
     if (func.type === 'ArrowFunctionExpression' && func.body.type !== 'BlockStatement') {
         body = t.blockStatement([t.returnStatement(func.body)]);
     }
     else {
         body = func.body;
     }
-    const funcDecl = t.functionDeclaration(t.identifier(name), func.params, body, func.type === 'FunctionExpression' ? func.generator : false, func.async);
+    // 创建函数声明节点
+    const funcDecl = t.functionDeclaration(t.identifier(name), // 函数名称
+    func.params, // 参数列表
+    body, // 函数体
+    func.type === 'FunctionExpression' ? func.generator : false, // 是否为生成器
+    func.async // 是否为异步函数
+    );
+    // 保留原始位置信息用于源码映射
     funcDecl.loc = func.loc;
     return funcDecl;
 }
@@ -69,16 +134,56 @@ function convertToNamedFunctionDeclaration(func, name) {
  * @returns 提取结果，包含名称、函数声明节点和是否是 builder 包装
  */
 function extractFunctionFromCallExpression(callExpr, exportedNames, builderAlias) {
+    // 判断是否为 builder 函数调用
     const isBuilder = isBuilderCall(callExpr, builderAlias);
+    // 遍历调用表达式的所有参数
     for (let i = 0; i < callExpr.arguments.length; i++) {
         const arg = callExpr.arguments[i];
+        // 找到作为参数传入的匿名函数
         if (arg.type === 'ArrowFunctionExpression' || arg.type === 'FunctionExpression') {
+            // 生成唯一名称
             const name = generateUniqueDefaultName(exportedNames);
+            // 转换为命名函数声明
+            const funcNode = convertToNamedFunctionDeclaration(arg, name);
+            // 将原参数替换为标识符引用
+            callExpr.arguments[i] = t.identifier(name);
+            return { name, funcNode, isBuilderWrapped: isBuilder };
+        }
+    }
+    // 未找到可提取的函数参数
+    return null;
+}
+/**
+ * 从变量声明的调用表达式中提取函数
+ * 将 const App = builder(() => <div/>) 转换为：
+ * function App$1() { return <div/> }
+ * const App = builder(App$1)
+ * @param callExpr - 调用表达式
+ * @param variableName - 变量名（作为内部函数名的基础）
+ * @param allBindingNames - 所有绑定名称集合（用于避免命名冲突）
+ * @param builderAlias - builder 的本地别名
+ * @returns 提取结果，包含名称、函数声明节点和是否是 builder 包装
+ */
+function extractFunctionFromVariableInit(callExpr, variableName, allBindingNames, builderAlias) {
+    // 判断是否为 builder 函数调用
+    const isBuilder = isBuilderCall(callExpr, builderAlias);
+    // 遍历调用表达式的所有参数
+    for (let i = 0; i < callExpr.arguments.length; i++) {
+        const arg = callExpr.arguments[i];
+        // 找到作为参数传入的匿名函数
+        if (arg.type === 'ArrowFunctionExpression' || arg.type === 'FunctionExpression') {
+            // 以变量名为基础生成唯一别名，避免与已有名称冲突
+            const name = generateUniqueAlias(variableName, allBindingNames);
+            // 将新名称加入集合，防止后续生成重复名称
+            allBindingNames.add(name);
+            // 转换为命名函数声明
             const funcNode = convertToNamedFunctionDeclaration(arg, name);
+            // 将原参数替换为标识符引用
             callExpr.arguments[i] = t.identifier(name);
             return { name, funcNode, isBuilderWrapped: isBuilder };
         }
     }
+    // 未找到可提取的函数参数
     return null;
 }
 /**
@@ -95,69 +200,139 @@ function processAnonymousDefaultExport(node, program, exportedNames, components,
     let funcNode = null;
     let name;
     let isWrapped = false;
+    // 处理无名称的函数声明 export default function() {}
     if (decl.type === 'FunctionDeclaration' && !decl.id) {
         name = generateUniqueDefaultName(exportedNames);
         decl.id = t.identifier(name);
         funcNode = decl;
     }
     else if (decl.type === 'FunctionExpression') {
+        // 处理函数表达式 export default function() {}
         name = generateUniqueDefaultName(exportedNames);
         funcNode = convertToNamedFunctionDeclaration(decl, name);
         node.declaration = funcNode;
     }
     else if (decl.type === 'ArrowFunctionExpression') {
+        // 处理箭头函数 export default () => {}
         name = generateUniqueDefaultName(exportedNames);
         funcNode = convertToNamedFunctionDeclaration(decl, name);
         node.declaration = funcNode;
     }
     else if (decl.type === 'CallExpression') {
+        // 处理包装调用 export default builder(() => {})
         const result = extractFunctionFromCallExpression(decl, exportedNames, builderAlias);
         if (result) {
             name = result.name;
             funcNode = result.funcNode;
             isWrapped = result.isBuilderWrapped;
+            // 将提取的函数声明插入到导出语句之前
             const exportIndex = program.body.indexOf(node);
             if (exportIndex !== -1) {
                 program.body.splice(exportIndex, 0, funcNode);
             }
         }
     }
+    // 如果成功提取到函数节点，添加到组件列表
     if (funcNode) {
         components.push({ name: name, node: funcNode, isWrapped });
     }
 }
+/**
+ * 在 program.body 中查找指定名称的变量声明
+ * 用于处理 export default X 场景，追溯标识符对应的变量声明
+ * @param program - AST Program 节点
+ * @param name - 要查找的变量名
+ * @returns 包含变量声明和所在语句的对象，未找到返回 null
+ */
+function findVariableDeclaration(program, name) {
+    for (const stmt of program.body) {
+        // 查找普通变量声明
+        if (stmt.type === 'VariableDeclaration') {
+            for (const decl of stmt.declarations) {
+                if (decl.id.type === 'Identifier' && decl.id.name === name) {
+                    return { decl, statement: stmt };
+                }
+            }
+        }
+        // 查找命名导出中的变量声明
+        if (stmt.type === 'ExportNamedDeclaration' &&
+            stmt.declaration?.type === 'VariableDeclaration') {
+            for (const decl of stmt.declaration.declarations) {
+                if (decl.id.type === 'Identifier' && decl.id.name === name) {
+                    return { decl, statement: stmt };
+                }
+            }
+        }
+    }
+    return null;
+}
 /**
  * 收集模块中的组件函数
+ * 遍历 AST 程序节点，提取所有导出的组件函数
  * @param program - AST Program 节点
  * @param builderAlias - builder 函数的本地别名（用于识别纯构建组件）
  * @returns 组件信息数组
  */
 export function collectComponentFunctions(program, builderAlias = null) {
+    // 收集所有已导出的名称
     const exportedNames = collectExportedNames(program);
+    // 收集所有绑定名称（用于生成唯一名称时避免冲突）
     const allBindingNames = collectAllBindingNames(program);
+    // 收集被 builder 包装的函数名称
     const builderWrappedNames = collectBuilderWrappedNames(program, builderAlias);
+    // 存储收集到的组件信息
     const components = [];
+    // 遍历程序体中的所有节点
     for (const node of program.body) {
+        // 处理普通函数声明 function Component() {}
         if (node.type === 'FunctionDeclaration' && node.id) {
             tryAddComponent(node.id.name, node, exportedNames, components, builderWrappedNames);
         }
         else if (node.type === 'VariableDeclaration') {
-            processVariableDeclaration(node, exportedNames, components, builderWrappedNames);
+            // 处理变量声明 const Component = () => {} 或 const App = builder(() => {})
+            processVariableDeclaration(node, exportedNames, components, builderWrappedNames, program, builderAlias, allBindingNames);
         }
         else if (node.type === 'ExportNamedDeclaration' && node.declaration) {
+            // 处理命名导出 export function Component() {} 或 export const Component = () => {}
             if (node.declaration.type === 'FunctionDeclaration' && node.declaration.id) {
                 tryAddComponent(node.declaration.id.name, node.declaration, exportedNames, components, builderWrappedNames);
             }
             else if (node.declaration.type === 'VariableDeclaration') {
-                processVariableDeclaration(node.declaration, exportedNames, components, builderWrappedNames);
+                // 处理变量声明 const Component = () => {} 或 const App = builder(() => {})
+                processVariableDeclaration(node.declaration, exportedNames, components, builderWrappedNames, program, builderAlias, allBindingNames);
             }
         }
         else if (node.type === 'ExportDefaultDeclaration') {
+            // 处理默认导出 export default Component 或 export default () => {}
             const decl = node.declaration;
             if (decl.type === 'FunctionDeclaration' && decl.id) {
+                // 处理具名函数默认导出 export default function Component() {}
                 tryAddComponent(decl.id.name, decl, exportedNames, components, builderWrappedNames);
             }
+            else if (decl.type === 'Identifier') {
+                // 处理标识符默认导出 export default X
+                // 追溯标识符对应的变量声明，判断是否为 builder 包装组件
+                if (isValidComponentName(decl.name) && exportedNames.has(decl.name)) {
+                    const varDecl = findVariableDeclaration(program, decl.name);
+                    if (varDecl?.decl.init?.type === 'CallExpression') {
+                        const result = extractFunctionFromVariableInit(varDecl.decl.init, decl.name, allBindingNames, builderAlias);
+                        if (result) {
+                            // 将提取的函数声明插入到变量声明所在语句之前
+                            const stmtIndex = program.body.indexOf(varDecl.statement);
+                            if (stmtIndex !== -1) {
+                                program.body.splice(stmtIndex, 0, result.funcNode);
+                            }
+                            components.push({
+                                name: result.name,
+                                node: result.funcNode,
+                                isWrapped: result.isBuilderWrapped
+                            });
+                        }
+                    }
+                }
+            }
             else {
+                // 处理匿名默认导出
                 processAnonymousDefaultExport(node, program, allBindingNames, components, builderAlias);
             }
         }

package/dist/utils/generate.d.ts

@@ -1,5 +1,8 @@
 /**
  * 生成唯一的别名
  * 从 $1 开始递增，直到找到不冲突的名称
+ * @param baseName - 基础名称
+ * @param existingNames - 已存在的名称集合（用于冲突检测）
+ * @returns 唯一的别名
  */
 export declare function generateUniqueAlias(baseName: string, existingNames: Set<string>): string;

package/dist/utils/generate.js

@@ -1,9 +1,13 @@
 /**
  * 生成唯一的别名
  * 从 $1 开始递增，直到找到不冲突的名称
+ * @param baseName - 基础名称
+ * @param existingNames - 已存在的名称集合（用于冲突检测）
+ * @returns 唯一的别名
  */
 export function generateUniqueAlias(baseName, existingNames) {
     let index = 1;
+    // 循环查找不冲突的名称
     while (existingNames.has(`${baseName}$${index}`)) {
         index++;
     }

package/dist/utils/jsx-helpers.d.ts

@@ -1,29 +1,43 @@
 /**
  * JSX 相关工具函数
+ * 提供 JSX 元素的各种操作和判断方法
  * @module utils/jsx-helpers
  */
 import * as t from '@babel/types';
 import { type Expression, type JSXAttribute, type JSXElement } from '@babel/types';
 /**
  * 获取 JSX 元素的名称
+ * @param node - JSX 元素节点
+ * @returns 元素名称（Identifier）或 null（MemberExpression）
  */
 export declare function getJSXElementName(node: JSXElement): string | null;
 /**
  * 将 JSX 元素名称节点转换为 createView 的类型表达式
  * JSXIdentifier → Identifier（组件）或 StringLiteral（原生元素）
  * JSXMemberExpression → MemberExpression（如 Obj.Key → Obj.Key）
+ * @param node - JSX 元素节点
+ * @returns 类型表达式或 null
  */
 export declare function resolveJSXElementType(node: JSXElement): t.Expression | null;
 /**
  * 判断名称是否为纯编译组件
+ * 纯编译组件在编译时完全展开，不会生成运行时调用
+ * @param name - 元素名称
+ * @returns 是否为纯编译组件
  */
 export declare function isPureCompileComponent(name: string): boolean;
 /**
  * 判断名称是否为组件（首字母大写）
+ * 遵循 React/Vue 的组件命名约定
+ * @param name - 元素名称
+ * @returns 是否为组件
  */
 export declare function isComponent(name: string): boolean;
 /**
  * 判断名称是否为原生元素
+ * 原生元素使用小写字母开头
+ * @param name - 元素名称
+ * @returns 是否为原生元素
  */
 export declare function isNativeElement(name: string): boolean;
 /**

package/dist/utils/jsx-helpers.js

@@ -1,5 +1,6 @@
 /**
  * JSX 相关工具函数
+ * 提供 JSX 元素的各种操作和判断方法
  * @module utils/jsx-helpers
  */
 import * as t from '@babel/types';
@@ -9,22 +10,30 @@ import { createError } from '../error.js';
 import { isWhitespaceJSXText } from './ast-guards.js';
 /**
  * 获取 JSX 元素的名称
+ * @param node - JSX 元素节点
+ * @returns 元素名称（Identifier）或 null（MemberExpression）
  */
 export function getJSXElementName(node) {
     const nameNode = node.openingElement.name;
+    // 只处理简单标识符，MemberExpression 返回 null
     return nameNode.type === 'JSXIdentifier' ? nameNode.name : null;
 }
 /**
  * 将 JSX 元素名称节点转换为 createView 的类型表达式
  * JSXIdentifier → Identifier（组件）或 StringLiteral（原生元素）
  * JSXMemberExpression → MemberExpression（如 Obj.Key → Obj.Key）
+ * @param node - JSX 元素节点
+ * @returns 类型表达式或 null
  */
 export function resolveJSXElementType(node) {
     const nameNode = node.openingElement.name;
+    // 处理简单标识符（如 <div> 或 <Component>）
     if (nameNode.type === 'JSXIdentifier') {
         const name = nameNode.name;
+        // 原生元素转为字符串，组件转为标识符
         return isNativeElement(name) ? t.stringLiteral(name) : t.identifier(name);
     }
+    // 处理成员表达式（如 <Obj.Key>）
     if (nameNode.type === 'JSXMemberExpression') {
         return jsxMemberExprToMemberExpr(nameNode);
     }
@@ -33,8 +42,11 @@ export function resolveJSXElementType(node) {
 /**
  * 递归转换 JSXMemberExpression 为 MemberExpression
  * Obj.Key → Obj.Key, A.B.C → A.B.C
+ * @param node - JSXMemberExpression 节点
+ * @returns MemberExpression 节点
  */
 function jsxMemberExprToMemberExpr(node) {
+    // 递归处理对象部分
     const object = node.object.type === 'JSXMemberExpression'
         ? jsxMemberExprToMemberExpr(node.object)
         : t.identifier(node.object.name);
@@ -42,18 +54,27 @@ function jsxMemberExprToMemberExpr(node) {
 }
 /**
  * 判断名称是否为纯编译组件
+ * 纯编译组件在编译时完全展开，不会生成运行时调用
+ * @param name - 元素名称
+ * @returns 是否为纯编译组件
  */
 export function isPureCompileComponent(name) {
     return PURE_COMPILE_COMPONENTS.includes(name);
 }
 /**
  * 判断名称是否为组件（首字母大写）
+ * 遵循 React/Vue 的组件命名约定
+ * @param name - 元素名称
+ * @returns 是否为组件
  */
 export function isComponent(name) {
     return name.length > 0 && name[0] === name[0].toUpperCase();
 }
 /**
  * 判断名称是否为原生元素
+ * 原生元素使用小写字母开头
+ * @param name - 元素名称
+ * @returns 是否为原生元素
  */
 export function isNativeElement(name) {
     return !isComponent(name);

package/dist/utils/pattern-helpers.d.ts

@@ -7,14 +7,14 @@ import type { LVal, ObjectPattern } from '@babel/types';
 /**
  * 从绑定模式中收集变量名
  * 支持标识符、对象模式、数组模式
- * @param pattern - 绑定模式
- * @param variables - 变量名集合
+ * @param pattern - 绑定模式节点
+ * @param variables - 存储变量名的集合
  */
 export declare function collectPatternBindings(pattern: LVal, variables: Set<string>): void;
 /**
  * 从对象解构模式中收集变量名
  * 专门用于 toRefs 解构场景
- * @param pattern - 对象模式
- * @param variables - 变量名集合
+ * @param pattern - 对象模式节点
+ * @param variables - 存储变量名的集合
  */
 export declare function collectObjectPatternBindings(pattern: ObjectPattern, variables: Set<string>): void;

package/dist/utils/pattern-helpers.js

@@ -1,26 +1,32 @@
 /**
  * 从绑定模式中收集变量名
  * 支持标识符、对象模式、数组模式
- * @param pattern - 绑定模式
- * @param variables - 变量名集合
+ * @param pattern - 绑定模式节点
+ * @param variables - 存储变量名的集合
  */
 export function collectPatternBindings(pattern, variables) {
+    // 处理简单标识符
     if (pattern.type === 'Identifier') {
         variables.add(pattern.name);
     }
     else if (pattern.type === 'ObjectPattern') {
+        // 处理对象解构模式
         for (const prop of pattern.properties) {
             if (prop.type === 'RestElement') {
+                // 处理剩余运算符（...rest）
                 collectPatternBindings(prop.argument, variables);
             }
             else {
+                // 处理普通属性，递归收集 value
                 collectPatternBindings(prop.value, variables);
             }
         }
     }
     else if (pattern.type === 'ArrayPattern') {
+        // 处理数组解构模式
         for (const elem of pattern.elements) {
             if (elem) {
+                // 递归处理每个非空元素
                 collectPatternBindings(elem, variables);
             }
         }
@@ -29,18 +35,21 @@ export function collectPatternBindings(pattern, variables) {
 /**
  * 从对象解构模式中收集变量名
  * 专门用于 toRefs 解构场景
- * @param pattern - 对象模式
- * @param variables - 变量名集合
+ * @param pattern - 对象模式节点
+ * @param variables - 存储变量名的集合
  */
 export function collectObjectPatternBindings(pattern, variables) {
     for (const prop of pattern.properties) {
         if (prop.type === 'RestElement') {
+            // 处理剩余运算符
             collectPatternBindings(prop.argument, variables);
         }
         else if (prop.value.type === 'Identifier') {
+            // 处理简单标识符属性
             variables.add(prop.value.name);
         }
         else if (prop.value.type === 'ObjectPattern') {
+            // 处理嵌套对象解构，递归收集
             collectObjectPatternBindings(prop.value, variables);
         }
     }

package/dist/utils/vif-helpers.d.ts

@@ -15,14 +15,22 @@ export interface VIfChainInfo {
 }
 /**
  * 验证 v-if 链的合法性
+ * 检查语法错误，如顺序不当、v-else 不是最后一个等
+ * @param children - v-if 链的元素数组
  */
 export declare function validateVIfChain(children: t.JSXElement[]): void;
 /**
  * 从 JSX 元素数组收集 v-if 链信息
+ * 要求所有元素都属于 v-if 链（之前已验证）
+ * @param nodes - JSX 元素数组
+ * @returns v-if 链信息对象
  */
 export declare function collectVIfChainInfo(nodes: t.JSXElement[]): VIfChainInfo;
 /**
  * 收集 Fragment 中的 v-if 链
+ * 从 Fragment 的子元素中识别多个独立的 v-if 链
+ * @param children - Fragment 的子节点数组
+ * @returns v-if 链信息数组
  */
 export declare function collectFragmentVIfChains(children: t.Node[]): Array<VIfChainInfo & {
     endIndex: number;