@proteus-vue/compiler 0.3.0-beta.0

package/README.md

@@ -0,0 +1,74 @@
+# @proteus-vue/compiler —— 编译引擎独立包
+
+> Proteus 的**编译引擎**，v0.2 起独立为 monorepo 包（`packages/compiler/`）。
+> 设计目标：**零 Vite 依赖、零项目配置依赖、纯函数、选项全入参**——可独立分发、独立测试、被任何构建器消费。
+
+## 模块边界（必须遵守）
+
+| 允许 | 禁止 |
+|---|---|
+| import `@vue/compiler-sfc` / `@vue/compiler-dom`（编译期 AST 处理） | import `vite` 或任何 Vite 相关 API |
+| import 同包 `./src` 内部模块 | import `proteus.config.ts` 或读取项目配置 |
+| 选项全部通过函数入参传入 | 读写文件系统 / 网络（纯函数） |
+
+- 所有转换函数是**纯函数**：相同输入 → 相同输出，可独立单测
+- 编译期警告通过返回值 `warnings` 透出（不直接抛错，除非不可恢复）
+
+## 公开 API
+
+```typescript
+// 整包编译（推荐入口）
+compileVueSfc(source: string, options: CompileOptions): CompileResult
+// CompileResult = { wxml, js, wxss, warnings, trace }
+
+// 分步转换（精细控制 / 单测）
+transformTemplateToWxml(templateSource, styleOpts): { wxml, vModelBindings, warnings }
+transformScriptToPage(scriptSource, styleOpts, { file, isComponent, vModelBindings }): { js, warnings }
+transformStyleToWxss(styleSource, styleOpts): string
+
+// ★ AI-native 透明：编译规则注册表（69 条规则，每条一份 AI 说明书）
+listTransformRules(phase?)    // 枚举规则（能力清单）
+getTransformRule(id)          // 查单条规则
+formatTransformRule(rule)     // 渲染单条 AI 说明书
+formatTransformCatalog()      // 渲染全量目录
+
+// ★ 阶段三分派层（底线循环 ① 完全形态）：AI 覆盖规则 apply 即获得新能力
+// （implemented 规则可携带 apply()；style/px-to-rpx、template/scope-attr 已登记示范）
+executeRule(id, ctx)          // 按规则 ID 执行（RuleContext：input → output）
+
+// ★ 决策 trace（底线循环 ②）：源码 → 实际触发的全部规则
+explainTransform(source, options?)  // → { events: [{ ruleId, phase, line, before, after }] }
+formatTransformTrace(result)        // 渲染为按阶段分组的可读文本
+
+// 规则覆盖（底线循环 ①③）：AI / config 改写或禁用规则
+// （TransformRuleOverrides：disabled / mapping / customTags，经 CompileOptions.rules 传入）
+```
+
+## 产物契约
+
+- `.wxml`：标准标签 → 小程序标签（`div→view` / `span,p,h1-h6→text` / `img→image` …）+ 指令映射
+- `.js`：`Page({ data, methods, onReady, onUnload, onLoad, proteusOnXInput, proteusNavigateTo })`（组件为 `Component()`）
+- `.wxss`：px → rpx、Skyline 不支持属性编译期警告、语义基础样式注入
+- `.json`：**不属于本引擎**，由 `scripts/gen-routes.ts`（框架路由生成器）负责
+
+## 消费方
+
+- `vite-plugin-mp-transform.ts`（monorepo 根，`@proteus-vue/plugin-vite` 前身）：薄适配层——扫描页面、传选项（含 `rules` 覆盖）、`emitFile` 产物
+- `tests/*.test.ts`：直接 import `../packages/compiler/src` 调纯函数（vitest，无 Vite 依赖）
+- 未来 CLI `@proteus-vue/cli`：`proteus build` / `proteus explain` 核心即调 `compileVueSfc` + `explainTransform`
+
+## 构建与发布
+
+```bash
+cd packages/compiler
+npm run build        # tsc -p tsconfig.build.json → dist/（ESM + .d.ts）
+npm publish          # 发布 @proteus-vue/compiler（main/types/exports 指向 dist）
+```
+
+发布后适配层可改为 `import { compileVueSfc } from '@proteus-vue/compiler'`（npm workspace 链接或直接依赖），
+`proteus.config.ts` 的 `style` / `rules` 选项由适配层读取后传入——编译引擎 API 不变。
+
+## MVP 限制（逐步补充边缘情况）
+
+computed 读路径（v0.3 已支持：`computed(() => 表达式)` → data 派生 + setData 合并重算）/ watch / 跨模块引用、复杂事件表达式、`:class` 数组语法、
+方法体对 setup ref 的复合赋值、`<template v-slot>` —— 均编译期警告或忽略。

package/dist/explain.d.ts

@@ -0,0 +1,25 @@
+import type { TransformTraceEvent } from './trace';
+import type { TransformRuleOverrides } from './types';
+export interface ExplainOptions {
+    /** 源文件名（写入 trace 注释） */
+    filename?: string;
+    /** 组件模式（Component() vs Page()） */
+    isComponent?: boolean;
+    /** 是否 px → rpx（默认 true） */
+    px2rpx?: boolean;
+    /** px→rpx 比例（默认 2） */
+    rpxRatio?: number;
+    /** 是否启用行号注释（默认 false） */
+    annotateLines?: boolean;
+    /** 规则覆盖（可选：★底线循环 ①③，与 proteus.config.ts rules 同构） */
+    rules?: TransformRuleOverrides;
+}
+export interface ExplainResult {
+    filename?: string;
+    /** 全部决策事件（template → script → style 按阶段顺序） */
+    events: TransformTraceEvent[];
+}
+/** 对一份 Vue SFC 源码执行全链路转换并收集决策 trace */
+export declare function explainTransform(source: string, options?: ExplainOptions): ExplainResult;
+/** 渲染决策 trace 为人类可读文本（按阶段分组 + 行号） */
+export declare function formatTransformTrace(result: ExplainResult): string;

package/dist/explain.js

@@ -0,0 +1,59 @@
+// src/compiler/explain.ts
+// explainTransform —— 阶段二核心：对一份 Vue SFC 输出它实际触发的全部转换规则（决策 trace）
+// AI 用法：改完编译器 / 写完页面后，跑 explainTransform 看转换链路，理解"为什么产物是这样"。
+import { parse as sfcParse } from '@vue/compiler-sfc';
+import { transformTemplateToWxml } from './template';
+import { transformScriptToPage } from './script';
+import { transformStyleToWxss } from './style';
+import { createTrace } from './trace';
+/** 对一份 Vue SFC 源码执行全链路转换并收集决策 trace */
+export function explainTransform(source, options = {}) {
+    const { descriptor } = sfcParse(source, { filename: options.filename ?? 'anonymous.vue' });
+    const styleOpts = { px2rpx: options.px2rpx ?? true, rpxRatio: options.rpxRatio ?? 2 };
+    const events = [];
+    // template 阶段（vModelBindings / usesNavigate 传给 script 阶段）
+    const tplTrace = createTrace('template');
+    const tpl = descriptor.template?.content ?? '';
+    const tplResult = transformTemplateToWxml(tpl, {
+        ...styleOpts,
+        filename: options.filename,
+        annotateLines: options.annotateLines,
+        rules: options.rules,
+        trace: tplTrace,
+    });
+    events.push(...tplTrace.events);
+    // script 阶段
+    const setup = descriptor.scriptSetup?.content ?? descriptor.script?.content ?? '';
+    const scriptTrace = createTrace('script');
+    transformScriptToPage(setup, styleOpts, {
+        file: options.filename,
+        isComponent: options.isComponent,
+        vModelBindings: tplResult.vModelBindings,
+        usesNavigate: tplResult.usesNavigate,
+        rules: options.rules,
+        trace: scriptTrace,
+    });
+    events.push(...scriptTrace.events);
+    // style 阶段
+    const styleTrace = createTrace('style');
+    transformStyleToWxss(descriptor.styles.map((s) => s.content).join('\n'), { ...styleOpts, rules: options.rules, trace: styleTrace });
+    events.push(...styleTrace.events);
+    return { filename: options.filename, events };
+}
+/** 渲染决策 trace 为人类可读文本（按阶段分组 + 行号） */
+export function formatTransformTrace(result) {
+    const phases = ['template', 'script', 'style', 'validate'];
+    const blocks = [];
+    for (const phase of phases) {
+        const evts = result.events.filter((e) => e.phase === phase);
+        if (!evts.length)
+            continue;
+        const lines = evts.map((e) => {
+            const line = e.line != null ? `L${e.line} ` : '';
+            const detail = [e.before, e.after].filter(Boolean).join(' → ');
+            return `  ${line}${e.ruleId}${detail ? `：${detail}` : ''}`;
+        });
+        blocks.push(`### ${phase} 阶段（${evts.length} 个决策）\n${lines.join('\n')}`);
+    }
+    return `# explainTransform ${result.filename ?? ''}\n\n${blocks.join('\n\n')}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import type { CompileOptions, CompileResult } from './types';
+/** djb2 哈希 → scoped 属性名（稳定：同文件同 scopeId；零依赖纯函数） */
+export declare function scopedIdFrom(filename: string): string;
+export type { CompileOptions, CompileResult, StyleTransformOptions, TemplateTransformOptions, TemplateTransformResult, ScriptTransformOptions, ScriptTransformResult, } from './types';
+export { transformTemplateToWxml } from './template';
+export { transformScriptToPage } from './script';
+export { transformStyleToWxss } from './style';
+export { validateJs, validateWxml, CompilerError } from './validate';
+export { listTransformRules, getTransformRule, formatTransformRule, formatTransformCatalog } from './transforms/registry';
+export type { TransformRule, TransformPhase, RuleStatus } from './transforms/types';
+export type { TransformRuleOverrides } from './types';
+export { explainTransform, formatTransformTrace } from './explain';
+export type { ExplainOptions, ExplainResult } from './explain';
+export { createTrace, lineAt } from './trace';
+export type { TransformTrace, TransformTraceEvent } from './trace';
+/** 整包编译：标准 Vue SFC 源码 → { wxml, js, wxss }（.json 由路由生成器负责） */
+export declare function compileVueSfc(source: string, options?: CompileOptions): CompileResult;