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

package/dist/utils/ast-builders.js

@@ -1,78 +1,91 @@
 /**
  * AST 节点构建函数
+ * 提供各类运行时 API 调用的创建辅助函数
  * @module utils/ast-builders
  */
 import * as t from '@babel/types';
 import { isIdentifier } from '@babel/types';
 import { PURE_COMMENT } from '../constants/index.js';
 /**
- * 创建 unref 调用
- * @param argument - 参数表达式
- * @param alias - unref 别名
- * @returns CallExpression
+ * 创建 unref 调用表达式
+ * @param argument - 需要解包的表达式
+ * @param alias - unref 的本地别名
+ * @returns unref(arg) 调用表达式
  */
 export function createUnrefCall(argument, alias) {
+    // 使用别名或默认名称创建标识符
     return t.callExpression(t.identifier(alias || 'unref'), [argument]);
 }
 /**
- * 创建 accessor 调用
+ * 创建 accessor 调用表达式
+ * 用于细粒度响应式追踪，只追踪对象的特定属性
  * @param object - 对象表达式
- * @param key - 键表达式
- * @param alias - accessor 别名
- * @returns CallExpression
+ * @param key - 属性键表达式
+ * @param alias - accessor 的本地别名
+ * @returns accessor(obj, key) 调用表达式
  */
 export function createAccessorCall(object, key, alias) {
+    // 如果键是标识符，转换为字符串字面量；否则保持原样
     const keyArg = isIdentifier(key) ? t.stringLiteral(key.name) : key;
     return t.callExpression(t.identifier(alias || 'accessor'), [object, keyArg]);
 }
 /**
- * 创建 expr 调用
- * @param argument - 参数表达式
- * @param alias - expr 别名
- * @returns CallExpression
+ * 创建 expr 调用表达式
+ * 用于粗粒度响应式追踪，包装任意表达式
+ * @param argument - 需要包装的表达式
+ * @param alias - expr 的本地别名
+ * @returns expr(() => arg) 调用表达式
  */
 export function createExprCall(argument, alias) {
+    // 将表达式包装在箭头函数中传递给 expr
     return t.callExpression(t.identifier(alias || 'expr'), [t.arrowFunctionExpression([], argument)]);
 }
 /**
- * 创建 branch 调用
- * @param condition - 条件函数
+ * 创建 branch 调用表达式
+ * 用于条件分支渲染，支持多分支选择
+ * @param condition - 返回分支索引的箭头函数
  * @param branches - 分支函数数组
- * @param alias - branch 别名
- * @returns CallExpression
+ * @param alias - branch 的本地别名
+ * @returns branch(condition, [branches]) 调用表达式
  */
 export function createBranchCall(condition, branches, alias) {
     return t.callExpression(t.identifier(alias || 'branch'), [condition, t.arrayExpression(branches)]);
 }
 /**
- * 创建 createView 调用
- * @param type - 元素类型
- * @param props - props 对象
- * @param locInfo - 位置信息对象
- * @param alias - createView 别名
- * @returns CallExpression
+ * 创建 createView 调用表达式
+ * 这是核心的视图创建函数，将 JSX 转换为运行时调用
+ * @param type - 元素类型（字符串表示原生元素，标识符表示组件）
+ * @param props - 属性对象表达式
+ * @param locInfo - 开发环境下的位置信息（用于错误定位）
+ * @param alias - createView 的本地别名
+ * @returns createView(type, props?, locInfo?) 调用表达式
  */
 export function createCreateViewCall(type, props, locInfo, alias) {
     const args = [type];
+    // 根据参数情况构建调用参数
     if (props) {
         args.push(props);
     }
     else if (locInfo) {
+        // 有位置信息但无 props 时，props 位置传 null
         args.push(t.nullLiteral());
     }
+    // 添加位置信息（仅开发环境）
     if (locInfo) {
         args.push(locInfo);
     }
     return t.callExpression(t.identifier(alias || 'createView'), args);
 }
 /**
- * 创建 withDirectives 调用
- * @param view - 视图节点
- * @param directives - 指令数组，每项为 [指令名, 指令值]
- * @param alias - withDirectives 别名
- * @returns CallExpression
+ * 创建 withDirectives 调用表达式
+ * 用于为视图节点添加自定义指令
+ * @param view - 视图节点表达式
+ * @param directives - 指令数组，每项为 [指令名, 指令值] 元组
+ * @param alias - withDirectives 的本地别名
+ * @returns withDirectives(view, [[name, value], ...]) 调用表达式
  */
 export function createWithDirectivesCall(view, directives, alias) {
+    // 将指令数组转换为嵌套数组表达式
     const directiveArray = directives.map(([name, value]) => {
         return t.arrayExpression([t.stringLiteral(name), value]);
     });
@@ -82,56 +95,62 @@ export function createWithDirectivesCall(view, directives, alias) {
     ]);
 }
 /**
- * 创建箭头函数
+ * 创建无参数箭头函数
  * @param body - 函数体表达式
- * @returns ArrowFunctionExpression
+ * @returns () => body 箭头函数表达式
  */
 export function createArrowFunction(body) {
     return t.arrowFunctionExpression([], body);
 }
 /**
  * 为调用表达式添加 @__PURE__ 注释
+ * 标记纯函数调用，帮助 Tree Shaking 优化
  * @param node - 调用表达式节点
- * @param ctx - 转换上下文
- * @returns 添加注释后的节点
+ * @param ctx - 转换上下文（用于去重）
+ * @returns 添加注释后的节点（可能是原节点）
  */
 export function addPureComment(node, ctx) {
+    // 避免重复添加注释
     if (ctx.pureCommentedNodes.has(node)) {
         return node;
     }
     ctx.pureCommentedNodes.add(node);
+    // 在节点前添加注释
     t.addComment(node, 'leading', ` ${PURE_COMMENT} `, false);
     return node;
 }
 /**
- * 获取 API 别名
- * @param aliases - 别名映射
- * @param name - API 名称
- * @returns 别名或原名
+ * 获取 API 的本地别名
+ * @param aliases - 别名映射对象
+ * @param name - API 原始名称
+ * @returns 本地别名或原始名称
  */
 export function getAlias(aliases, name) {
     return aliases[name] || name;
 }
 /**
- * 创建位置信息对象
- * @param filename - 文件名
- * @param loc - 源码位置
- * @returns ObjectExpression
+ * 创建源码位置信息对象
+ * 用于开发环境下的错误定位
+ * @param filename - 当前文件名
+ * @param loc - 源码位置信息
+ * @returns 位置信息对象 { fileName, lineNumber, columnNumber }
  */
 export function createLocationObject(filename, loc) {
     return t.objectExpression([
         t.objectProperty(t.identifier('fileName'), t.stringLiteral(filename)),
         t.objectProperty(t.identifier('lineNumber'), t.numericLiteral(loc.start.line)),
+        // 列号从 1 开始（与编辑器一致）
         t.objectProperty(t.identifier('columnNumber'), t.numericLiteral(loc.start.column + 1))
     ]);
 }
 /**
  * 获取开发环境下的位置信息对象
- * 仅在开发环境下返回位置信息，生产环境返回 null
+ * 仅在开发模式且节点有位置信息时返回
  * @param ctx - 转换上下文
- * @param node - AST 节点或位置信息
+ * @param node - AST 节点或包含 loc 属性的对象
  * @returns 位置信息对象或 null
  */
 export function getDevLocInfo(ctx, node) {
+    // 仅开发模式且有位置信息时创建
     return ctx.options.dev && node.loc ? createLocationObject(ctx.filename, node.loc) : null;
 }

package/dist/utils/ast-guards.d.ts

@@ -1,11 +1,12 @@
 /**
  * AST 类型守卫函数
- * 用于判断节点类型
+ * 用于判断节点类型和属性
  * @module utils/ast-guards
  */
 import { type Node } from '@babel/types';
 /**
  * 判断 JSXText 是否为纯空白文本
+ * 空白文本在渲染时通常需要被过滤掉
  * @param node - AST 节点
  * @returns 是否为纯空白文本
  */

package/dist/utils/ast-guards.js

@@ -1,16 +1,19 @@
 /**
  * AST 类型守卫函数
- * 用于判断节点类型
+ * 用于判断节点类型和属性
  * @module utils/ast-guards
  */
 import { isJSXText } from '@babel/types';
 /**
  * 判断 JSXText 是否为纯空白文本
+ * 空白文本在渲染时通常需要被过滤掉
  * @param node - AST 节点
  * @returns 是否为纯空白文本
  */
 export function isWhitespaceJSXText(node) {
+    // 先判断是否为 JSXText 类型
     if (!isJSXText(node))
         return false;
+    // 使用正则表达式判断是否只包含空白字符
     return /^\s*$/.test(node.value);
 }

package/dist/utils/collect-names.d.ts

@@ -5,24 +5,33 @@
  */
 import type * as t from '@babel/types';
 /**
- * 从命名导出中收集名称
+ * 从命名导出声明中收集名称
+ * @param node - 命名导出声明节点
+ * @param names - 存储名称的集合
  */
 export declare function collectFromNamedExport(node: t.ExportNamedDeclaration, names: Set<string>): void;
 /**
- * 从默认导出中收集名称
+ * 从默认导出声明中收集名称
+ * @param node - 默认导出声明节点
+ * @param names - 存储名称的集合
  */
 export declare function collectFromDefaultExport(node: t.ExportDefaultDeclaration, names: Set<string>): void;
 /**
  * 收集所有导出的标识符名称
+ * @param program - AST Program 节点
+ * @returns 导出名称集合
  */
 export declare function collectExportedNames(program: t.Program): Set<string>;
 /**
  * 收集模块中所有绑定的名称（用于避免命名冲突）
+ * 包括函数声明、变量声明、导入声明和导出声明
+ * @param program - AST Program 节点
+ * @returns 所有绑定名称集合
  */
 export declare function collectAllBindingNames(program: t.Program): Set<string>;
 /**
  * 判断调用表达式是否是 builder 调用
- * @param callExpr - 调用表达式
+ * @param callExpr - 调用表达式节点
  * @param builderAlias - builder 的本地别名
  * @returns 是否是 builder 调用
  */
@@ -32,6 +41,6 @@ export declare function isBuilderCall(callExpr: t.CallExpression, builderAlias:
  * 检测 builder(Comp) 或 builder(Comp, options) 形式的调用
  * @param program - AST Program 节点
  * @param builderAlias - builder 的本地别名
- * @returns 被 builder 调用的组件名称集合
+ * @returns 被 builder 包装的组件名称集合
  */
 export declare function collectBuilderWrappedNames(program: t.Program, builderAlias: string | null): Set<string>;

package/dist/utils/collect-names.js

@@ -1,7 +1,10 @@
 /**
- * 从命名导出中收集名称
+ * 从命名导出声明中收集名称
+ * @param node - 命名导出声明节点
+ * @param names - 存储名称的集合
  */
 export function collectFromNamedExport(node, names) {
+    // 处理内联声明（export function/const）
     if (node.declaration) {
         if (node.declaration.type === 'FunctionDeclaration' && node.declaration.id) {
             names.add(node.declaration.id.name);
@@ -14,6 +17,7 @@ export function collectFromNamedExport(node, names) {
             }
         }
     }
+    // 处理导出说明符（export { a, b }）
     if (node.specifiers) {
         for (const spec of node.specifiers) {
             if (spec.type === 'ExportSpecifier') {
@@ -23,22 +27,29 @@ export function collectFromNamedExport(node, names) {
     }
 }
 /**
- * 从默认导出中收集名称
+ * 从默认导出声明中收集名称
+ * @param node - 默认导出声明节点
+ * @param names - 存储名称的集合
  */
 export function collectFromDefaultExport(node, names) {
     const decl = node.declaration;
+    // 处理命名函数声明
     if (decl.type === 'FunctionDeclaration' && decl.id) {
         names.add(decl.id.name);
     }
     else if (decl.type === 'Identifier') {
+        // 处理标识符引用（export default Component）
         names.add(decl.name);
     }
 }
 /**
  * 从变量声明中收集变量名
+ * @param node - 变量声明节点
+ * @param names - 存储名称的集合
  */
 function collectFromVariableDeclaration(node, names) {
     for (const decl of node.declarations) {
+        // 只处理简单标识符（不处理解构）
         if (decl.id.type === 'Identifier') {
             names.add(decl.id.name);
         }
@@ -46,17 +57,23 @@ function collectFromVariableDeclaration(node, names) {
 }
 /**
  * 从导入声明中收集绑定的名称
+ * @param node - 导入声明节点
+ * @param names - 存储名称的集合
  */
 function collectFromImportDeclaration(node, names) {
     for (const spec of node.specifiers) {
+        // 收集本地绑定名称
         names.add(spec.local.name);
     }
 }
 /**
  * 收集所有导出的标识符名称
+ * @param program - AST Program 节点
+ * @returns 导出名称集合
  */
 export function collectExportedNames(program) {
     const names = new Set();
+    // 遍历程序体中的所有节点
     for (const node of program.body) {
         if (node.type === 'ExportNamedDeclaration') {
             collectFromNamedExport(node, names);
@@ -69,23 +86,32 @@ export function collectExportedNames(program) {
 }
 /**
  * 收集模块中所有绑定的名称（用于避免命名冲突）
+ * 包括函数声明、变量声明、导入声明和导出声明
+ * @param program - AST Program 节点
+ * @returns 所有绑定名称集合
  */
 export function collectAllBindingNames(program) {
     const names = new Set();
+    // 遍历程序体中的所有节点
     for (const node of program.body) {
+        // 函数声明
         if (node.type === 'FunctionDeclaration' && node.id) {
             names.add(node.id.name);
         }
         else if (node.type === 'VariableDeclaration') {
+            // 变量声明
             collectFromVariableDeclaration(node, names);
         }
         else if (node.type === 'ImportDeclaration') {
+            // 导入声明
             collectFromImportDeclaration(node, names);
         }
         else if (node.type === 'ExportNamedDeclaration') {
+            // 命名导出
             collectFromNamedExport(node, names);
         }
         else if (node.type === 'ExportDefaultDeclaration') {
+            // 默认导出
             collectFromDefaultExport(node, names);
         }
     }
@@ -93,14 +119,16 @@ export function collectAllBindingNames(program) {
 }
 /**
  * 判断调用表达式是否是 builder 调用
- * @param callExpr - 调用表达式
+ * @param callExpr - 调用表达式节点
  * @param builderAlias - builder 的本地别名
  * @returns 是否是 builder 调用
  */
 export function isBuilderCall(callExpr, builderAlias) {
+    // 如果没有配置 builder 别名，直接返回 false
     if (!builderAlias)
         return false;
     const callee = callExpr.callee;
+    // 检查调用者是否为标识符且名称匹配
     return callee.type === 'Identifier' && callee.name === builderAlias;
 }
 /**
@@ -108,13 +136,16 @@ export function isBuilderCall(callExpr, builderAlias) {
  * 检测 builder(Comp) 或 builder(Comp, options) 形式的调用
  * @param program - AST Program 节点
  * @param builderAlias - builder 的本地别名
- * @returns 被 builder 调用的组件名称集合
+ * @returns 被 builder 包装的组件名称集合
  */
 export function collectBuilderWrappedNames(program, builderAlias) {
     const wrappedNames = new Set();
+    // 如果没有配置 builder 别名，直接返回空集合
     if (!builderAlias)
         return wrappedNames;
+    // 遍历程序体中的所有节点
     for (const node of program.body) {
+        // 处理独立调用语句：builder(Comp)
         if (node.type === 'ExpressionStatement' && node.expression.type === 'CallExpression') {
             const callExpr = node.expression;
             if (isBuilderCall(callExpr, builderAlias)) {
@@ -125,6 +156,7 @@ export function collectBuilderWrappedNames(program, builderAlias) {
             }
         }
         else if (node.type === 'ExportDefaultDeclaration' && node.declaration.type === 'CallExpression') {
+            // 处理默认导出：export default builder(Comp)
             const callExpr = node.declaration;
             if (isBuilderCall(callExpr, builderAlias)) {
                 const arg = callExpr.arguments[0];
@@ -134,6 +166,7 @@ export function collectBuilderWrappedNames(program, builderAlias) {
             }
         }
         else if (node.type === 'VariableDeclaration') {
+            // 处理变量声明：const Comp = builder(CompImpl)
             for (const decl of node.declarations) {
                 if (decl.init?.type === 'CallExpression' && isBuilderCall(decl.init, builderAlias)) {
                     const arg = decl.init.arguments[0];
@@ -144,6 +177,7 @@ export function collectBuilderWrappedNames(program, builderAlias) {
             }
         }
         else if (node.type === 'ExportNamedDeclaration' && node.declaration?.type === 'VariableDeclaration') {
+            // 处理命名导出：export const Comp = builder(CompImpl)
             for (const decl of node.declaration.declarations) {
                 if (decl.init?.type === 'CallExpression' && isBuilderCall(decl.init, builderAlias)) {
                     const arg = decl.init.arguments[0];

package/dist/utils/component-collect.d.ts

@@ -5,16 +5,18 @@
  */
 import * as t from '@babel/types';
 /**
- * 组件信息
+ * 组件信息接口
+ * 描述从 AST 中提取的组件函数信息
  */
 export interface ComponentInfo {
     name: string;
     node: t.FunctionDeclaration | t.ArrowFunctionExpression | t.FunctionExpression;
-    /** 是否为包装组件（传递给 builder/defineComponent 等函数） */
+    /** 是否为包装组件（传递给 builder 函数） */
     isWrapped?: boolean;
 }
 /**
  * 收集模块中的组件函数
+ * 遍历 AST 程序节点，提取所有导出的组件函数
  * @param program - AST Program 节点
  * @param builderAlias - builder 函数的本地别名（用于识别纯构建组件）
  * @returns 组件信息数组