@compelem/compiler 0.30.0-beta.3 → 0.30.0-beta.5

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 holyhigh2
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 holyhigh2
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,3 @@
-# @compelem/compiler
-
+# @compelem/compiler
+
 [compelem](https://github.com/holyhigh2/compelem) 的**编译器**

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { a as ComponentAnalysis, c as ReactiveKind, i as CompilerOptions, n as compelemCompiler, o as DEBUG_DIV, r as CompiledStatic, s as ReactiveField, t as VitePluginOptions } from "./vite-BAl4p1jA.js";
+import { a as ComponentAnalysis, c as ReactiveKind, i as CompilerOptions, n as compelemCompiler, o as DEBUG_DIV, r as CompiledStatic, s as ReactiveField, t as VitePluginOptions } from "./vite-D178A0gy.js";
 
-//#region src/utils/oxc.d.ts
+//#region src/utils/ast.d.ts
 interface ParsedFile {
   program: any;
   /** 源码中所有 import 声明：本地名 → { source, imported } */
@@ -9,6 +9,8 @@ interface ParsedFile {
     imported: string;
   }>;
 }
+/** 解析 TS 源码为 AST（带缓存，LRU：命中回尾、超限逐出最老）。 */
+declare function parse(code: string, id?: string): ParsedFile;
 //#endregion
 //#region src/analyze/component.d.ts
 /** 判断某个 import source 是否指向 compelem 本体。 */
@@ -23,6 +25,11 @@ declare function collectCompelemImports(imports: ParsedFile['imports']): Map<str
  */
 declare function analyzeFile(code: string, id: string, parsed: ParsedFile): ComponentAnalysis[];
 //#endregion
+//#region src/analyze/inline-template-methods.d.ts
+
+/** 兼容旧 API：只返回改写后的源码。compile.ts 用 WithEdits 版本保留坐标映射。 */
+declare function inlineTemplateMethods(code: string, parsed: ParsedFile): string;
+//#endregion
 //#region src/analyze/template.d.ts
 
 interface TemplateIssue {
@@ -36,7 +43,6 @@ interface TemplateIssue {
 }
 //#endregion
 //#region src/analyze/render-body.d.ts
-
 /** 主视图依赖提取结果。 */
 interface RenderAnalysis {
   /** 主视图依赖路径（对应 ViewDepMap） */
@@ -97,8 +103,6 @@ interface StaticLiteralCodes {
   inlinedWatchAncestors?: boolean;
   /** cssVars effect 工厂（读 CSS 依赖信号 → 更新自定义属性） */
   cssEffect?: string;
-  /** 结构指令元数据占位字段，运行时从不读取（分派参数在 pointEffects 内） */
-  dirMeta?: string;
   buildTemplate?: string;
   /** 子视图表（结构指令的子模板元数据）：`subViews: { <subId>: { buildTemplate, fx } }` */
   subViews?: string;
@@ -120,11 +124,23 @@ interface CtorInsertPlan {
   pos: number;
   /** true = 类无构造体 → 合成 `constructor(...__a){ super(...__a); ... }` */
   synthesize: boolean;
+  /**
+   * 警告级诊断（W 通道）：super(…) 不在构造体顶层语句位时给出——
+   * 插入点只能退到构造体末尾，prop/state 初始值写入晚于分支内用户语句，
+   * 与原生字段初始化时机不严格等价。调用方转成 severity:'warn' 诊断。
+   */
+  warn?: string;
 }
 /** 文件级运行时函数 import 注入参数。 */
 interface ImportInjectOptions {
   /** 需要导入的运行时函数名（已定名，含可能的 __ce_ 别名） */
   helpers?: string[];
+  /**
+   * helper 的本地名 → 原始导出名。仅当本地名与导出名不同（冲突别名）时需要；
+   * 缺省按同名导入。例如 `{ __ce_signal: 'signal' }` →
+   * `import { signal as __ce_signal } from 'compelem'`。
+   */
+  helperAliases?: Record<string, string>;
   /** 定位到的 compelem import 声明：有命名 specifier 则原位扩展，否则新增独立行 */
   helperImport?: {
     decl: any;
@@ -134,6 +150,8 @@ interface ImportInjectOptions {
   helpersAnchor?: number;
   /** 需要从 **myfx** 注入的运行时函数名（方法装饰器前移的 debounce/throttle/once） */
   myfxHelpers?: string[];
+  /** myfx helper 的本地名 → 原始导出名（同 helperAliases） */
+  myfxAliases?: Record<string, string>;
   /** 定位到的 myfx import 声明：有命名 specifier 则原位扩展，否则新增独立行 */
   myfxImport?: {
     decl: any;
@@ -146,6 +164,12 @@ interface ImportInjectOptions {
   topLevel?: string;
   /** topLevel 的插入锚点（紧跟其后的偏移） */
   topLevelAnchor?: number;
+  /** inline 预变换的原始坐标编辑；在 class 注入前统一 overwrite。 */
+  inlineEdits?: Array<{
+    start: number;
+    end: number;
+    text: string;
+  }>;
 }
 /** 生成 `static __ce_static__ = {...}` 的源码文本。 */
 declare function buildStaticLiteral(opts: InjectOptions, codes?: StaticLiteralCodes): string;
@@ -209,15 +233,12 @@ interface CompileResult {
     viewDeps: number;
     /**
      * 约定错误（emit/@prop/@computed/@csscope 静态校验）。
-     *
-     * ⚠️ 这里**只有**约定错误。静态分析未通过的组件不会出现在 diagnostics 里 ——
-     * `assertStaticAnalysis` 直接抛 `StaticAnalysisError`，模板 codegen 失败同样抛。
-     * 不合规就报错，没有「凑合能跑」的产物，因此诊断里不需要任何结论字段。
      */
     conventionErrors: Array<{
       start: number;
       end: number;
       message: string;
+      severity?: 'warn';
     }>;
     /** 静态依赖清单（每组件无条件填充；options.verbose 时输出人类可读格式） */
     deps?: DepSummary;
@@ -247,20 +268,78 @@ interface VarMapEntry {
   }>;
 }
 /**
- * 默认的参与编译判定：`.ts` 且源码里出现 `extends CompElem` 或 `@tag`。
- *
- * 额外放行**家族装饰器**形态：mixin 文件（`export function mix(B) { class M extends B { @prop … } }`）
- * 既不含 `extends CompElem` 也不含 `@tag`（`@tag` 挂在具体组件上），但必须参与编译，
- * 否则其中的 `@prop/@state/@computed` 不会被剥离、注入的 `__ce_static__` 缺失，
- * 而运行时这几个装饰器是 no-op ⇒ 属性静默退化成普通实例字段。
- * 精确性由 `collectMixinClasses` 的「顶层函数体内 + 带 compelem 家族装饰器」把关，
- * 这里放宽只是让文件进入管线。
- *
- * ⚠️ 保持只收 `.ts`：IIFE 打包产物（`.js`）里指令名不在 scope，放宽会触发 D3 误报。
+ * 默认的参与编译判定：`.ts` 且源码里出现 `extends CompElem` 或 `@tag`
  */
 declare function defaultInclude(id: string, code: string): boolean;
-/** 编译单个文件。不会抛出：解析失败时原样返回。 */
+/** 编译单个文件。解析失败时原样返回；静态分析/模板 codegen 失败会抛 StaticAnalysisError。 */
 declare function compileFile(code: string, id: string, options?: CompilerOptions): CompileResult;
+/**
+ * 编译**已确定要编译**的源码，跳过 `include` 判定。
+ *
+ * 与 {@link compileFile} 的分工：
+ * - `compileFile` 面向「磁盘上可能是组件、也可能不是」的输入，先按扩展名 +
+ *   特征做 include 判定；
+ * - `compileSource` 面向「调用方已经决定要编译」的输入 —— 典型是 SFC 插件把
+ *   `.ce` 分段拼成的虚拟 TypeScript 模块。虚拟模块的 id 仍是 `.ce`（为了
+ *   sourcemap 指向真实文件），天然过不了 `defaultInclude` 的扩展名检查，
+ *   以前只能传 `include: () => true` 绕过整个判定（连 node_modules 排除也一起绕过）。
+ *
+ * `options.include` 在这里被忽略。
+ */
+declare function compileSource(code: string, id: string, options?: CompilerOptions): CompileResult;
+//#endregion
+//#region src/diagnostics.d.ts
+/** 约定违规的处理力度：error 阻断构建 / warn 控制台提示 / silent 忽略。 */
+type ConventionMode = 'error' | 'warn' | 'silent';
+/** 已格式化为 `文件:行:列 [类名] 消息` 的两组诊断文本。 */
+interface CollectedDiagnostics {
+  errs: string[];
+  warns: string[];
+}
+/** 惰性构建换行偏移索引（升序；仅在有诊断时付费一次）。 */
+declare function newlineIndex(code: string): Int32Array;
+/** 把源码偏移换算成 `行:列`（1 起算）；带换行索引时走二分（O(log n)）。 */
+declare function offsetToLineCol(code: string, offset: number, nl?: Int32Array): string;
+/** 相对 root 的展示路径（统一正斜杠，便于点击跳转）。 */
+declare function relativeToRoot(id: string, root: string): string;
+/**
+ * 从 diagnostics 收集**约定诊断**为可上报文本，按 severity 分为 errs（E-*）与 warns（W-*）。
+ *
+ * `root` 只用于把绝对路径压成相对路径，不影响判定。
+ */
+declare function collectDiagnostics(res: CompileResult, code: string, id: string, root: string): CollectedDiagnostics;
+/**
+ * 按 mode 上报违规：error 走插件上下文的 `this.error`（阻断构建），warn 走控制台。
+ *
+ * `thisArg` 是 Rollup/Vite 的插件上下文；纯 API 调用时传 undefined 也能工作
+ * （退化为 `throw`）。
+ */
+declare function reportDiagnostics(msgs: string[], mode: ConventionMode, head: string, thisArg: any): void;
+/**
+ * 一站式上报：W 码恒为控制台提示（不随档位阻断），E 码按 mode 处理。
+ *
+ * 返回是否发生了阻断（仅用于调用方决定是否继续）。
+ */
+declare function reportConventionDiagnostics(collected: CollectedDiagnostics, mode: ConventionMode, thisArg: any, tag?: string): void;
+//#endregion
+//#region src/tag-registry.d.ts
+/** `@tag('x-foo')` / `@tag(\`x-foo\`)`；一次扫描内复用，调用方负责重置 lastIndex。 */
+declare const TAG_RE: RegExp;
+/** 默认只把 `.ts` / `.tsx` 当作组件来源。 */
+declare const DEFAULT_TAG_EXT: RegExp;
+interface ScanKnownTagsOptions {
+  /** 参与扫描的文件扩展名正则，默认 {@link DEFAULT_TAG_EXT}。 */
+  extensions?: RegExp;
+  /** 目录递归深度上限，默认 20。 */
+  maxDepth?: number;
+}
+/**
+ * 递归收集 root 下匹配 `extensions` 的文件里的 `@tag` 名，写入 `out`。
+ *
+ * 读失败的文件直接跳过：注册表是 best-effort 的，它只会**放宽**校验，
+ * 不该让一次权限错误打断构建。`node_modules` 等目录不参与扫描。
+ */
+declare function scanKnownTags(root: string, out: Set<string>, options?: ScanKnownTagsOptions): void;
 //#endregion
-export { type CompileResult, type CompiledStatic, type CompilerOptions, type ComponentAnalysis, DEBUG_DIV, type DepSummary, type ReactiveField, type ReactiveKind, type RenderAnalysis, StaticAnalysisError, type VitePluginOptions, analyzeFile, analyzeRender, assertStaticAnalysis, buildStaticLiteral, collectCompelemImports, compelemCompiler, compileFile, defaultInclude, injectInto, isCompelemSource };
+export { type CollectedDiagnostics, type CompileResult, type CompiledStatic, type CompilerOptions, type ComponentAnalysis, type ConventionMode, DEBUG_DIV, DEFAULT_TAG_EXT, type DepSummary, type ReactiveField, type ReactiveKind, type RenderAnalysis, type ScanKnownTagsOptions, StaticAnalysisError, TAG_RE, type VitePluginOptions, analyzeFile, analyzeRender, assertStaticAnalysis, buildStaticLiteral, collectCompelemImports, collectDiagnostics, compelemCompiler, compileFile, compileSource, defaultInclude, injectInto, inlineTemplateMethods, isCompelemSource, newlineIndex, offsetToLineCol, parse, relativeToRoot, reportConventionDiagnostics, reportDiagnostics, scanKnownTags };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,3 +1,3 @@
-import { a as buildStaticLiteral, c as analyzeRender, d as analyzeFile, f as collectCompelemImports, i as defaultInclude, l as StaticAnalysisError, o as injectInto, p as isCompelemSource, r as compileFile, s as DEBUG_DIV, t as compelemCompiler, u as assertStaticAnalysis } from "./vite-DwMiG3VM.js";
+import { C as collectCompelemImports, S as analyzeFile, T as parse, _ as DEBUG_DIV, a as scanKnownTags, b as inlineTemplateMethods, c as offsetToLineCol, d as reportDiagnostics, f as compileFile, g as injectInto, h as buildStaticLiteral, i as TAG_RE, l as relativeToRoot, m as defaultInclude, o as collectDiagnostics, p as compileSource, r as DEFAULT_TAG_EXT, s as newlineIndex, t as compelemCompiler, u as reportConventionDiagnostics, v as StaticAnalysisError, w as isCompelemSource, x as analyzeRender, y as assertStaticAnalysis } from "./vite-CLK9td6W.js";
 
-export { DEBUG_DIV, StaticAnalysisError, analyzeFile, analyzeRender, assertStaticAnalysis, buildStaticLiteral, collectCompelemImports, compelemCompiler, compileFile, defaultInclude, injectInto, isCompelemSource };
+export { DEBUG_DIV, DEFAULT_TAG_EXT, StaticAnalysisError, TAG_RE, analyzeFile, analyzeRender, assertStaticAnalysis, buildStaticLiteral, collectCompelemImports, collectDiagnostics, compelemCompiler, compileFile, compileSource, defaultInclude, injectInto, inlineTemplateMethods, isCompelemSource, newlineIndex, offsetToLineCol, parse, relativeToRoot, reportConventionDiagnostics, reportDiagnostics, scanKnownTags };