@wevu/compiler 0.0.3 → 0.0.5

package/dist/index.d.mts

@@ -4,7 +4,13 @@ import * as t from "@babel/types";
 import { Expression } from "@babel/types";
 
 //#region src/auto-import-components/builtin.d.ts
+/**
+ * 内置组件集合（来自自动生成的组件列表）。
+ */
 declare const builtinComponentsSet: Set<string>;
+/**
+ * 判断标签是否为内置组件。
+ */
 declare function isBuiltinComponent(tag: string): boolean;
 //#endregion
 //#region src/constants.d.ts
@@ -20,7 +26,13 @@ declare const WE_VU_PAGE_HOOK_TO_FEATURE: {
   readonly onAddToFavorites: "enableOnAddToFavorites";
   readonly onSaveExitState: "enableOnSaveExitState";
 };
+/**
+ * wevu 运行时模块 ID。
+ */
 declare const WE_VU_MODULE_ID: "wevu";
+/**
+ * wevu 运行时 API 名称映射。
+ */
 declare const WE_VU_RUNTIME_APIS: {
   readonly createApp: "createApp";
   readonly createWevuComponent: "createWevuComponent";
@@ -28,6 +40,9 @@ declare const WE_VU_RUNTIME_APIS: {
   readonly defineComponent: "defineComponent";
   readonly setWevuDefaults: "setWevuDefaults";
 };
+/**
+ * wevu 运行时 API 名称类型。
+ */
 type WevuRuntimeApiName = (typeof WE_VU_RUNTIME_APIS)[keyof typeof WE_VU_RUNTIME_APIS];
 //#endregion
 //#region src/plugins/utils/cache.d.ts
@@ -46,13 +61,25 @@ declare function readFile(id: string, options?: {
   checkMtime?: boolean;
   encoding?: BufferEncoding;
 }): Promise<string>;
+/**
+ * 判断文件或路径是否存在，可选缓存。
+ */
 declare function pathExists(id: string, options?: {
   ttlMs?: number;
 }): Promise<boolean>;
+/**
+ * 清理指定文件相关的缓存。
+ */
 declare function invalidateFileCache(id: string): void;
+/**
+ * 清空所有文件缓存。
+ */
 declare function clearFileCaches(): void;
 //#endregion
 //#region src/plugins/utils/vueSfc.d.ts
+/**
+ * 读取并解析 SFC 的配置。
+ */
 interface ReadAndParseSfcOptions {
   /**
    * 直接传入源码以跳过文件读取。
@@ -67,6 +94,9 @@ interface ReadAndParseSfcOptions {
    */
   resolveSrc?: ResolveSfcBlockSrcOptions;
 }
+/**
+ * 解析 SFC block `src` 的配置。
+ */
 interface ResolveSfcBlockSrcOptions {
   resolveId?: (source: string, importer?: string) => Promise<string | undefined>;
   readFile?: (id: string, options?: {
@@ -74,30 +104,57 @@ interface ResolveSfcBlockSrcOptions {
   }) => Promise<string>;
   checkMtime?: boolean;
 }
+/**
+ * 预处理 `<script setup src>`，避免编译器丢失 src。
+ */
 declare function preprocessScriptSetupSrc(source: string): string;
+/**
+ * 预处理普通 `<script src>`，避免编译器丢失 src。
+ */
 declare function preprocessScriptSrc(source: string): string;
+/**
+ * 将预处理的 `<script setup src>` 恢复为真实 src。
+ */
 declare function restoreScriptSetupSrc(descriptor: SFCDescriptor): void;
+/**
+ * 将预处理的 `<script src>` 恢复为真实 src。
+ */
 declare function restoreScriptSrc(descriptor: SFCDescriptor): void;
+/**
+ * 解析 SFC 中带 `src` 的 block，并返回依赖列表。
+ */
 declare function resolveSfcBlockSrc(descriptor: SFCDescriptor, filename: string, options?: ResolveSfcBlockSrcOptions): Promise<{
   descriptor: SFCDescriptor;
   deps: string[];
 }>;
+/**
+ * 读取并解析 SFC，支持缓存与 src 解析。
+ */
 declare function readAndParseSfc(filename: string, options?: ReadAndParseSfcOptions): Promise<{
   source: string;
   descriptor: SFCDescriptor;
   errors: SFCParseResult['errors'];
 }>;
+/**
+ * 获取 SFC 读取时是否检查 mtime 的策略。
+ */
 declare function getSfcCheckMtime(config?: {
   isDev?: boolean;
 }): boolean;
 //#endregion
 //#region src/plugins/vue/compiler/style.d.ts
+/**
+ * 样式编译结果。
+ */
 interface StyleCompileResult {
   code: string;
   map?: string;
   scopedId?: string;
   modules?: Record<string, Record<string, string>>;
 }
+/**
+ * 样式编译选项。
+ */
 interface StyleCompileOptions {
   id: string;
   scoped?: boolean;
@@ -110,6 +167,9 @@ interface StyleCompileOptions {
 declare function compileVueStyleToWxss(styleBlock: SFCStyleBlock, options: StyleCompileOptions): StyleCompileResult;
 //#endregion
 //#region src/plugins/vue/compiler/template/platform.d.ts
+/**
+ * 小程序模板平台适配器定义。
+ */
 interface MiniProgramPlatform {
   name: string;
   wrapIf: (exp: string, content: string) => string;
@@ -123,6 +183,9 @@ interface MiniProgramPlatform {
 }
 //#endregion
 //#region src/plugins/vue/compiler/template/types.d.ts
+/**
+ * 作用域插槽组件资源描述。
+ */
 interface ScopedSlotComponentAsset {
   id: string;
   componentName: string;
@@ -132,11 +195,17 @@ interface ScopedSlotComponentAsset {
   classStyleWxs?: boolean;
   inlineExpressions?: InlineExpressionAsset[];
 }
+/**
+ * 内联表达式资源描述。
+ */
 interface InlineExpressionAsset {
   id: string;
   expression: string;
   scopeKeys: string[];
 }
+/**
+ * 模板编译结果。
+ */
 interface TemplateCompileResult {
   code: string;
   warnings: string[];
@@ -148,6 +217,9 @@ interface TemplateCompileResult {
   templateRefs?: TemplateRefBinding[];
   inlineExpressions?: InlineExpressionAsset[];
 }
+/**
+ * v-for 解析结果。
+ */
 interface ForParseResult {
   listExp?: string;
   listExpAst?: Expression;
@@ -155,6 +227,9 @@ interface ForParseResult {
   index?: string;
   key?: string;
 }
+/**
+ * 模板编译选项。
+ */
 interface TemplateCompileOptions {
   platform?: MiniProgramPlatform;
   scopedSlotsCompiler?: ScopedSlotsCompilerMode;
@@ -164,8 +239,17 @@ interface TemplateCompileOptions {
   wxsExtension?: string;
   classStyleWxsSrc?: string;
 }
+/**
+ * 作用域插槽编译模式。
+ */
 type ScopedSlotsCompilerMode = 'auto' | 'augmented' | 'off';
+/**
+ * class/style 运行时模式。
+ */
 type ClassStyleRuntime = 'wxs' | 'js';
+/**
+ * class/style 绑定信息。
+ */
 interface ClassStyleBinding {
   name: string;
   type: 'class' | 'style';
@@ -173,6 +257,9 @@ interface ClassStyleBinding {
   expAst?: Expression;
   forStack: ForParseResult[];
 }
+/**
+ * template ref 绑定信息。
+ */
 interface TemplateRefBinding {
   selector: string;
   inFor: boolean;
@@ -182,30 +269,63 @@ interface TemplateRefBinding {
 }
 //#endregion
 //#region src/types/platform.d.ts
+/**
+ * 小程序平台标识。
+ */
 type MpPlatform = 'weapp' | 'alipay' | 'tt' | 'swan' | 'jd' | 'xhs';
 //#endregion
 //#region src/plugins/vue/compiler/template/platforms/alipay.d.ts
+/**
+ * 支付宝小程序平台适配器。
+ */
 declare const alipayPlatform: MiniProgramPlatform;
 //#endregion
 //#region src/plugins/vue/compiler/template/platforms/swan.d.ts
+/**
+ * 百度智能小程序平台适配器。
+ */
 declare const swanPlatform: MiniProgramPlatform;
 //#endregion
 //#region src/plugins/vue/compiler/template/platforms/tt.d.ts
+/**
+ * 抖音小程序平台适配器。
+ */
 declare const ttPlatform: MiniProgramPlatform;
 //#endregion
 //#region src/plugins/vue/compiler/template/platforms/wechat.d.ts
+/**
+ * 微信小程序平台适配器。
+ */
 declare const wechatPlatform: MiniProgramPlatform;
 //#endregion
 //#region src/plugins/vue/compiler/template/platforms/index.d.ts
+/**
+ * 获取指定平台的模板适配器，默认回退到 wechat。
+ */
 declare function getMiniProgramTemplatePlatform(platform?: MpPlatform): MiniProgramPlatform;
 //#endregion
 //#region src/plugins/vue/compiler/template.d.ts
+/**
+ * 将 Vue 模板编译为 WXML。
+ */
 declare function compileVueTemplateToWxml(template: string, filename: string, options?: TemplateCompileOptions): TemplateCompileResult;
 //#endregion
 //#region src/plugins/vue/compiler/template/classStyleRuntime.d.ts
+/**
+ * class/style WXS 模块名。
+ */
 declare const CLASS_STYLE_WXS_MODULE = "__weapp_vite";
+/**
+ * class/style WXS 文件名（不含扩展名）。
+ */
 declare const CLASS_STYLE_WXS_FILE = "__weapp_vite_class_style";
+/**
+ * 构建 class/style WXS 引用标签。
+ */
 declare function buildClassStyleWxsTag(extension: string, src?: string): string;
+/**
+ * 解析 class/style WXS 文件位置与引用路径。
+ */
 declare function resolveClassStyleWxsLocation(options: {
   relativeBase: string;
   extension: string;
@@ -214,6 +334,9 @@ declare function resolveClassStyleWxsLocation(options: {
   fileName: string;
   src: string;
 };
+/**
+ * 获取内置 class/style WXS 运行时代码。
+ */
 declare function getClassStyleWxsSource(): string;
 //#endregion
 //#region src/plugins/vue/transform/classStyleComputed.d.ts
@@ -224,14 +347,29 @@ interface ClassStyleHelperNames {
 declare function buildClassStyleComputedCode(bindings: ClassStyleBinding[], helpers: ClassStyleHelperNames): string | null;
 //#endregion
 //#region src/types/json.d.ts
+/**
+ * JSON 合并阶段枚举。
+ */
 type JsonMergeStage = 'defaults' | 'json-block' | 'auto-using-components' | 'component-generics' | 'macro' | 'emit' | 'merge-existing';
+/**
+ * JSON 合并上下文。
+ */
 interface JsonMergeContext {
   filename?: string;
   kind?: 'app' | 'page' | 'component' | 'unknown';
   stage: JsonMergeStage;
 }
+/**
+ * JSON 合并函数。
+ */
 type JsonMergeFunction = (target: Record<string, any>, source: Record<string, any>, context: JsonMergeContext) => Record<string, any> | void;
+/**
+ * JSON 合并策略。
+ */
 type JsonMergeStrategy = 'deep' | 'assign' | 'replace' | JsonMergeFunction;
+/**
+ * JSON 产物配置。
+ */
 interface JsonConfig {
   /**
    * 产物 JSON 默认值（用于 app/page/component）
@@ -252,12 +390,18 @@ interface JsonConfig {
 }
 //#endregion
 //#region src/types/wevu.d.ts
+/**
+ * wevu JSON 默认值配置（app/component）。
+ */
 interface WevuDefaults {
   app?: Record<string, any>;
   component?: Record<string, any>;
 }
 //#endregion
 //#region src/plugins/vue/transform/compileVueFile/types.d.ts
+/**
+ * Vue 单文件组件转换结果。
+ */
 interface VueTransformResult {
   script?: string;
   template?: string;
@@ -275,6 +419,9 @@ interface VueTransformResult {
     sfcSrcDeps?: string[];
   };
 }
+/**
+ * 自动生成 usingComponents 选项。
+ */
 interface AutoUsingComponentsOptions {
   enabled?: boolean;
   resolveUsingComponentPath?: (importSource: string, importerFilename: string, info?: {
@@ -284,6 +431,9 @@ interface AutoUsingComponentsOptions {
   }) => Promise<string | undefined>;
   warn?: (message: string) => void;
 }
+/**
+ * 自动导入模板标签组件选项。
+ */
 interface AutoImportTagsOptions {
   enabled?: boolean;
   resolveUsingComponent?: (tag: string, importerFilename: string) => Promise<{
@@ -292,6 +442,9 @@ interface AutoImportTagsOptions {
   } | undefined>;
   warn?: (message: string) => void;
 }
+/**
+ * 编译 Vue SFC 的选项集合。
+ */
 interface CompileVueFileOptions {
   isPage?: boolean;
   isApp?: boolean;
@@ -309,22 +462,49 @@ interface CompileVueFileOptions {
 }
 //#endregion
 //#region src/plugins/vue/transform/compileVueFile/index.d.ts
+/**
+ * 编译 Vue 单文件组件，输出脚本、模板、样式与配置结果。
+ */
 declare function compileVueFile(source: string, filename: string, options?: CompileVueFileOptions): Promise<VueTransformResult>;
 //#endregion
 //#region src/plugins/vue/transform/config.d.ts
+/**
+ * JS 配置块的语言类型。
+ */
 type JsLikeLang = 'js' | 'ts';
+/**
+ * 规范化配置块语言。
+ */
 declare function normalizeConfigLang(lang?: string): string;
+/**
+ * 判断是否为 JSON 类语言。
+ */
 declare function isJsonLikeLang(lang: string): lang is "json" | "jsonc" | "json5";
+/**
+ * 将语言标识归一为 js/ts。
+ */
 declare function resolveJsLikeLang(lang: string): JsLikeLang;
+/**
+ * 执行 JS/TS 配置块并返回对象结果。
+ */
 declare function evaluateJsLikeConfig(source: string, filename: string, lang: string): Promise<any>;
+/**
+ * 编译 SFC 内的 <json> 配置块并返回 JSON 字符串。
+ */
 declare function compileConfigBlocks(blocks: SFCBlock[], filename: string, options?: {
   merge?: (target: Record<string, any>, source: Record<string, any>) => Record<string, any> | void;
 }): Promise<string | undefined>;
 //#endregion
 //#region src/plugins/vue/transform/jsonMacros/rewrite.d.ts
+/**
+ * 从任意代码中剥离 JSON 宏调用。
+ */
 declare function stripJsonMacroCallsFromCode(code: string, filename: string): string;
 //#endregion
 //#region src/plugins/vue/transform/jsonMacros/index.d.ts
+/**
+ * 从 `<script setup>` 中提取 JSON 宏配置并返回剥离后的代码。
+ */
 declare function extractJsonMacroFromScriptSetup(content: string, filename: string, lang?: string, options?: {
   merge?: (target: Record<string, any>, source: Record<string, any>) => Record<string, any> | void;
 }): Promise<{
@@ -335,7 +515,13 @@ declare function extractJsonMacroFromScriptSetup(content: string, filename: stri
 }>;
 //#endregion
 //#region src/plugins/vue/transform/jsonMerge.d.ts
+/**
+ * 按策略合并 JSON 配置对象。
+ */
 declare function mergeJsonWithStrategy(target: Record<string, any>, source: Record<string, any>, strategy: JsonMergeStrategy | undefined, context: JsonMergeContext): Record<string, any>;
+/**
+ * 创建带上下文的 JSON 合并函数。
+ */
 declare function createJsonMerger(strategy: JsonMergeStrategy | undefined, baseContext: Omit<JsonMergeContext, 'stage'>): (target: Record<string, any>, source: Record<string, any>, stage: JsonMergeContext["stage"]) => Record<string, any>;
 //#endregion
 //#region src/plugins/vue/transform/scopedId.d.ts
@@ -400,25 +586,49 @@ interface TransformScriptOptions {
 }
 //#endregion
 //#region src/plugins/vue/transform/transformScript/index.d.ts
+/**
+ * 转换 Vue SFC 脚本：处理宏、导入、默认导出与 wevu 相关注入。
+ */
 declare function transformScript(source: string, options?: TransformScriptOptions): TransformResult;
 //#endregion
 //#region src/plugins/wevu/pageFeatures/types.d.ts
+/**
+ * wevu 页面特性标识（由钩子映射表推导）。
+ */
 type WevuPageFeatureFlag = (typeof WE_VU_PAGE_HOOK_TO_FEATURE)[keyof typeof WE_VU_PAGE_HOOK_TO_FEATURE];
+/**
+ * wevu 页面钩子名称。
+ */
 type WevuPageHookName = keyof typeof WE_VU_PAGE_HOOK_TO_FEATURE;
+/**
+ * 模块解析器，用于注入特性时按需解析模块与源码。
+ */
 interface ModuleResolver {
   resolveId: (source: string, importer: string) => Promise<string | undefined>;
   loadCode: (id: string) => Promise<string | undefined>;
 }
 //#endregion
 //#region src/plugins/wevu/pageFeatures/flags.d.ts
+/**
+ * 扫描 AST，收集启用的 wevu 页面特性标识。
+ */
 declare function collectWevuPageFeatureFlags(ast: t.File): Set<WevuPageFeatureFlag>;
+/**
+ * 将启用的页面特性注入到 options 对象中。
+ */
 declare function injectWevuPageFeatureFlagsIntoOptionsObject(optionsObject: t.ObjectExpression, enabled: Set<WevuPageFeatureFlag>): boolean;
 //#endregion
 //#region src/plugins/wevu/pageFeatures/inject.d.ts
+/**
+ * 在 JS 源码中注入 wevu 页面特性（基于本文件分析）。
+ */
 declare function injectWevuPageFeaturesInJs(source: string): {
   code: string;
   transformed: boolean;
 };
+/**
+ * 在 JS 源码中注入 wevu 页面特性（支持跨模块解析）。
+ */
 declare function injectWevuPageFeaturesInJsWithResolver(source: string, options: {
   id: string;
   resolver: ModuleResolver;
@@ -428,6 +638,9 @@ declare function injectWevuPageFeaturesInJsWithResolver(source: string, options:
 }>;
 //#endregion
 //#region src/plugins/wevu/pageFeatures/matcher.d.ts
+/**
+ * 页面入口匹配器的数据源。
+ */
 interface PageEntryMatcherSource {
   srcRoot: string;
   loadEntries: () => Promise<{
@@ -440,6 +653,9 @@ interface PageEntryMatcherSource {
   }>;
   warn?: (message: string) => void;
 }
+/**
+ * 创建页面入口匹配器。
+ */
 declare function createPageEntryMatcher(source: PageEntryMatcherSource): {
   markDirty(): void;
   isPageFile(filePath: string): Promise<boolean>;
@@ -448,13 +664,22 @@ declare function createPageEntryMatcher(source: PageEntryMatcherSource): {
 //#region src/utils/vueTemplateTags.d.ts
 declare const RESERVED_VUE_COMPONENT_TAGS: Set<string>;
 declare const VUE_COMPONENT_TAG_RE: RegExp;
+/**
+ * 判断模板标签是否可能需要自动导入。
+ */
 declare function isAutoImportCandidateTag(tag: string): boolean;
+/**
+ * 模板标签收集配置。
+ */
 interface CollectVueTemplateTagsOptions {
   filename?: string;
   warnLabel?: string;
   warn?: (message: string) => void;
   shouldCollect: (tag: string) => boolean;
 }
+/**
+ * 收集 Vue 模板中的自定义组件标签。
+ */
 declare function collectVueTemplateTags(template: string, options: CollectVueTemplateTagsOptions): Set<string>;
 //#endregion
 export { type AutoImportTagsOptions, type AutoUsingComponentsOptions, CLASS_STYLE_WXS_FILE, CLASS_STYLE_WXS_MODULE, type ClassStyleBinding, type ClassStyleRuntime, type CollectVueTemplateTagsOptions, type CompileVueFileOptions, type ForParseResult, type InlineExpressionAsset, type JsLikeLang, type JsonConfig, type JsonMergeContext, type JsonMergeStage, type JsonMergeStrategy, type MiniProgramPlatform, type ModuleResolver, type MpPlatform, RESERVED_VUE_COMPONENT_TAGS, type ReadAndParseSfcOptions, type ResolveSfcBlockSrcOptions, type ScopedSlotComponentAsset, type StyleCompileOptions, type StyleCompileResult, type TemplateCompileOptions, type TemplateCompileResult, type TemplateRefBinding, type TransformResult, type TransformScriptOptions, VUE_COMPONENT_TAG_RE, type VueTransformResult, WE_VU_MODULE_ID, WE_VU_PAGE_HOOK_TO_FEATURE, WE_VU_RUNTIME_APIS, type WevuDefaults, type WevuPageFeatureFlag, type WevuPageHookName, WevuRuntimeApiName, alipayPlatform, buildClassStyleComputedCode, buildClassStyleWxsTag, builtinComponentsSet, clearFileCaches, collectVueTemplateTags, collectWevuPageFeatureFlags, compileConfigBlocks, compileVueFile as compileSfc, compileVueFile, compileVueStyleToWxss as compileStyle, compileVueStyleToWxss, compileVueTemplateToWxml as compileTemplate, compileVueTemplateToWxml, createJsonMerger, createPageEntryMatcher, evaluateJsLikeConfig, extractJsonMacroFromScriptSetup, generateScopedId, getClassStyleWxsSource, getMiniProgramTemplatePlatform, getSfcCheckMtime, injectWevuPageFeatureFlagsIntoOptionsObject, injectWevuPageFeaturesInJs, injectWevuPageFeaturesInJsWithResolver, invalidateFileCache, isAutoImportCandidateTag, isBuiltinComponent, isInvalidate, isJsonLikeLang, loadCache, mergeJsonWithStrategy, mtimeCache, normalizeConfigLang, pathExists, preprocessScriptSetupSrc, preprocessScriptSrc, readAndParseSfc, readFile, resolveClassStyleWxsLocation, resolveJsLikeLang, resolveSfcBlockSrc, restoreScriptSetupSrc, restoreScriptSrc, stripJsonMacroCallsFromCode, swanPlatform, transformScript, transformScript as transformSfcScript, ttPlatform, wechatPlatform };

package/dist/index.mjs

@@ -111,7 +111,13 @@ const components = [
 
 //#endregion
 //#region src/auto-import-components/builtin.ts
+/**
+* 内置组件集合（来自自动生成的组件列表）。
+*/
 const builtinComponentsSet = new Set(components);
+/**
+* 判断标签是否为内置组件。
+*/
 function isBuiltinComponent(tag) {
 	return builtinComponentsSet.has(tag);
 }
@@ -130,7 +136,13 @@ const WE_VU_PAGE_HOOK_TO_FEATURE = {
 	onAddToFavorites: "enableOnAddToFavorites",
 	onSaveExitState: "enableOnSaveExitState"
 };
+/**
+* wevu 运行时模块 ID。
+*/
 const WE_VU_MODULE_ID = "wevu";
+/**
+* wevu 运行时 API 名称映射。
+*/
 const WE_VU_RUNTIME_APIS = {
 	createApp: "createApp",
 	createWevuComponent: "createWevuComponent",
@@ -188,6 +200,9 @@ async function readFile(id, options) {
 	loadCache.set(id, content);
 	return content;
 }
+/**
+* 判断文件或路径是否存在，可选缓存。
+*/
 async function pathExists(id, options) {
 	const ttlMs = options?.ttlMs;
 	const cached = pathExistsCache.get(id);
@@ -197,11 +212,17 @@ async function pathExists(id, options) {
 	else pathExistsCache.set(id, exists);
 	return exists;
 }
+/**
+* 清理指定文件相关的缓存。
+*/
 function invalidateFileCache(id) {
 	mtimeCache.delete(id);
 	loadCache.delete(id);
 	pathExistsCache.delete(id);
 }
+/**
+* 清空所有文件缓存。
+*/
 function clearFileCaches() {
 	mtimeCache.clear();
 	loadCache.clear();
@@ -210,6 +231,9 @@ function clearFileCaches() {
 
 //#endregion
 //#region src/utils/cachePolicy.ts
+/**
+* 获取 readFile 是否检查 mtime 的策略。
+*/
 function getReadFileCheckMtime(config) {
 	return Boolean(config?.isDev);
 }
@@ -299,6 +323,9 @@ function getBlockLabel(kind) {
 	if (kind === "script setup") return "script setup";
 	return kind;
 }
+/**
+* 预处理 `<script setup src>`，避免编译器丢失 src。
+*/
 function preprocessScriptSetupSrc(source) {
 	if (!source.includes("<script") || !source.includes("setup") || !source.includes("src")) return source;
 	return source.replace(SCRIPT_SETUP_TAG_RE, (full, attrs) => {
@@ -306,6 +333,9 @@ function preprocessScriptSetupSrc(source) {
 		return `<script${attrs.replace(/\bsrc(\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+))/i, `${SCRIPT_SETUP_SRC_ATTR}$1`)}>`;
 	});
 }
+/**
+* 预处理普通 `<script src>`，避免编译器丢失 src。
+*/
 function preprocessScriptSrc(source) {
 	if (!source.includes("<script") || !source.includes("src")) return source;
 	return source.replace(SCRIPT_SETUP_TAG_RE, (full, attrs) => {
@@ -313,6 +343,9 @@ function preprocessScriptSrc(source) {
 		return `<script${attrs.replace(/\bsrc(\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+))/i, `${SCRIPT_SRC_ATTR}$1`)}>`;
 	});
 }
+/**
+* 将预处理的 `<script setup src>` 恢复为真实 src。
+*/
 function restoreScriptSetupSrc(descriptor) {
 	const scriptSetup = descriptor.scriptSetup;
 	if (!scriptSetup?.attrs || !(SCRIPT_SETUP_SRC_ATTR in scriptSetup.attrs)) return;
@@ -320,6 +353,9 @@ function restoreScriptSetupSrc(descriptor) {
 	if (typeof raw === "string") scriptSetup.src = raw;
 	delete scriptSetup.attrs[SCRIPT_SETUP_SRC_ATTR];
 }
+/**
+* 将预处理的 `<script src>` 恢复为真实 src。
+*/
 function restoreScriptSrc(descriptor) {
 	const script = descriptor.script;
 	if (!script?.attrs || !(SCRIPT_SRC_ATTR in script.attrs)) return;
@@ -356,6 +392,9 @@ async function readBlockContent(resolvedId, filename, options) {
 		throw new Error(`解析 ${filename} 失败：读取 ${resolvedId} 失败：${message}`);
 	}
 }
+/**
+* 解析 SFC 中带 `src` 的 block，并返回依赖列表。
+*/
 async function resolveSfcBlockSrc(descriptor, filename, options) {
 	if (!options) return {
 		descriptor,
@@ -388,6 +427,9 @@ async function resolveSfcBlockSrc(descriptor, filename, options) {
 		deps: Array.from(deps)
 	};
 }
+/**
+* 读取并解析 SFC，支持缓存与 src 解析。
+*/
 async function readAndParseSfc(filename, options) {
 	const checkMtime = options?.checkMtime ?? true;
 	const source = options?.source ?? await readFile(filename, { checkMtime });
@@ -435,6 +477,9 @@ async function readAndParseSfc(filename, options) {
 		errors: parsed.errors
 	};
 }
+/**
+* 获取 SFC 读取时是否检查 mtime 的策略。
+*/
 function getSfcCheckMtime(config) {
 	return getReadFileCheckMtime(config);
 }
@@ -533,16 +578,28 @@ function normalizeRoot(root) {
 
 //#endregion
 //#region src/plugins/vue/compiler/template/classStyleRuntime.ts
+/**
+* class/style WXS 模块名。
+*/
 const CLASS_STYLE_WXS_MODULE = "__weapp_vite";
+/**
+* class/style WXS 文件名（不含扩展名）。
+*/
 const CLASS_STYLE_WXS_FILE = "__weapp_vite_class_style";
 function resolveScriptModuleTag(extension) {
 	return (extension.startsWith(".") ? extension.slice(1) : extension) === "sjs" ? "sjs" : "wxs";
 }
+/**
+* 构建 class/style WXS 引用标签。
+*/
 function buildClassStyleWxsTag(extension, src) {
 	const normalized = extension.startsWith(".") ? extension.slice(1) : extension;
 	const resolvedSrc = src ?? `./${CLASS_STYLE_WXS_FILE}.${normalized}`;
 	return `<${resolveScriptModuleTag(normalized)} module="${CLASS_STYLE_WXS_MODULE}" src="${resolvedSrc}"/>`;
 }
+/**
+* 解析 class/style WXS 文件位置与引用路径。
+*/
 function resolveClassStyleWxsLocation(options) {
 	const normalizedExt = options.extension.startsWith(".") ? options.extension.slice(1) : options.extension;
 	const normalizedRoot = normalizeRoot(options.packageRoot ?? "");
@@ -557,6 +614,9 @@ function resolveClassStyleWxsLocation(options) {
 		src
 	};
 }
+/**
+* 获取内置 class/style WXS 运行时代码。
+*/
 function getClassStyleWxsSource() {
 	return [
 		"var objectCtor = ({}).constructor",
@@ -2376,6 +2436,9 @@ function toOnEventName(eventName) {
 	if (!eventName) return "on";
 	return `on${(eventName[0] ?? "").toUpperCase()}${eventName.slice(1)}`;
 }
+/**
+* 支付宝小程序平台适配器。
+*/
 const alipayPlatform = {
 	name: "alipay",
 	wrapIf: (exp, content) => `<block a:if="{{${exp}}}">${content}</block>`,
@@ -2420,6 +2483,9 @@ const eventMap$2 = {
 	longtap: "longtap",
 	longpress: "longpress"
 };
+/**
+* 百度智能小程序平台适配器。
+*/
 const swanPlatform = {
 	name: "swan",
 	wrapIf: (exp, content) => `<block s-if="{{${exp}}}">${content}</block>`,
@@ -2463,6 +2529,9 @@ const eventMap$1 = {
 	longtap: "longtap",
 	longpress: "longpress"
 };
+/**
+* 抖音小程序平台适配器。
+*/
 const ttPlatform = {
 	name: "tt",
 	wrapIf: (exp, content) => `<block tt:if="{{${exp}}}">${content}</block>`,
@@ -2506,6 +2575,9 @@ const eventMap = {
 	longtap: "longtap",
 	longpress: "longpress"
 };
+/**
+* 微信小程序平台适配器。
+*/
 const wechatPlatform = {
 	name: "wechat",
 	wrapIf: (exp, content) => `<block wx:if="{{${exp}}}">${content}</block>`,
@@ -2535,6 +2607,9 @@ const TEMPLATE_PLATFORMS = {
 	jd: wechatPlatform,
 	xhs: wechatPlatform
 };
+/**
+* 获取指定平台的模板适配器，默认回退到 wechat。
+*/
 function getMiniProgramTemplatePlatform(platform) {
 	if (!platform) return wechatPlatform;
 	return TEMPLATE_PLATFORMS[platform] ?? wechatPlatform;
@@ -2542,6 +2617,9 @@ function getMiniProgramTemplatePlatform(platform) {
 
 //#endregion
 //#region src/plugins/vue/compiler/template.ts
+/**
+* 将 Vue 模板编译为 WXML。
+*/
 function compileVueTemplateToWxml(template, filename, options) {
 	const warnings = [];
 	const runtimeMode = options?.classStyleRuntime ?? "auto";
@@ -2711,9 +2789,15 @@ const RESERVED_VUE_COMPONENT_TAGS = new Set([
 	"suspense"
 ]);
 const VUE_COMPONENT_TAG_RE = /^[A-Z_$][\w$]*$/i;
+/**
+* 判断模板标签是否可能需要自动导入。
+*/
 function isAutoImportCandidateTag(tag) {
 	return tag.includes("-") || /^[A-Z][\w$]*$/.test(tag);
 }
+/**
+* 收集 Vue 模板中的自定义组件标签。
+*/
 function collectVueTemplateTags(template, options) {
 	const tags = /* @__PURE__ */ new Set();
 	const warn = options.warn;
@@ -2748,6 +2832,9 @@ function collectVueTemplateTags(template, options) {
 
 //#endregion
 //#region src/utils/warn.ts
+/**
+* 解析警告处理函数，未提供时回退到 console.warn。
+*/
 function resolveWarnHandler(warn) {
 	return warn ?? ((message) => {
 		console.warn(message);
@@ -2843,19 +2930,31 @@ function resolveWevuConfigTempDir(fromDir) {
 
 //#endregion
 //#region src/plugins/vue/transform/config.ts
+/**
+* 规范化配置块语言。
+*/
 function normalizeConfigLang(lang) {
 	if (!lang) return "json";
 	const lower = lang.toLowerCase();
 	if (lower === "txt") return "json";
 	return lower;
 }
+/**
+* 判断是否为 JSON 类语言。
+*/
 function isJsonLikeLang(lang) {
 	return lang === "json" || lang === "jsonc" || lang === "json5";
 }
+/**
+* 将语言标识归一为 js/ts。
+*/
 function resolveJsLikeLang(lang) {
 	if (lang === "ts" || lang === "tsx" || lang === "cts" || lang === "mts") return "ts";
 	return "js";
 }
+/**
+* 执行 JS/TS 配置块并返回对象结果。
+*/
 async function evaluateJsLikeConfig(source, filename, lang) {
 	const dir = path.dirname(filename);
 	const extension = resolveJsLikeLang(lang) === "ts" ? "ts" : "js";
@@ -2887,6 +2986,9 @@ async function evaluateJsLikeConfig(source, filename, lang) {
 		}
 	});
 }
+/**
+* 编译 SFC 内的 <json> 配置块并返回 JSON 字符串。
+*/
 async function compileConfigBlocks(blocks, filename, options) {
 	const jsonBlocks = blocks.filter((block) => block.type === "json");
 	if (!jsonBlocks.length) return;
@@ -3212,6 +3314,9 @@ function findProgramPath(ast) {
 
 //#endregion
 //#region src/plugins/vue/transform/jsonMacros/rewrite.ts
+/**
+* 移除 `<script setup>` 中的 JSON 宏语句，返回剥离后的代码与宏源码片段。
+*/
 function stripScriptSetupMacroStatements(content, ast, filename) {
 	const ms = new MagicString(content);
 	const macroStatementSources = [];
@@ -3231,6 +3336,9 @@ function stripScriptSetupMacroStatements(content, ast, filename) {
 		macroStatementSources
 	};
 }
+/**
+* 从任意代码中剥离 JSON 宏调用。
+*/
 function stripJsonMacroCallsFromCode(code, filename) {
 	let ast;
 	try {
@@ -3258,6 +3366,9 @@ function stripJsonMacroCallsFromCode(code, filename) {
 
 //#endregion
 //#region src/plugins/vue/transform/jsonMacros/index.ts
+/**
+* 从 `<script setup>` 中提取 JSON 宏配置并返回剥离后的代码。
+*/
 async function extractJsonMacroFromScriptSetup(content, filename, lang, options) {
 	const ast = parseScriptSetupAst(content, filename);
 	const { macroNames } = collectMacroCallPaths(ast, filename);
@@ -3302,6 +3413,9 @@ function toPlainRecord(value) {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return {};
 	return value;
 }
+/**
+* 按策略合并 JSON 配置对象。
+*/
 function mergeJsonWithStrategy(target, source, strategy, context) {
 	const base = { ...toPlainRecord(target) };
 	const incoming = toPlainRecord(source);
@@ -3319,6 +3433,9 @@ function mergeJsonWithStrategy(target, source, strategy, context) {
 	recursive(merged, incoming);
 	return merged;
 }
+/**
+* 创建带上下文的 JSON 合并函数。
+*/
 function createJsonMerger(strategy, baseContext) {
 	return (target, source, stage) => {
 		return mergeJsonWithStrategy(target, source, strategy, {
@@ -3467,6 +3584,9 @@ function isTopLevel(path) {
 
 //#endregion
 //#region src/plugins/wevu/pageFeatures/flags.ts
+/**
+* 扫描 AST，收集启用的 wevu 页面特性标识。
+*/
 function collectWevuPageFeatureFlags(ast) {
 	const namedHookLocals = /* @__PURE__ */ new Map();
 	const namespaceLocals = /* @__PURE__ */ new Set();
@@ -3514,6 +3634,9 @@ function collectWevuPageFeatureFlags(ast) {
 	});
 	return enabled;
 }
+/**
+* 将启用的页面特性注入到 options 对象中。
+*/
 function injectWevuPageFeatureFlagsIntoOptionsObject(optionsObject, enabled) {
 	if (!enabled.size) return false;
 	const expectedKeys = Array.from(enabled);
@@ -3980,6 +4103,9 @@ async function collectWevuFeaturesFromSetupReachableImports(pageModule, setupFn,
 
 //#endregion
 //#region src/plugins/wevu/pageFeatures/inject.ts
+/**
+* 在 JS 源码中注入 wevu 页面特性（基于本文件分析）。
+*/
 function injectWevuPageFeaturesInJs(source) {
 	const ast = parseJsLike(source);
 	const enabled = collectWevuPageFeatureFlags(ast);
@@ -4003,6 +4129,9 @@ function injectWevuPageFeaturesInJs(source) {
 		transformed: true
 	};
 }
+/**
+* 在 JS 源码中注入 wevu 页面特性（支持跨模块解析）。
+*/
 async function injectWevuPageFeaturesInJsWithResolver(source, options) {
 	const ast = parseJsLike(source);
 	const { optionsObjects, module } = collectTargetOptionsObjects(ast, options.id);
@@ -4038,6 +4167,9 @@ async function injectWevuPageFeaturesInJsWithResolver(source, options) {
 
 //#endregion
 //#region src/plugins/wevu/pageFeatures/matcher.ts
+/**
+* 创建页面入口匹配器。
+*/
 function createPageEntryMatcher(source) {
 	let cached;
 	const warn = resolveWarnHandler(source.warn);
@@ -4827,6 +4959,9 @@ function rewriteDefaultExport(ast, state, options, enabledPageFeatures, serializ
 
 //#endregion
 //#region src/plugins/vue/transform/transformScript/index.ts
+/**
+* 转换 Vue SFC 脚本：处理宏、导入、默认导出与 wevu 相关注入。
+*/
 function transformScript(source, options) {
 	const ast = parse$2(source, BABEL_TS_MODULE_PARSER_OPTIONS);
 	const warn = resolveWarnHandler(options?.warn);
@@ -5002,6 +5137,9 @@ function compileTemplatePhase(descriptor, filename, options, result) {
 
 //#endregion
 //#region src/plugins/vue/transform/compileVueFile/index.ts
+/**
+* 编译 Vue 单文件组件，输出脚本、模板、样式与配置结果。
+*/
 async function compileVueFile(source, filename, options) {
 	const parsed = await parseVueFile(source, filename, options);
 	const result = { meta: { ...parsed.meta } };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wevu/compiler",
   "type": "module",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "wevu 编译器基础包，面向小程序模板的编译与转换",
   "author": "ice breaker <1324318532@qq.com>",
   "license": "MIT",
@@ -41,7 +41,7 @@
     "dist"
   ],
   "dependencies": {
-    "@babel/generator": "^7.29.0",
+    "@babel/generator": "^7.29.1",
     "@babel/parser": "^7.29.0",
     "@babel/traverse": "^7.29.0",
     "@babel/types": "^7.29.0",
@@ -53,8 +53,8 @@
     "merge": "^2.1.1",
     "pathe": "^2.0.3",
     "vue": "^3.5.27",
-    "@weapp-core/shared": "3.0.0",
-    "rolldown-require": "2.0.3"
+    "@weapp-core/shared": "3.0.1",
+    "rolldown-require": "2.0.5"
   },
   "publishConfig": {
     "access": "public",