@wevu/compiler 7.2.2 → 7.4.0

package/README.md

@@ -41,7 +41,7 @@ console.log(result.template)
 
 ### 编译诊断
 
-`compileTemplate` 始终返回 `diagnostics`，`compileSfc` / `compileJsxFile` 在存在模板或 JSX 诊断时返回 `diagnostics`。每条诊断包含稳定的 `code`、`severity`、`filename`、`source` 和可选 `loc`：
+`compileTemplate` 始终返回 `diagnostics`，供调用方检查错误和警告。`compileSfc`（`compileVueFile`）遇到 error 级模板诊断或 SFC 解析错误时，会抛出公开的 `CompilerDiagnosticError`，不会返回静默降级的产物；warning 仍随成功结果返回。`compileJsxFile` 在存在 JSX 诊断时返回 `diagnostics`。每条诊断以及 `CompilerDiagnosticError` 均包含稳定的 `code`、`severity`、`message`、`filename`、`source` 和可选 `loc`。
 
 这是一次 clean cutover：原有 `warnings: string[]` 字段已移除，调用方应改读 `diagnostics`，需要展示文本时使用 `diagnostic.message`。
 
@@ -60,9 +60,9 @@ for (const diagnostic of result.diagnostics) {
 }
 ```
 
-稳定 code：`WV1001`（模板转换警告）、`WV1002`（模板表达式警告）、`WV1003`（JSX 警告）、`WV2001`（模板解析错误）、`WV2002`（模板编译错误）。
+稳定 code：`WV1001`（模板转换警告）、`WV1002`（模板表达式警告）、`WV1003`（JSX 警告）、`WV2001`（模板解析错误，含非法 `v-for`）、`WV2002`（模板编译错误）、`WV2003`（SFC 解析错误）。SFC 解析错误通过 `cause` 保留原始 Vue 错误及其数值 code，不将其混入稳定的 `WV*` code。
 
-`loc.start` / `loc.end` 使用半开区间；`offset` 从 0 开始，`line` / `column` 从 1 开始。`compileSfc` 会将内联 `<template>` 位置映射到完整 SFC 源码；外部 `<template src>` 则使用解析后的外部文件名和其自身位置。模板与 JSX 自有诊断会按 `diagnostic.message` 原样、仅一次地适配到 `warn` 回调，结构化消费应使用结果中的 `diagnostics`。
+`loc.start` / `loc.end` 使用半开区间；`offset` 从 0 开始，`line` / `column` 从 1 开始。`compileSfc` 会将内联 `<template>` 位置映射到完整 SFC 源码；外部 `<template src>` 则使用解析后的外部文件名和其自身位置。内置 `<json>` 和 `defineOptions` 改写后的 SFC 重解析错误也映射回输入源码，不依赖 `sourceMap` 开关。模板与 JSX 自有诊断会按 `diagnostic.message` 原样、仅一次地适配到 `warn` 回调；结构化消费应检查返回的 `diagnostics`，并捕获 `CompilerDiagnosticError`。
 
 使用页面特性工具：
 

package/dist/index.d.mts

@@ -18,7 +18,7 @@ export declare const builtinComponentsSet: Set<string>;
 export declare function isBuiltinComponent(tag: string): boolean;
 //#endregion
 //#region src/types/diagnostics.d.ts
-type CompilerDiagnosticCode = 'WV1002' | 'WV1003' | 'WV2002' | 'WV2001' | 'WV1001';
+type CompilerDiagnosticCode = 'WV1002' | 'WV1003' | 'WV2003' | 'WV2002' | 'WV2001' | 'WV1001';
 type CompilerDiagnosticSeverity = 'error' | 'warning';
 type CompilerDiagnosticSource = 'expression' | 'jsx' | 'script' | 'sfc' | 'style' | 'template';
 /**
@@ -47,6 +47,20 @@ interface CompilerDiagnostic {
   source: CompilerDiagnosticSource;
   loc?: SourceSpan;
 }
+/**
+ * 携带结构化编译诊断的致命错误。
+ */
+export declare class CompilerDiagnosticError extends Error implements CompilerDiagnostic {
+  readonly code: CompilerDiagnosticCode;
+  readonly severity: CompilerDiagnosticSeverity;
+  readonly filename: string;
+  readonly source: CompilerDiagnosticSource;
+  readonly loc?: SourceSpan;
+  readonly cause?: unknown;
+  constructor(diagnostic: CompilerDiagnostic, options?: {
+    cause?: unknown;
+  });
+}
 //#endregion
 //#region src/types/bindingManifest.d.ts
 /**
@@ -120,6 +134,7 @@ export declare function createRuntimeBindingManifest(manifest: WevuBindingManife
 //#region src/constants.d.ts
 export declare const WE_VU_PAGE_HOOK_TO_FEATURE: {
   readonly onPageScroll: "enableOnPageScroll";
+  readonly usePageScrollRestoration: "enableOnPageScroll";
   readonly onPullDownRefresh: "enableOnPullDownRefresh";
   readonly onReachBottom: "enableOnReachBottom";
   readonly onRouteDone: "enableOnRouteDone";
@@ -166,6 +181,8 @@ export declare const WE_VU_RUNTIME_MODULE_IDS: readonly ["wevu", "wevu/internal-
  * 判断模块 ID 是否为 wevu 运行时入口。
  */
 export declare function isWevuRuntimeModuleId(moduleId: string): boolean;
+/** 页面特性可由独立 router 入口的适配器启用，但该入口不提供组件工厂。 */
+export declare function isWevuPageFeatureModuleId(moduleId: string): boolean;
 /**
  * wevu 运行时 API 名称映射。
  */
@@ -194,6 +211,17 @@ export declare const WE_VU_INTERNAL_TEMPLATE_APIS: readonly ["normalizeClass", "
  */
 export declare function resolveWevuInternalImportModuleId(apiName: string): "virtual:weapp-vite/runtime" | "virtual:weapp-vite/runtime/reactivity" | "virtual:weapp-vite/runtime/template";
 //#endregion
+//#region src/utils/sourcemap.d.ts
+interface EncodedSourceMapLike {
+  version: number | string;
+  file?: string;
+  names: string[];
+  sourceRoot?: string;
+  sources: string[];
+  sourcesContent?: Array<string | null>;
+  mappings: string;
+}
+//#endregion
 //#region src/plugins/utils/vueSfcBlockSrc.d.ts
 /**
  * 解析 SFC block `src` 的配置。
@@ -273,17 +301,6 @@ export declare function getSfcCheckMtime(config?: {
   isDev?: boolean;
 }): boolean;
 //#endregion
-//#region src/utils/sourcemap.d.ts
-interface EncodedSourceMapLike {
-  version: number | string;
-  file?: string;
-  names: string[];
-  sourceRoot?: string;
-  sources: string[];
-  sourcesContent?: Array<string | null>;
-  mappings: string;
-}
-//#endregion
 //#region ../../node_modules/.pnpm/@babel+types@8.0.6/node_modules/@babel/types/lib/index.d.ts
 interface BaseComment {
   value: string;
@@ -1834,7 +1851,7 @@ export declare function stripPageDeclaration(source: string, filename: string):
  *
  * @internal
  */
-declare const WE_VU_RUNTIME_CAPABILITY_ORDER: readonly ["patchStrategy", "templateRefs", "inlineEvents", "setDataHighFrequencyWarning", "scopedSlots", "layout"];
+declare const WE_VU_RUNTIME_CAPABILITY_ORDER: readonly ["patchStrategy", "templateRefs", "inlineEvents", "setDataHighFrequencyWarning", "scopedSlots", "layout", "jsxIslands"];
 /**
  * wevu 编译器内部使用的运行时能力名称。
  *
@@ -2063,6 +2080,8 @@ interface TemplateCompileResult {
  * v-for 解析结果。
  */
 interface ForParseResult {
+  /** 无法拆分为完整别名与列表的非法循环表达式诊断。 */
+  error?: string;
   listExp?: string;
   rawListExp?: string;
   listExpAst?: Expression;
@@ -2106,6 +2125,10 @@ interface TemplateCompileOptions {
   objectLiteralBindMode?: ObjectLiteralBindMode;
   mustacheInterpolation?: MustacheInterpolationMode;
   formatWxml?: boolean;
+  /**
+   * 保留模板注释，供最终产物阶段统一处理；默认移除。
+   */
+  preserveComments?: boolean;
   runtimeBindingManifest?: WevuRuntimeBindingManifestMode;
   wxsExtension?: string;
   classStyleWxsSrc?: string;
@@ -2569,10 +2592,18 @@ type VueSfcBlockSignatures = Readonly<Record<VueSfcBlockType, string>>;
 type VueSfcBlockChanges = VueSfcBlockType[];
 interface VueSfcHmrSignatures {
   readonly blockSignatures?: VueSfcBlockSignatures;
+  /**
+   * 按 compiler provider 归属的内容签名，供宿主在不依赖具体 provider 名称的情况下维护 HMR 状态。
+   */
+  readonly contentSignatures?: Readonly<Record<string, string>>;
   readonly hasTemplate?: boolean;
   readonly nonJsonSignature?: string;
   readonly scriptSignature?: string;
   readonly styleIndependentSignature?: string;
+  /** 按 provider 归属的模板内容签名。 */
+  readonly templateContentSignatures?: Readonly<Record<string, string>>;
+  /** 按 provider 归属的脚本内容签名。 */
+  readonly scriptContentSignatures?: Readonly<Record<string, string>>;
   readonly tailwindContentSignature?: string;
   readonly tailwindScriptContentSignature?: string;
   readonly tailwindTemplateContentSignature?: string;