@proteus-vue/compiler-backend 0.1.0

package/README.md

@@ -0,0 +1,45 @@
+# @proteus-vue/compiler-backend
+
+> **G-29 编译器可插拔后端**（`docs/proteus-compiler-backend-1-plan/`）· B1
+
+## 一句话
+
+**编译器从"固定 Node 工具链"升级为"可插拔后端"**——Node / Rust(SWC-ecosystem) / WASM 三端后端对同一份 SFC 产出语义等价的 `CompilerIR`，业务零感知一个 flag 切换。与 G-27 `ProteusRenderBackend`、G-28 `ProteusNativeBackend` 同构（语义契约 + 后端实现 + conformance）。
+
+## 内容
+
+| 模块 | 说明 |
+|------|------|
+| `spi.ts` | `ProteusCompilerBackend` 接口 + `CompilerIR` 契约（version/render/semantic/bindings）+ `CompilerCapabilities`（对齐 plan 02-compiler-backend-spi.md） |
+| `conformance.ts` | `runCompilerConformance(backend)` 自检——CMP004 版本协商 + CMP002 IR 合规（render/semantic 计数交叉核对）+ ★G-31.1 语义链接（p-* 标签 → TAG_SEMANTIC_MAP） |
+| `node.ts` | **NodeBackend** 参考实现：真实模板编译（@vue/compiler-sfc + @vue/compiler-dom）→ CompilerIR，**semantic = toComponentIR 产物**——「源码 → C-IR」生产端雏形 |
+
+## 用法
+
+```ts
+import { createNodeCompilerBackend, runCompilerConformance } from '@proteus-vue/compiler-backend'
+
+const backend = createNodeCompilerBackend()
+const result = runCompilerConformance(backend) // { ok: true, checks: [...] } —— CMP002/CMP004
+
+const ir = backend.compile({ filename: 'grid.vue', source: `<template><p-grid :min-col-width="160" :max-cols="4"><p-box /></p-grid></template>` })
+ir.semantic.tree    // { tag: 'p-grid', semantic: 'layout.grid', props: { minColWidth: { expr: '160' }, maxCols: { expr: '4' } }, children: [...] }
+ir.render.root      // 渲染树（含 semantic 字段——G-27 nodeOps 消费）
+ir.bindings         // capability 入口 + v-model + 事件（G-28 消费）
+```
+
+## 与 G-31 衔接
+
+`CompilerIR.semantic` = C-IR 树（`toComponentIR` 产物）——**真实模板编译接语义层**：
+Renderer 树兼含语义组件（Layer 0）与兼容层标签（Layer 1）；语义计数交叉核对（render semantic 节点数 == semanticCount == C-IR 树节点数）保证两棵树同源不漂移。
+
+## 严格规则
+
+- **G-29.1**：三端 Backend 对同一份 SFC 必须产出语义等价的 CompilerIR（IR Golden Test 强制）
+- **G-29.2**：新 Compiler Backend 必须通过 conformance test
+- **G-29.3**：HMR 语义三端一致
+- **CMP001-004**：依赖私有 API / IR 不合规 / HMR 不一致 / 版本不兼容
+
+## 路线
+
+B1 CompilerIR 契约 + NodeBackend ✅ → B2 RustBackend（SWC-ecosystem）→ B3 WASM Backend（Playground）→ B4 HMR 三端一致 + Source Map + Tree-shaking

package/dist/conformance.d.ts

@@ -0,0 +1,19 @@
+import type { ProteusCompilerBackend } from './spi';
+export interface ConformanceCheck {
+    name: string;
+    pass: boolean;
+    detail?: string;
+}
+export interface ConformanceResult {
+    ok: boolean;
+    checks: ConformanceCheck[];
+}
+/** 默认 conformance fixture（一份含布局原语 + 兼容层 + 能力入口 + 事件/模型的真实 SFC） */
+export declare const DEFAULT_CONFORMANCE_SFC = "<template>\n  <p-stack :gap=\"12\">\n    <p-grid :min-col-width=\"160\" :max-cols=\"4\">\n      <p-box />\n      <view class=\"compat\"></view>\n    </p-grid>\n    <p-text>{{ title }}</p-text>\n    <p-button @click=\"onSave\">\u4FDD\u5B58</p-button>\n    <p-input v-model=\"keyword\" />\n    <p-scan-qr />\n  </p-stack>\n</template>";
+/**
+ * CompilerBackend 接口完整性 + IR 产出合规自检
+ * - CMP004：minCompatVersion ≠ 1 / IR version ≠ 1 → fail
+ * - CMP002：render 树 shape（type/children）+ semantic 计数与渲染树交叉核对 + bindings shape
+ * - G-31.1：渲染树中 p-* 元素 semantic 必须 == TAG_SEMANTIC_MAP[type]（语义链接机器验证）
+ */
+export declare function runCompilerConformance(backend: ProteusCompilerBackend, fixture?: string): ConformanceResult;

package/dist/dual-check.d.ts

@@ -0,0 +1,20 @@
+export type CompilerBackendChoice = 'node' | 'rust';
+/**
+ * ★双编译语义等价校验：同一 SFC → Node/Rust 双后端 → diff
+ *   @param rustBin  Rust CLI 可执行（bin/cli.js 路径；null → skipped）
+ *   @param runRust  注入式 runner（默认 execFileSync node bin compile —— 测试注入 mock 驱动 mismatch/skipped）
+ */
+export declare function verifyDualCompilerEquivalence(source: string, opts: {
+    rustBin: string | null;
+    filename?: string;
+    runRust?: (bin: string, sfc: string) => string;
+}): {
+    status: 'ok' | 'mismatch' | 'skipped';
+    details: string[];
+    reason?: string;
+};
+/**
+ * ★定位 Rust CLI 可执行（bin/cli.js——npm bin 壳：release 优先/缺失自动 cargo build）：
+ *   ① env PROTEUS_CC_RUST 显式路径 → ② 工程/本包解析 @proteus-vue/compiler-backend-rust 包 → null（调用方降级）
+ */
+export declare function resolveRustCliBin(projectRoot: string): string | null;

package/dist/g38-conformance.d.ts

@@ -0,0 +1,20 @@
+import type { G38CompilerBackend } from './g38';
+export interface G38ConformanceResult {
+    id: string;
+    status: 'PASS' | 'FAIL' | 'SKIP';
+    error?: string;
+}
+export interface G38ConformanceSummary {
+    total: number;
+    pass: number;
+    fail: number;
+    skip: number;
+    results: G38ConformanceResult[];
+}
+export declare function createG38TerminalBackend(): G38CompilerBackend;
+/** 跑全部 42 项（单后端；C-02 生命周期组依赖顺序执行——与 runner 同构） */
+export declare function runG38Conformance(backend: G38CompilerBackend, opts?: {
+    only?: string;
+}): Promise<G38ConformanceSummary>;
+/** 文本报告（CLI 打印） */
+export declare function formatG38Conformance(name: string, s: G38ConformanceSummary): string;

package/dist/g38-fallback.d.ts

@@ -0,0 +1,29 @@
+import type { G38CompilerBackend } from './g38';
+export interface G38FallbackLog {
+    from: string;
+    to: string;
+    reason: string;
+}
+export interface G38FallbackOptions {
+    /** 首选后端 id（'node' | 'rust' | 'go' | 'wasm' | 'bytecode'） */
+    preferred: string;
+    /** 降级目标（规范 §6 固定 node——Node 参考实现恒可用） */
+    fallback?: 'node';
+    /** 加载器（注入可单测）：返回后端实例；null/抛错 → 降级 */
+    load?: (id: string) => Promise<G38CompilerBackend | null>;
+    /** 降级事件监听（日志/指标——C-07-02 可观测） */
+    onFallback?: (log: G38FallbackLog) => void;
+}
+export interface G38FallbackResult {
+    /** 实际选用的后端（preferred 可用 → 它；否则 node 参考实现） */
+    backend: G38CompilerBackend;
+    /** 降级记录（未降级 → null） */
+    fallback: G38FallbackLog | null;
+    isDegraded: boolean;
+}
+/**
+ * ★createG38FallbackBackend：selectCompilerBackend（01 §6 / 03-implementation-guide）
+ *   用法：const { backend } = await createG38FallbackBackend({ preferred: 'rust' })
+ *   → rust 不可用 → backend = node 参考实现 + fallback 日志（from:rust to:node）
+ */
+export declare function createG38FallbackBackend(opts: G38FallbackOptions): Promise<G38FallbackResult>;

package/dist/g38-session.d.ts

@@ -0,0 +1,11 @@
+import type { G38CompilerBackend, G38IncrementalSession } from './g38';
+export interface G38SessionOptions {
+    /** 会话 id（缺省 'incr'） */
+    id?: string;
+    /** 内容提供者（recompute 重算脏文件时取内容；缺省 → 用 track 注入的内容） */
+    getContent?: (file: string) => string | null;
+}
+/** ★createG38IncrementalSession：真增量会话（依赖图 + 签名缓存 + 局部重算 + commit/rollback 快照） */
+export declare function createG38IncrementalSession(backend: G38CompilerBackend, cacheDir: string, opts?: G38SessionOptions): G38IncrementalSession;
+/** 便捷：解析 SFC script 块 import 依赖（相对/包裸名——module-plan B0 同款正则；模板无 import → []） */
+export declare function scanSfcImports(source: string): string[];

package/dist/g38.d.ts

@@ -0,0 +1,115 @@
+import type { ComponentIR } from '@proteus-vue/component-ir';
+import type { G38SessionOptions } from './g38-session';
+export interface G38CompilerCapabilities {
+    incremental: boolean;
+    aot: boolean;
+    sourceMap: boolean;
+    minify: boolean;
+    treeShake: boolean;
+    targetPlatforms: ('web' | 'ios' | 'android' | 'harmony' | 'flutter')[];
+    supportedLanguages: ('sfc' | 'tsx' | 'jsx' | 'vue')[];
+    backend: 'native' | 'wasm' | 'js';
+    deterministic: boolean;
+}
+export interface G38SourceFile {
+    path?: string;
+    content: string;
+}
+export interface G38SourceLoc {
+    line: number;
+    column: number;
+}
+export interface G38Diagnostic {
+    code: string;
+    message: string;
+    loc: G38SourceLoc;
+    severity?: 'error' | 'warning';
+}
+export interface G38ElementNode {
+    kind: 'element';
+    tag: string;
+    attributes: Record<string, unknown>;
+    children: G38ElementNode[];
+    loc: G38SourceLoc;
+}
+export interface G38ProgramIR {
+    nodes: G38ElementNode[];
+    diagnostics: G38Diagnostic[];
+}
+export interface G38ImportNode {
+    source: string;
+    imported: string;
+}
+export interface G38CapabilityNode {
+    name: string;
+    semantic: string;
+}
+export interface G38ModuleMetadata {
+    semanticCount: number;
+    compatCount: number;
+    componentCount: number;
+}
+export interface G38IRModule {
+    readonly id: string;
+    readonly imports: G38ImportNode[];
+    /** ★语义组件树（ComponentIR——G-31 C-IR 同构，直接交 G-37 RenderBackend 消费） */
+    readonly components: ComponentIR[];
+    readonly capabilities: G38CapabilityNode[];
+    readonly metadata: G38ModuleMetadata;
+}
+export interface G38CompiledArtifact {
+    code: string;
+    map: unknown;
+    hash: string;
+}
+export interface G38IRModuleDiff {
+    changed: string[];
+    removed: string[];
+    added: string[];
+    affectedFiles: string[];
+}
+export interface G38IncrementalSession {
+    readonly id: string;
+    invalidate(file: string): void;
+    invalidateAll(): void;
+    recompute(): G38IRModuleDiff;
+    getDependencies(file: string): string[];
+    getDependents(file: string): string[];
+    commit(): void;
+    rollback(): void;
+    getStats(): Record<string, unknown>;
+    dispose(): void;
+    /** ★宿主驱动扩展（04-incremental-compilation：首次全量构建逐文件注册——非规范必需方法） */
+    track?(file: string, content: string, deps?: string[]): void;
+}
+export interface G38CompilerContext {
+    cacheDir?: string;
+}
+export interface G38ParseContext {
+    filename?: string;
+}
+export interface G38TransformContext {
+    filename?: string;
+}
+export interface G38EmitContext {
+    format?: 'bundle' | 'ir-json' | 'list';
+}
+/** ★G-38 编译后端 SPI（01 §2.1 同形）——任何合规后端必须实现全部方法 */
+export interface G38CompilerBackend {
+    readonly id: string;
+    readonly version: string;
+    readonly capabilities: G38CompilerCapabilities;
+    initialize(ctx?: G38CompilerContext): Promise<void>;
+    dispose(): void;
+    parse(source: G38SourceFile, ctx?: G38ParseContext): G38ProgramIR;
+    transform(ast: G38ProgramIR, ctx?: G38TransformContext): G38IRModule;
+    emit(module: G38IRModule, ctx?: G38EmitContext): G38CompiledArtifact;
+    createIncrementalSession(cacheDir: string, opts?: G38SessionOptions): G38IncrementalSession;
+    reportDiagnostics(module: G38IRModule): G38Diagnostic[];
+    getCacheKey(input: G38SourceFile): string;
+    getArtifactHash(artifact: G38CompiledArtifact): string;
+}
+/** djb2 哈希（与 conformance-runner.js 同算法——产物 hash 可交叉比对） */
+export declare function g38Hash(s: string): string;
+/** ★createG38NodeBackend：Node 参考实现（G-38 01 §2.1 全部 16 方法） */
+export declare function createG38NodeBackend(): G38CompilerBackend;

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export type { ProteusCompilerBackend, CompilerCapabilities, CompilerIR, RenderIR, RenderNode, SemanticIR, LayoutConstraintIR, BindingIR, SFCSource, SourceLoc, TemplateAST, TemplateNode, TemplateNodeType, FileChange, UpdatePayload, SourceMap, } from './spi';
+export { runCompilerConformance, DEFAULT_CONFORMANCE_SFC } from './conformance';
+export type { ConformanceCheck, ConformanceResult } from './conformance';
+export { createNodeCompilerBackend } from './node';
+export { verifyDualCompilerEquivalence, resolveRustCliBin } from './dual-check';
+export type { CompilerBackendChoice } from './dual-check';
+export { createG38NodeBackend, g38Hash } from './g38';
+export type { G38CompilerBackend, G38CompilerCapabilities, G38SourceFile, G38SourceLoc, G38Diagnostic, G38ElementNode, G38ProgramIR, G38ImportNode, G38CapabilityNode, G38ModuleMetadata, G38IRModule, G38CompiledArtifact, G38IRModuleDiff, G38IncrementalSession, G38CompilerContext, G38ParseContext, G38TransformContext, G38EmitContext, } from './g38';
+export { createG38FallbackBackend } from './g38-fallback';
+export type { G38FallbackOptions, G38FallbackResult, G38FallbackLog } from './g38-fallback';
+export { createG38IncrementalSession, scanSfcImports } from './g38-session';
+export type { G38SessionOptions } from './g38-session';
+export { createG38TerminalBackend, runG38Conformance, formatG38Conformance } from './g38-conformance';
+export type { G38ConformanceResult, G38ConformanceSummary } from './g38-conformance';