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

package/dist/passes/imports/collectRefVariables.d.ts

@@ -14,7 +14,7 @@ import type { RefApiAliases } from '../../context.js';
 export declare function collectRefApiAliases(program: t.Program): RefApiAliases;
 /**
  * 收集通过 ref API 定义的变量
- * 包括直接赋值和 toRefs 解构
+ * 包括直接赋值（const x = ref(0)）和 toRefs 解构（const { a, b } = toRefs(obj)）
  * @param program - AST Program 节点
  * @param refApiAliases - ref API 别名映射
  * @returns ref 变量名集合
@@ -22,7 +22,7 @@ export declare function collectRefApiAliases(program: t.Program): RefApiAliases;
 export declare function collectRefVariables(program: t.Program, refApiAliases: RefApiAliases): Set<string>;
 /**
  * 收集确定不是 ref 的变量
- * 包括函数声明、箭头函数和函数表达式变量
+ * 包括函数声明、箭头函数和函数表达式变量（这些不可能是 ref）
  * @param program - AST Program 节点
  * @returns 非 ref 变量名集合
  */

package/dist/passes/imports/collectRefVariables.js

@@ -7,6 +7,7 @@ import { collectPatternBindings, collectObjectPatternBindings } from '../../util
  * @returns ref API 别名映射
  */
 export function collectRefApiAliases(program) {
+    // 初始化别名映射，默认为 null（未导入）
     const aliases = {
         ref: null,
         toRef: null,
@@ -14,18 +15,25 @@ export function collectRefApiAliases(program) {
         shallowRef: null,
         computed: null
     };
+    // 遍历程序体中的所有节点
     for (const node of program.body) {
+        // 跳过非导入声明节点
         if (node.type !== 'ImportDeclaration')
             continue;
         const source = node.source.value;
+        // 只处理 vitarx 和 @vitarx/responsive 模块
         if (!RESPONSIVE_MODULES.includes(source))
             continue;
+        // 遍历导入说明符
         for (const specifier of node.specifiers) {
+            // 只处理命名导入
             if (specifier.type !== 'ImportSpecifier')
                 continue;
+            // 获取导入的原始名称
             const importedName = specifier.imported.type === 'Identifier'
                 ? specifier.imported.name
                 : specifier.imported.value;
+            // 如果是 ref API，记录别名映射
             if (Object.values(REF_APIS).includes(importedName)) {
                 aliases[importedName] = specifier.local.name;
             }
@@ -35,48 +43,66 @@ export function collectRefApiAliases(program) {
 }
 /**
  * 收集通过 ref API 定义的变量
- * 包括直接赋值和 toRefs 解构
+ * 包括直接赋值（const x = ref(0)）和 toRefs 解构（const { a, b } = toRefs(obj)）
  * @param program - AST Program 节点
  * @param refApiAliases - ref API 别名映射
  * @returns ref 变量名集合
  */
 export function collectRefVariables(program, refApiAliases) {
     const refVariables = new Set();
+    // 构建 ref API 的本地名称集合（包括别名）
     const { refApiLocalNames, toRefsLocalNames } = buildApiNameSets(refApiAliases);
+    // 遍历程序体中的所有节点
     for (const node of program.body) {
         collectRefVariablesFromNode(node, refVariables, refApiLocalNames, toRefsLocalNames);
     }
     return refVariables;
 }
+/**
+ * 从节点中递归收集 ref 变量
+ * @param node - AST 节点
+ * @param refVariables - 存储 ref 变量名的集合
+ * @param refApiLocalNames - ref API 的本地名称集合
+ * @param toRefsLocalNames - toRefs API 的本地名称集合
+ */
 function collectRefVariablesFromNode(node, refVariables, refApiLocalNames, toRefsLocalNames) {
+    // 处理变量声明
     if (node.type === 'VariableDeclaration') {
         for (const decl of node.declarations) {
+            // 跳过没有初始值的声明
             if (!decl.init)
                 continue;
+            // 跳过 void 模式
             if (decl.id.type === 'VoidPattern')
                 continue;
             const init = decl.init;
+            // 检查是否为函数调用表达式
             if (init.type !== 'CallExpression' || init.callee.type !== 'Identifier') {
                 continue;
             }
             const calleeName = init.callee.name;
+            // toRefs 需要特殊处理：只收集对象解构的属性
             if (toRefsLocalNames.has(calleeName) && decl.id.type === 'ObjectPattern') {
                 collectObjectPatternBindings(decl.id, refVariables);
             }
             else if (refApiLocalNames.has(calleeName)) {
+                // 其他 ref API：收集变量名（支持解构）
                 collectPatternBindings(decl.id, refVariables);
             }
         }
     }
     else if (node.type === 'FunctionDeclaration' && node.body) {
+        // 递归处理函数体内的语句
         for (const stmt of node.body.body) {
             collectRefVariablesFromNode(stmt, refVariables, refApiLocalNames, toRefsLocalNames);
         }
     }
     else if (node.type === 'ExportNamedDeclaration' && node.declaration) {
+        // 处理命名导出的声明
         collectRefVariablesFromNode(node.declaration, refVariables, refApiLocalNames, toRefsLocalNames);
     }
     else if (node.type === 'ExportDefaultDeclaration') {
+        // 处理默认导出
         const decl = node.declaration;
         if (decl.type === 'FunctionDeclaration' && decl.body) {
             for (const stmt of decl.body.body) {
@@ -87,20 +113,28 @@ function collectRefVariablesFromNode(node, refVariables, refApiLocalNames, toRef
 }
 /**
  * 收集确定不是 ref 的变量
- * 包括函数声明、箭头函数和函数表达式变量
+ * 包括函数声明、箭头函数和函数表达式变量（这些不可能是 ref）
  * @param program - AST Program 节点
  * @returns 非 ref 变量名集合
  */
 export function collectNonRefVariables(program) {
     const nonRefVariables = new Set();
+    // 遍历程序体中的所有节点
     for (const node of program.body) {
         collectNonRefFromNode(node, nonRefVariables);
     }
     return nonRefVariables;
 }
+/**
+ * 从节点中递归收集非 ref 变量
+ * @param node - AST 节点
+ * @param nonRefVariables - 存储非 ref 变量名的集合
+ */
 function collectNonRefFromNode(node, nonRefVariables) {
+    // 函数声明一定不是 ref
     if (node.type === 'FunctionDeclaration' && node.id) {
         nonRefVariables.add(node.id.name);
+        // 递归处理函数体内的变量
         if (node.body) {
             for (const stmt of node.body.body) {
                 collectNonRefFromNode(stmt, nonRefVariables);
@@ -108,9 +142,11 @@ function collectNonRefFromNode(node, nonRefVariables) {
         }
     }
     else if (node.type === 'VariableDeclaration') {
+        // 变量声明：只有箭头函数或函数表达式才是非 ref
         for (const decl of node.declarations) {
             if (!decl.init)
                 continue;
+            // 只处理简单标识符（不处理解构）
             if (decl.id.type !== 'Identifier')
                 continue;
             const init = decl.init;
@@ -121,11 +157,13 @@ function collectNonRefFromNode(node, nonRefVariables) {
         }
     }
     else if (node.type === 'ExportNamedDeclaration') {
+        // 处理命名导出的声明
         if (node.declaration) {
             collectNonRefFromNode(node.declaration, nonRefVariables);
         }
     }
     else if (node.type === 'ExportDefaultDeclaration') {
+        // 处理默认导出
         const decl = node.declaration;
         if (decl.type === 'FunctionDeclaration' && decl.id) {
             nonRefVariables.add(decl.id.name);
@@ -133,14 +171,19 @@ function collectNonRefFromNode(node, nonRefVariables) {
     }
 }
 /**
- * 构建 API 名称集合
+ * 构建 ref API 的本地名称集合
+ * 将别名映射转换为集合，便于快速查找
+ * @param refApiAliases - ref API 别名映射
+ * @returns 包含 ref API 和 toRefs API 的本地名称集合
  */
 function buildApiNameSets(refApiAliases) {
     const refApiLocalNames = new Set();
     const toRefsLocalNames = new Set();
+    // 遍历所有 ref API
     for (const key of Object.keys(refApiAliases)) {
         const alias = refApiAliases[key];
         if (alias) {
+            // 如果有别名，使用别名
             if (key === 'toRefs') {
                 toRefsLocalNames.add(alias);
             }
@@ -149,6 +192,7 @@ function buildApiNameSets(refApiAliases) {
             }
         }
         else {
+            // 如果没有别名，使用原始名称
             if (key === 'toRefs') {
                 toRefsLocalNames.add(key);
             }

package/dist/passes/imports/injectImports.d.ts

@@ -8,6 +8,7 @@ import type { TransformContext } from '../../context.js';
 /**
  * 注入 vitarx 导入
  * 根据已使用的 API 动态生成导入语句
+ * 如果已存在 vitarx 导入，则追加说明符；否则创建新的导入语句
  * @param program - AST Program 节点
  * @param ctx - 转换上下文
  */

package/dist/passes/imports/injectImports.js

@@ -8,6 +8,7 @@ import { VITARX_MODULE } from '../../constants/index.js';
 /**
  * API 导入配置
  * 定义需要注入的 API 及其与 ImportInfo 的映射关系
+ * 当代码中使用了特定的 vitarx API 时，自动注入对应的 import 语句
  */
 const API_IMPORT_CONFIG = [
     { name: 'createView', importKey: 'createView' },
@@ -22,17 +23,22 @@ const API_IMPORT_CONFIG = [
 /**
  * 注入 vitarx 导入
  * 根据已使用的 API 动态生成导入语句
+ * 如果已存在 vitarx 导入，则追加说明符；否则创建新的导入语句
  * @param program - AST Program 节点
  * @param ctx - 转换上下文
  */
 export function injectImports(program, ctx) {
+    // 如果没有需要注入的 API，直接返回
     if (!needsInject(ctx))
         return;
+    // 查找已存在的 vitarx 导入语句
     const existingVitarxImport = findExistingVitarxImport(program);
+    // 如果存在且可以追加说明符，则追加
     if (existingVitarxImport && canAppendSpecifiers(existingVitarxImport)) {
         appendImportSpecifiers(existingVitarxImport, ctx);
     }
     else {
+        // 否则创建新的导入语句
         const specifiers = buildImportSpecifiers(ctx);
         if (specifiers.length === 0)
             return;
@@ -42,7 +48,9 @@ export function injectImports(program, ctx) {
 }
 /**
  * 检查是否可以向导入语句追加说明符
- * 只有纯命名导入才能追加，命名空间导入和默认导入不能追加
+ * 只有纯命名导入才能追加，命名空间导入（import * as xxx）和默认导入（import xxx）不能追加
+ * @param importDecl - 导入声明节点
+ * @returns 是否可以追加说明符
  */
 function canAppendSpecifiers(importDecl) {
     for (const spec of importDecl.specifiers) {
@@ -55,7 +63,9 @@ function canAppendSpecifiers(importDecl) {
 }
 /**
  * 查找已存在的 vitarx 导入语句
- * 只查找普通的 import 语句，跳过 import type 语句
+ * 只查找普通的 import 语句，跳过 import type/typeof 语句
+ * @param program - AST Program 节点
+ * @returns 已存在的 vitarx 导入声明，不存在则返回 null
  */
 function findExistingVitarxImport(program) {
     for (const node of program.body) {
@@ -70,21 +80,29 @@ function findExistingVitarxImport(program) {
 }
 /**
  * 向已存在的导入语句追加说明符
+ * @param importDecl - 导入声明节点
+ * @param ctx - 转换上下文
  */
 function appendImportSpecifiers(importDecl, ctx) {
+    // 收集已存在的本地名称，避免重复
     const existingLocals = new Set();
     for (const spec of importDecl.specifiers) {
         if (spec.type === 'ImportSpecifier') {
             existingLocals.add(spec.local.name);
         }
     }
+    // 遍历需要注入的 API
     for (const { name, importKey } of API_IMPORT_CONFIG) {
+        // 如果该 API 未被使用，跳过
         if (!ctx.imports[importKey])
             continue;
+        // 获取用户配置的别名，无别名则使用原始名称
         const alias = ctx.vitarxAliases[name];
         const localName = alias || name;
+        // 如果该本地名称已存在，跳过
         if (existingLocals.has(localName))
             continue;
+        // 创建导入说明符并追加
         const imported = t.identifier(name);
         const local = t.identifier(localName);
         importDecl.specifiers.push(t.importSpecifier(local, imported));
@@ -92,17 +110,25 @@ function appendImportSpecifiers(importDecl, ctx) {
 }
 /**
  * 检查是否需要注入导入
+ * @param ctx - 转换上下文
+ * @returns 是否有需要注入的 API
  */
 function needsInject(ctx) {
+    // 检查 imports 对象中是否有任何值为 true
     return Object.values(ctx.imports).some(Boolean);
 }
 /**
  * 构建导入说明符列表
+ * @param ctx - 转换上下文
+ * @returns 导入说明符数组
  */
 function buildImportSpecifiers(ctx) {
     const specifiers = [];
+    // 遍历需要注入的 API
     for (const { name, importKey } of API_IMPORT_CONFIG) {
+        // 只处理已使用的 API
         if (ctx.imports[importKey]) {
+            // 获取用户配置的别名
             const alias = ctx.vitarxAliases[name];
             const imported = t.identifier(name);
             const local = alias ? t.identifier(alias) : imported;

package/dist/transform.js

@@ -9,6 +9,7 @@ import traverse from '@babel/traverse';
 import { createContext } from './context.js';
 import { collectExistingImports, collectLocalBindings, collectNonRefVariables, collectRefApiAliases, collectRefVariables, injectHMRSupport, injectImports, processJSXElement, processJSXFragment, processPureCompileComponent, processVIfChain, transformJSXElement } from './passes/index.js';
 import { collectComponentFunctions, generateUniqueAlias, getJSXElementName, isPureCompileComponent } from './utils/index.js';
+const entryPatterns = [/\/src\/main\.(tsx|jsx)$/, /\\src\\main\.(tsx|jsx)$/];
 /**
  * 创建解析器选项
  */
@@ -127,6 +128,15 @@ export function shouldTransform(id) {
     const ext = id.split('?')[0].split('.').pop()?.toLowerCase();
     return ext === 'jsx' || ext === 'tsx';
 }
+/**
+ * 检查是否为入口文件
+ * 入口文件（如 src/main.tsx/src/main.jsx）不应注入 HMR，因为主脚本重新执行会导致页面内容重复
+ * 最佳实践：入口文件应为 main.ts/main.js，组件应放在 App.tsx/App.jsx 等专门的组件文件中
+ */
+function isEntryFile(id) {
+    const normalizedId = id.split('?')[0];
+    return entryPatterns.some(pattern => pattern.test(normalizedId));
+}
 /**
  * 转换 JSX/TSX 代码
  */
@@ -138,7 +148,7 @@ export async function transform(code, id, options) {
     const components = collectComponentFunctions(ast.program, ctx.builderAlias);
     transformAST(ast, ctx);
     injectImports(ast.program, ctx);
-    if (options.hmr && components.length > 0) {
+    if (options.hmr && components.length > 0 && !isEntryFile(id)) {
         injectHMRSupport(ast.program, components, id);
     }
     return generateCode(ast, code, id, options.sourceMap);

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

@@ -1,5 +1,6 @@
 /**
  * AST 节点构建函数
+ * 提供各类运行时 API 调用的创建辅助函数
  * @module utils/ast-builders
  */
 import * as t from '@babel/types';
@@ -7,84 +8,91 @@ import { type ArrowFunctionExpression, type CallExpression, type Expression, typ
 import type { SourceLocation } from 'acorn';
 import type { TransformContext, VitarxImportAliases } from '../context.js';
 /**
- * 创建 unref 调用
- * @param argument - 参数表达式
- * @param alias - unref 别名
- * @returns CallExpression
+ * 创建 unref 调用表达式
+ * @param argument - 需要解包的表达式
+ * @param alias - unref 的本地别名
+ * @returns unref(arg) 调用表达式
  */
 export declare function createUnrefCall(argument: Expression, alias?: string): CallExpression;
 /**
- * 创建 accessor 调用
+ * 创建 accessor 调用表达式
+ * 用于细粒度响应式追踪，只追踪对象的特定属性
  * @param object - 对象表达式
- * @param key - 键表达式
- * @param alias - accessor 别名
- * @returns CallExpression
+ * @param key - 属性键表达式
+ * @param alias - accessor 的本地别名
+ * @returns accessor(obj, key) 调用表达式
  */
 export declare function createAccessorCall(object: Expression, key: Expression, alias?: string): CallExpression;
 /**
- * 创建 expr 调用
- * @param argument - 参数表达式
- * @param alias - expr 别名
- * @returns CallExpression
+ * 创建 expr 调用表达式
+ * 用于粗粒度响应式追踪，包装任意表达式
+ * @param argument - 需要包装的表达式
+ * @param alias - expr 的本地别名
+ * @returns expr(() => arg) 调用表达式
  */
 export declare function createExprCall(argument: Expression, alias?: string): CallExpression;
 /**
- * 创建 branch 调用
- * @param condition - 条件函数
+ * 创建 branch 调用表达式
+ * 用于条件分支渲染，支持多分支选择
+ * @param condition - 返回分支索引的箭头函数
  * @param branches - 分支函数数组
- * @param alias - branch 别名
- * @returns CallExpression
+ * @param alias - branch 的本地别名
+ * @returns branch(condition, [branches]) 调用表达式
  */
 export declare function createBranchCall(condition: ArrowFunctionExpression, branches: ArrowFunctionExpression[], alias?: string): CallExpression;
 /**
- * 创建 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 declare function createCreateViewCall(type: Expression, props: ObjectExpression | null, locInfo?: ObjectExpression | null, alias?: string): CallExpression;
 /**
- * 创建 withDirectives 调用
- * @param view - 视图节点
- * @param directives - 指令数组，每项为 [指令名, 指令值]
- * @param alias - withDirectives 别名
- * @returns CallExpression
+ * 创建 withDirectives 调用表达式
+ * 用于为视图节点添加自定义指令
+ * @param view - 视图节点表达式
+ * @param directives - 指令数组，每项为 [指令名, 指令值] 元组
+ * @param alias - withDirectives 的本地别名
+ * @returns withDirectives(view, [[name, value], ...]) 调用表达式
  */
 export declare function createWithDirectivesCall(view: Expression, directives: Array<[string, Expression]>, alias?: string): CallExpression;
 /**
- * 创建箭头函数
+ * 创建无参数箭头函数
  * @param body - 函数体表达式
- * @returns ArrowFunctionExpression
+ * @returns () => body 箭头函数表达式
  */
 export declare function createArrowFunction(body: Expression): ArrowFunctionExpression;
 /**
  * 为调用表达式添加 @__PURE__ 注释
+ * 标记纯函数调用，帮助 Tree Shaking 优化
  * @param node - 调用表达式节点
- * @param ctx - 转换上下文
- * @returns 添加注释后的节点
+ * @param ctx - 转换上下文（用于去重）
+ * @returns 添加注释后的节点（可能是原节点）
  */
 export declare function addPureComment<T extends CallExpression>(node: T, ctx: TransformContext): T;
 /**
- * 获取 API 别名
- * @param aliases - 别名映射
- * @param name - API 名称
- * @returns 别名或原名
+ * 获取 API 的本地别名
+ * @param aliases - 别名映射对象
+ * @param name - API 原始名称
+ * @returns 本地别名或原始名称
  */
 export declare function getAlias(aliases: VitarxImportAliases, name: keyof VitarxImportAliases): string;
 /**
- * 创建位置信息对象
- * @param filename - 文件名
- * @param loc - 源码位置
- * @returns ObjectExpression
+ * 创建源码位置信息对象
+ * 用于开发环境下的错误定位
+ * @param filename - 当前文件名
+ * @param loc - 源码位置信息
+ * @returns 位置信息对象 { fileName, lineNumber, columnNumber }
  */
 export declare function createLocationObject(filename: string, loc: SourceLocation): ObjectExpression;
 /**
  * 获取开发环境下的位置信息对象
- * 仅在开发环境下返回位置信息，生产环境返回 null
+ * 仅在开发模式且节点有位置信息时返回
  * @param ctx - 转换上下文
- * @param node - AST 节点或位置信息
+ * @param node - AST 节点或包含 loc 属性的对象
  * @returns 位置信息对象或 null
  */
 export declare function getDevLocInfo(ctx: TransformContext, node: t.Node | {