基于 FigmaMCP 的 D2C 工具(六): verify（上）——静态义务和 ComponentUsageIR

// schemas/proof.ts（精简）
interface ProofObligation {
  id: string                     // 形如 binding:prop:title、boundary:fingerprint:catalog
  category: 'contract' | 'semantic' | 'behavior' | 'structure' | 'layout' | 'boundary'
  phase?: 'static' | 'runtime'   // 静态侧一律 static
  outcome: 'pass' | 'fail' | 'unknown'
  expected?: unknown             // fail 时带期望值
  actual?: unknown               // fail 时带实际值
  differences?: Array<{ path: string, expected: unknown, actual: unknown, message: string }>
  unresolved?: UnresolvedFact    // unknown 时必须带，说明为什么证不了
}

// schemas/evidence.ts（精简）
interface UnresolvedFact {
  kind: 'unresolved'
  reason: 'dynamic-expression'   // 值是表达式 / 引用，静态看不到最终值
    | 'dynamic-spread'           // v-bind="obj"，可能给了也可能没给
    | 'dynamic-style'            // :class / :style / css 里的 v-bind()
    | 'unresolved-symbol'        // class 没有样式来源、token 找不到
    | 'ambiguous-component-resolution' // 标签解析不到契约
    | 'stale-fingerprint'        // decision 里缺这枚指纹
    | 'runtime-required'         // 只能靠浏览器证
    | /* …decide 阶段用的几个省略 */ 'unknown'
  detail?: string
}

// schemas/component-usage.ts（精简）
interface ComponentUsageIR {
  schemaVersion: 2
  kind: 'component-usage'
  id: string                      // usage:<相对路径>
  source: { file: string, fingerprint: string }   // 指纹 = 源文件 + 参与的样式文件
  roots: ComponentUsageNode[]     // template 顶层节点
  styles: UsageStyleFact[]        // 编译后的 CSS，一条声明一条事实
  layout: LayoutConstraintGraph   // 从 styles 投影出的布局事实，和 DesignIntentIR.layout 同一个类型
  unresolved: UnresolvedFact[]    // 抽取器自己解不开的账
}

interface ComponentUsageNode {
  id: string                      // <文件>:<行>:<列>:<序号>
  nodeKind: 'component' | 'element' | 'template' | 'text'
  tag: string
  resolution:                     // 标签解析到哪个契约，verify 定位靶点只认这个字段
    | { kind: 'resolved', contractId: string, importPath?: string }
    | { kind: 'native', tag: string }
    | { kind: 'unresolved', fact: UnresolvedFact }
  props: Array<{ name: string, value: BindingValue, syntax: 'static' | 'bind' | 'shorthand' }>
  models: Array<{ name: string, argument?: string, value: BindingValue }>   // v-model
  events: Array<{ name: string, handler: BindingValue }>                   // @xxx
  slots: Array<{ name: BindingValue, dynamic: boolean }>                   // <template #xxx>
  spreads: Array<{ target: 'props' | 'attrs' | 'listeners', value: BindingValue }>  // v-bind="obj"
  directives: UsageDirective[]; branches: UsageBranch[]; loops: UsageLoop[]
  classes?: BindingValue[]; styles?: BindingValue[]; text?: BindingValue
  children: ComponentUsageNode[]
}

// schemas/binding.ts（精简）。BindingPlan 里的期望值也是这个类型，两边形状一致才能比
type BindingValue =
  | { kind: 'literal', value: string | number | boolean | null }
  | { kind: 'reference', name: string, path?: string[] }   // :size="size"、:v="a.b.c"
  | { kind: 'expression', source: string, possibleValues?: BindingValue[] }
  | { kind: 'object', entries: Array<{ key: string, value: BindingValue }> }
  | { kind: 'array', items: BindingValue[] }
  | UnresolvedFact

// src/usage/source-usage.ts（伪代码，按真实流程精简）
async function extractComponentUsage(file, { projectRoot, catalog }) {
  const parsed = parseSfc(readFileSync(file))     // @vue/compiler-sfc；解析报错直接抛，不产出半份 IR

  // 1. <script> 里的 import 收成 局部名 -> 模块路径（typescript 编译器 API）
  const imports = parseImports(script)
  // 2. catalog 契约建索引：id / name / aliases / source.file 归一化成 kebab-case 当 key
  //    Nuxt 自动注册的组件从 .nuxt/components.d.ts 补进索引
  const components = componentIndex(catalog); addNuxtComponents(components, projectRoot)

  // 3. template 用 @vue/compiler-dom 解析，递归生成节点
  //    - 组件标签先查索引，再拿 import 路径对契约的 importPath；都对不上 -> resolution unresolved
  //    - 属性归类：普通 attribute -> props(static)；:xxx -> props(bind)；v-bind="obj" -> spreads
  //      v-model -> models；@xxx -> events；<template #xxx> 由父组件收成 slots，槽名 isStatic 才是 literal
  //    - 表达式走 parseBindingExpression：字符串/数字/布尔 -> literal；标识符 -> reference；
  //      a.b.c -> reference + path；对象/数组字面量递归；三元 -> expression + possibleValues
  const roots = parseTemplate(template).children.flatMap(n => usageNode(n, undefined, ctx))

  // 4. 样式：<style> 块 compileStyleAsync 编译（scoped 带 data-v-xxx），postcss 逐条声明记一条事实
  //    nuxt.config.ts 的 css: [] 和 UnoCSS 生成结果同样逐条记
  //    模板里的静态 class 没被 UnoCSS 匹配、也没被任何 selector 覆盖 -> unresolved-symbol
  const styles = await extractStyles(...)

  // 5. styles 投影进 layout 图：selector 能匹配到节点才投
  //    display:flex -> axis:row；flex-direction:column -> axis:column；gap / padding / sizing / overflow 各有 relation
  addLayoutFromStyles(roots, styles, ctx.layout)

  return ComponentUsageIRSchema.parse({ ..., source: { file, fingerprint: fingerprintFiles([file, ...styleFiles]) } })
}

<!-- pages/confirm.vue -->
<script setup lang="ts">
import Dialog from '~/components/Dialog.vue'
const visible = ref(false)
const size = 'medium'
const footerSlot = 'footer'
function onConfirm() {}
</script>

<template>
  <div class="page">
    <Dialog v-model="visible" title="确认删除" :size="size" :closable="true" @confirm="onConfirm">
      <p class="tip">删除后不可恢复</p>
      <template #[footerSlot]>
        <Button type="primary">确定</Button>
      </template>
    </Dialog>
  </div>
</template>

<style scoped>
.page { display: flex; flex-direction: column; gap: 16px; padding: 24px; }
</style>

{
  "kind": "component-usage",
  "id": "usage:pages/confirm.vue",
  "source": { "file": "pages/confirm.vue", "fingerprint": "sha256:9f2c…" },
  "roots": [{
    "id": "pages/confirm.vue:11:3:1", "nodeKind": "element", "tag": "div",
    "resolution": { "kind": "native", "tag": "div" },
    "classes": [{ "kind": "literal", "value": "page" }],
    "children": [{
      "id": "pages/confirm.vue:12:5:2", "nodeKind": "component", "tag": "Dialog",
      "resolution": { "kind": "resolved", "contractId": "dialog", "importPath": "~/components/Dialog.vue" },
      "props": [
        { "name": "title",    "value": { "kind": "literal",   "value": "确认删除" }, "syntax": "static" },
        { "name": "size",     "value": { "kind": "reference", "name": "size" },     "syntax": "bind" },
        { "name": "closable", "value": { "kind": "literal",   "value": true },       "syntax": "bind" }
      ],
      "models": [{ "name": "modelValue", "value": { "kind": "reference", "name": "visible" } }],
      "events": [{ "name": "confirm", "handler": { "kind": "reference", "name": "onConfirm" } }],
      "slots":  [{ "name": { "kind": "expression", "source": "footerSlot" }, "dynamic": true }],
      "spreads": [],
      "children": [
        { "id": "pages/confirm.vue:13:7:3", "nodeKind": "element",  "tag": "p", "classes": [{ "kind": "literal", "value": "tip" }] },
        { "id": "pages/confirm.vue:14:7:5", "nodeKind": "template", "tag": "template",
          "directives": [{ "name": "slot", "argument": { "kind": "expression", "source": "footerSlot" } }],
          "children": [{ "nodeKind": "component", "tag": "Button", "resolution": { "kind": "resolved", "contractId": "button" } }] }
      ]
    }]
  }],
  "styles": [
    { "source": "sfc-scoped", "selector": ".page[data-v-9f2c1a3b]", "property": "display", "value": { "kind": "literal", "value": "flex" } },
    "…flex-direction / gap / padding 三条同形…"
  ],
  "layout": {
    "relations": [
      { "kind": "containment", "parentId": "pages/confirm.vue:11:3:1", "childId": "pages/confirm.vue:12:5:2" },
      { "kind": "axis", "nodeId": "pages/confirm.vue:11:3:1", "value": "column" },
      { "kind": "gap",  "nodeId": "pages/confirm.vue:11:3:1", "value": 16 },
      "…padding 一条…"
    ]
  },
  "unresolved": [
    { "kind": "unresolved", "reason": "unresolved-symbol",
      "detail": "Class 'tip' was matched neither by UnoCSS nor by component or global styles." }
  ]
}

// src/verify-v2/static-verifier.ts（伪代码，按真实流程精简）
function verifyStatic({ decision, design, usage, catalog }): VerifyReport {
  const obligations: ProofObligation[] = []

  // 1. 四枚指纹先对。decision 里缺这枚 -> unknown(stale-fingerprint)；对不上 -> fail，带 expected/actual
  //    任何一枚 fail，后面的义务照样生成，但整单一定是 fail
  for (const [name, expected, actual] of [
    ['extractor', decision.fingerprints.extractor, catalog.fingerprints.extractor],
    ['design',    decision.fingerprints.design,    design.source.fingerprint],
    ['catalog',   decision.fingerprints.catalog,   catalog.fingerprint],
    ['source',    decision.fingerprints.source,    usage.source.fingerprint],
  ]) obligations.push(fingerprintProof(name, expected, actual))

  // 2. 两份 IR 自带的 unresolved 原样投影成 unknown，不吞掉
  design.unresolved.forEach((fact, i) => obligations.push(unknown(`semantic:design-unresolved:${i}`, fact)))
  usage.unresolved.forEach((fact, i)  => obligations.push(unknown(`boundary:source-unresolved:${i}`, fact)))

  // 3. 三个定位。usageNode 认的是 resolution.contractId，不是 tag 字符串
  const designNode = flatten(design.roots).find(n => n.id === decision.designNodeId)
  const contract   = catalog.contracts.find(c => c.id === decision.target)
  const usageNode  = flatten(usage.roots).find(n => n.resolution.kind === 'resolved' && n.resolution.contractId === decision.target)
  obligations.push(designNode ? pass('structure:design-node')        : fail('structure:design-node', 'Design node … was not found.'))
  obligations.push(contract   ? pass('contract:selected-component')  : fail('contract:selected-component', 'Catalog contract … was not found.'))
  obligations.push(usageNode  ? pass('structure:selected-component') : fail('structure:selected-component', 'Source does not use ….'))

  // 4. 契约和 usage 节点都在，才查必填项、才逐条对 BindingPlan
  if (contract && usageNode) {
    obligations.push(...verifyRequiredContract(contract, usageNode))
    obligations.push(...verifyOperations(decision.bindingPlan?.operations ?? [], usageNode, usage.styles))
  }
  // 5. 设计节点和 usage 节点都在，才碰布局骨架
  if (designNode && usageNode) obligations.push(...skeletonLayoutObligations(designNode, usageNode, design, usage))

  // 6. 聚合：有 fail -> fail；否则有 unknown -> unknown；否则 pass
  const status = reportStatus(obligations)
  return VerifyReportSchema.parse({
    kind: 'verify-report', id: `verify:${decision.id}:static`, decisionId: decision.id,
    fingerprints: { /* 以当前实际值为准重新写一遍 */ },
    target: { kind: 'static', sourceFile: usage.source.file },
    obligations, status,
    disposition: status === 'pass' ? 'accepted' : status === 'fail' ? 'rejected' : 'needs-review',
    artifacts: [],   // 静态阶段没有产物，截图之类是 runtime 的事
  })
}

function verifyOperations(operations, node, styles): ProofObligation[] {
  const tokens = tokenChannel(styles)   // 收 styles 里 --xxx 的字面量定义和 var(--xxx) 引用
  return operations.map((op, index) => {
    switch (op.kind) {
      case 'set-prop': {
        const actual = node.props.find(p => p.name === op.prop)?.value
        if (!actual && node.spreads.length) return unknown(`binding:prop:${op.prop}`, 'dynamic-spread')  // 可能在 spread 里
        return compareBinding(`binding:prop:${op.prop}`, op.value, actual)
      }
      case 'bind-model': {
        const actual = node.models.find(m => (m.argument ?? 'modelValue') === op.prop)
        // 缺 v-model -> fail；有 -> 比值。值几乎总是 reference，所以几乎总是 unknown
        return actual ? compareBinding(`binding:model:${op.model}`, op.value, actual.value)
                      : fail(`binding:model:${op.model}`, `v-model ${op.model} is absent.`)
      }
      case 'bind-event':
        // 只查有没有绑，不比 handler。handler 是什么函数静态证不了
        return node.events.some(e => e.name === op.event)
          ? pass(`behavior:event:${op.event}`) : fail(`behavior:event:${op.event}`, `Event ${op.event} is not bound.`)
      case 'fill-slot': {
        const literalHit = node.slots.some(s => s.name.kind === 'literal' && s.name.value === op.slot)
        const defaultHit = op.slot === 'default' && node.children.some(c => c.nodeKind !== 'template')  // default 槽：有非 template 子节点就算填了
        if (literalHit || defaultHit) return pass(`structure:slot:${op.slot}`)
        if (node.slots.some(s => s.name.kind !== 'literal')) return unknown(`structure:slot:${op.slot}`, 'runtime-required')  // 动态槽名可能填的就是它
        return fail(`structure:slot:${op.slot}`, `Slot ${op.slot} is not filled.`)
      }
      case 'compose-wrapper': return unknown(`boundary:wrapper:${index}`, 'runtime-required')  // 要祖先感知，静态不证
      case 'outer-layout':    return unknown(`layout:outer:${index}`, 'runtime-required')      // 要几何，静态不证
      case 'token-override':  return verifyTokenOverride(op, tokens)
      default:                return unknown(`contract:operation:${index}`, 'unsupported-vue-construct')
    }
  })
}

// 三态比较，整个静态校验里最常被调用的函数
function compareBinding(id, expected, actual): ProofObligation {
  if (!actual) return fail(id, 'Expected binding is absent.', expected, undefined)
  // reference / expression / unresolved 静态拿不到最终值 -> unknown(dynamic-expression)
  if (actual.kind === 'unresolved' || actual.kind === 'expression' || actual.kind === 'reference')
    return unknown(id, actual.kind === 'unresolved' ? actual : unresolvedFact('dynamic-expression', ...))
  // 剩下 literal / object / array，整体序列化后比
  return JSON.stringify(expected) === JSON.stringify(actual) ? pass(id) : fail(id, 'Binding value differs.', expected, actual)
}

// schemas/verify.ts（精简）
interface VerifyReport {
  kind: 'verify-report'
  id: string                                  // verify:<decisionId>:static
  decisionId: string
  fingerprints: { extractor: string, catalog: string, design: string, source: string }
  target: { kind: 'static', sourceFile: string }
        | { kind: 'route' | 'component', scenarioId: string, viewport: {…}, … }   // runtime 用
  obligations: ProofObligation[]
  status: 'pass' | 'fail' | 'unknown'
  disposition?: 'accepted' | 'rejected' | 'needs-review'
  artifacts: Array<{ kind: 'dom' | 'computed-style' | 'geometry' | 'screenshot' | 'visual-diff' | …, diagnosticOnly: boolean, … }>
  createdAt: string
}

d2c verify static \
  --decision .d2c/decisions/confirm-dialog.json \
  --design   .d2c/design/confirm.json \
  --file     pages/confirm.vue \
  --out      .d2c/verify/confirm-dialog.static.json

{
  "kind": "verify-report",
  "id": "verify:decision:confirm-dialog:static",
  "target": { "kind": "static", "sourceFile": "pages/confirm.vue" },
  "obligations": [
    { "id": "boundary:fingerprint:extractor", "category": "boundary", "outcome": "pass" },
    "…design / catalog / source 三枚指纹 pass…",
    { "id": "boundary:source-unresolved:0", "category": "boundary", "outcome": "unknown",
      "unresolved": { "reason": "unresolved-symbol", "detail": "Class 'tip' was matched neither by UnoCSS nor by component or global styles." } },
    { "id": "structure:design-node",        "category": "structure", "outcome": "pass" },
    { "id": "contract:selected-component",  "category": "contract",  "outcome": "pass" },
    { "id": "structure:selected-component", "category": "structure", "outcome": "pass" },
    { "id": "contract:required-prop:title", "category": "contract",  "outcome": "pass" },
    { "id": "binding:prop:title",           "category": "contract",  "outcome": "pass" },
    { "id": "binding:prop:size",            "category": "contract",  "outcome": "unknown",
      "unresolved": { "reason": "dynamic-expression", "detail": "Binding size requires runtime proof." } },
    { "id": "binding:prop:closable",        "category": "contract",  "outcome": "pass" },
    { "id": "binding:model:modelValue",     "category": "contract",  "outcome": "unknown",
      "unresolved": { "reason": "dynamic-expression", "detail": "Binding visible requires runtime proof." } },
    { "id": "behavior:event:confirm",       "category": "behavior",  "outcome": "pass" },
    { "id": "structure:slot:default",       "category": "structure", "outcome": "pass" },
    { "id": "structure:slot:footer",        "category": "structure", "outcome": "unknown",
      "unresolved": { "reason": "runtime-required", "detail": "A dynamic slot name may fill slot footer; runtime proof is required." } },
    { "id": "skeleton:design:dialog-1",     "category": "layout",    "outcome": "unknown",
      "unresolved": { "reason": "runtime-required", "detail": "Skeleton layout proof requires source-side layout facts; the usage layout graph has none for node pages/confirm.vue:12:5:2." } }
  ],
  "status": "unknown",
  "disposition": "needs-review",
  "artifacts": []
}