@proteus-vue/component-ir 0.1.0

package/README.md

@@ -0,0 +1,62 @@
+# @proteus-vue/component-ir
+
+> **G-31 组件与 API 语义化**（`docs/proteus-component-semantics-plan/`）· B1-B5
+
+## 一句话
+
+**内置组件与 API 不由任何既有平台组件集"翻译"而来，而是由 Proteus 自己的语义 IR（C-IR）直接定义**——组件表达"意图"（semantic），属性表达"约束"，Backend 消费 semantic 而非 tag 字符串。
+
+## 内容
+
+| 模块 | 说明 |
+|------|------|
+| `schema.ts` | `ComponentIR` 类型 + `COMPONENT_IR_SCHEMA`（JSON Schema，对齐 plan component-ir.schema.json）+ `SEMANTIC_ENUM`（★G-32 扩展至 53 个语义：layout 15 / ui 21 / shell 9 / gesture 2 / engineering 3 / capability 3） + `TAG_SEMANTIC_MAP`（p-grid → layout.grid；★G-32 组件原语全量登记） |
+| `validate.ts` | `validateComponentIR`（CIR_INVALID_TAG：p- 前缀铁律 G-31.1 / CIR_INVALID_SEMANTIC / **CMP006**：capabilities 缺 degradation 声明 G-31.2）+ `validateGridConstraints`（**GRID_CONFLICT**）+ `validateComponentTree`（递归） |
+| `map.ts` | `SEMANTIC_BACKEND_MAP` + `mapSemanticToBackend`（semantic → 各端控件：layout.grid → UICollectionView / GridView / div.proteus-grid——**验证「Backend 用 semantic 映射而非 tag」**；★B5 与各后端实际产出对齐，是 conformance 门禁标准；★G-32 补至 26 implemented 语义） |
+| `primitives.ts` | ★G-32 完整语义原语清单 SSOT：`PRIMITIVE_CATALOG`（128 原语——6 大类 12+18+10+10+50+28）+ 选取器（componentPrimitives/implementedPrimitives）+ 自检（checkPrimitiveCatalog：128/唯一性） |
+| `conformance.ts` | `checkComponentSnapshot`（渲染快照 vs 参考表）+ `extractSemanticTree`（跨端结构同构）+ `checkSemanticCoverage`（★G-32：catalog-aware——仅 implemented 语义 ≥3 端门禁） |
+| `audit.ts` | ★G-32 B1 audit:coverage：`auditMiniprogramCoverage`（G-32.1 小程序能力 100%——对照矩阵 0 缺失 CI 红）+ `auditCatalogConsistency`（闭环 C1-C5：catalog↔enum↔tag↔render-map 四向不漂移）+ `formatCoverageReport` |
+| `to-ir.ts` | `toComponentIR` / `toComponentTree`（模板标签 → C-IR——G-29 生产端前置纯函数） |
+
+## 用法
+
+```ts
+import { validateComponentTree, mapSemanticToBackend, TAG_SEMANTIC_MAP } from '@proteus-vue/component-ir'
+
+const ir = { tag: 'p-grid', semantic: 'layout.grid', props: { minColWidth: 200, maxCols: 4 }, children: [] }
+const diags = validateComponentTree(ir, 375)
+// → GRID_CONFLICT：200 × 4 = 800 > 375——max-cols 永不达
+
+mapSemanticToBackend('layout.grid', 'native-ios') // 'UICollectionView'
+mapSemanticToBackend('layout.grid', 'flutter')    // 'GridView'
+mapSemanticToBackend('layout.grid', 'vue-dom')    // 'div.proteus-grid'
+```
+
+## Conformance（B5）
+
+```ts
+import { renderComponentSnapshot, createControlReader } from '@proteus-vue/render-backend'
+import { checkComponentSnapshot, checkSemanticCoverage } from '@proteus-vue/component-ir'
+
+const snap = renderComponentSnapshot(backend, ir, createControlReader(backend.id))
+const result = checkComponentSnapshot(backend.id, snap) // 控件 readback == 参考表？
+checkSemanticCoverage(3) // G-31.4：每语义 ≥3 端映射
+```
+
+## 严格规则
+
+- **G-31.1**：内置组件必须 `p-` 前缀 + 语义命名；禁止与小程序/HTML 组件同名（`<view>` 属兼容层）
+- **G-31.2**：每个组件属性须声明 Tier 降级行为（CMP006 编译期拦截）
+- **G-31.3**：Layer 0 API 全部 Promise/Hook 化，禁止回调式/全局对象式（无 `wx.xxx`）
+- **G-31.4**：组件进 L1 前须 ≥3 端真实 Backend 通过 conformance
+
+## 分层
+
+```
+Layer 0：Proteus 原生语义组件（p-* + useNative/useFetch）——本包
+Layer 1：@proteus/compat-miniprogram（旧小程序兼容层，独立包）
+```
+
+## 路线
+
+B1 C-IR + 校验器 ✅ → B2 布局原语 6 个 + VueDom ✅ → B3 Native 映射 ✅ → B4 UI 原语 + Fluid 扩展 ✅ → B5 conformance 三端快照 ✅ → **G-32 B1 完整语义闭环（128 原语 SSOT + audit:coverage 100% + 26 implemented 语义）✅** → B6 compat-miniprogram → B7 API Hook 化

package/dist/audit.d.ts

@@ -0,0 +1,45 @@
+/** 覆盖标记：✅ L1 原语 / 🔄 L2 或 compat / ⬛ 平台私有（C47 useMiniProgram）/ ❌ 缺失（CI 拦截） */
+export type MpCoverageStatus = 'ok' | 'compat' | 'private' | 'missing';
+export interface MpMatrixItem {
+    /** 小程序组件名或 API 名 */
+    mp: string;
+    /** Proteus 原语（语义/API/组件名） */
+    proteus: string;
+    status: MpCoverageStatus;
+    /** 对照类别（component / api-*) */
+    group: 'component' | 'api';
+}
+/** 全量对照矩阵 */
+export declare const MP_MAPPING_MATRIX: MpMatrixItem[];
+export interface CoverageReport {
+    total: number;
+    ok: number;
+    compat: number;
+    private: number;
+    missing: number;
+    /** 覆盖百分比（非 missing 占比） */
+    percent: number;
+    /** G-32.1：missing > 0 → 不达标（CI 红） */
+    pass: boolean;
+    missingItems: MpMatrixItem[];
+}
+/**
+ * ★G-32.1 audit:coverage：小程序官方能力 100% 覆盖校验
+ * 缺失（❌）= 无 Proteus 原语且非平台私有 —— 出现即 CI 红
+ */
+export declare function auditMiniprogramCoverage(matrix?: MpMatrixItem[]): CoverageReport;
+export interface ConsistencyIssue {
+    rule: string;
+    detail: string;
+}
+/**
+ * ★闭环 IR 一致性门禁：清单 ↔ 枚举 ↔ 标签映射 ↔ 渲染映射 四方不漂移
+ * - C1 catalog(tag) 条目：TAG_SEMANTIC_MAP[tag] === semantic（逐条对齐）
+ * - C2 catalog 组件语义 ⊆ SEMANTIC_ENUM（清单不越界）
+ * - C3 TAG_SEMANTIC_MAP 值 ⊆ SEMANTIC_ENUM（标签映射不产出非法语义）
+ * - C4 implemented 语义 ∈ SEMANTIC_BACKEND_MAP（已实现必有渲染映射）
+ * - C5 SEMANTIC_ENUM 全量 ∈ SEMANTIC_BACKEND_MAP ∪ planned（枚举中未实现的语义必须是 catalog planned 或已在 map）
+ */
+export declare function auditCatalogConsistency(): ConsistencyIssue[];
+/** 输出覆盖率报告（CLI 展示用） */
+export declare function formatCoverageReport(report: CoverageReport): string;

package/dist/conformance.d.ts

@@ -0,0 +1,40 @@
+import type { RenderNodeSnapshot } from '@proteus-vue/render-backend';
+/** 控件映射偏差：error=与参考表不符（门禁阻断）；unverified=参考表未声明该后端/语义，或 Layer 1 兼容层标签（不强制） */
+export interface ControlMismatch {
+    path: string;
+    semantic: string;
+    expected: string | null;
+    actual: string;
+    reason: 'mismatch' | 'no-row' | 'no-column' | 'compat';
+}
+export interface ComponentConformanceResult {
+    ok: boolean;
+    backendId: string;
+    /** 校验节点数 */
+    nodes: number;
+    /** 门禁错误：语义节点的控件映射与参考表不一致 */
+    errors: ControlMismatch[];
+    /** 不强制项：参考表缺行/缺列、Layer 1 兼容层标签 */
+    unverified: ControlMismatch[];
+}
+/** 语义树（跨端结构比对载体：同一 C-IR → 各端 semantic 路径必须同构） */
+export interface SemanticTree {
+    semantic: string;
+    children: SemanticTree[];
+}
+/** 提取语义树（忽略控件/属性——只比结构形状） */
+export declare function extractSemanticTree(snap: RenderNodeSnapshot): SemanticTree;
+/**
+ * 渲染快照 vs 规范参考表（SEMANTIC_BACKEND_MAP）
+ * - Layer 0 语义节点（semantic ≠ type）：参考表命中 → 控件必须一致（error）；参考表缺该语义/后端列 → unverified（不臆造门禁）
+ * - Layer 1 兼容层节点（无 semantic，semantic === type）：各后端自定义 compat 映射 → 不设门禁（unverified）
+ */
+export declare function checkComponentSnapshot(backendId: string, snapshot: RenderNodeSnapshot): ComponentConformanceResult;
+/** 参考表覆盖缺口（G-31.4：新组件进 L1 须 ≥3 端映射；不足 → 降级 L2，禁入 core）
+ *  ★G-32 B1：仅对 catalog 中 status='implemented' 的原语设门禁——planned（L2 生态/待落地）不阻断
+ */
+export interface CoverageGap {
+    semantic: string;
+    backends: string[];
+}
+export declare function checkSemanticCoverage(minBackends?: number): CoverageGap[];

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { COMPONENT_IR_SCHEMA, SEMANTIC_ENUM, TAG_SEMANTIC_MAP } from './schema';
+export type { ComponentIR } from './schema';
+export { validateComponentIR, validateGridConstraints, validateComponentTree, DEFAULT_DESIGN_WIDTH } from './validate';
+export type { CIRDiagnostic } from './validate';
+export { SEMANTIC_BACKEND_MAP, mapSemanticToBackend } from './map';
+export { toComponentIR, toComponentTree } from './to-ir';
+export { checkComponentSnapshot, extractSemanticTree, checkSemanticCoverage } from './conformance';
+export type { ComponentConformanceResult, ControlMismatch, SemanticTree, CoverageGap } from './conformance';
+export { PRIMITIVE_CATALOG, componentPrimitives, implementedPrimitives, primitiveById, primitiveBySemantic, primitiveByTag, checkPrimitiveCatalog } from './primitives';
+export type { PrimitiveDef, PrimitiveKind, PrimitiveStatus } from './primitives';
+export { MP_MAPPING_MATRIX, auditMiniprogramCoverage, auditCatalogConsistency, formatCoverageReport } from './audit';
+export type { CoverageReport, MpCoverageStatus, MpMatrixItem, ConsistencyIssue } from './audit';