基于 FigmaMCP 的 D2C 工具(七): verify——skeleton 与运行时量测

export type SkeletonAxis = 'flex-row' | 'flex-col' | 'grid' | 'stack' | 'inline'
export type SkeletonJustify = 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'
export type SkeletonAlign = 'start' | 'center' | 'end' | 'stretch' | 'baseline'
export type SkeletonGap = 'none' | 'tight' | 'normal' | 'loose'
export type SkeletonPadding = 'none' | 'tight' | 'normal' | 'spacious'

export interface SkeletonNode {
  id: string
  // role 只是信息 不参与等价比较
  role?: string
  layout: {
    // undefined 表示这一路没拿到这个事实 不是默认值
    axis: SkeletonAxis | undefined
    justify: SkeletonJustify | undefined
    align: SkeletonAlign | undefined
    gap: SkeletonGap | undefined
    padding: SkeletonPadding | undefined
    sizing: 'hug' | 'fill' | 'fixed' | 'min' | 'max' | undefined
    wrap: 'nowrap' | 'wrap' | 'wrap-reverse' | undefined
    overflow: 'visible' | 'hidden' | 'clip' | 'scroll' | 'auto' | undefined
  }
}

function extractLayout(relations: LayoutRelation[]): SkeletonNode['layout'] {
  for (const rel of relations) {
    switch (rel.kind) {
      case 'axis':
        // unresolved 的不硬填 保持 undefined
        if (isResolved(rel.value))
          axis = rel.value === 'row' ? 'flex-row' : rel.value === 'column' ? 'flex-col' : rel.value
        break
      case 'alignment':
        // 主轴进 justify 交叉轴进 align
        if (isResolved(rel.value))
          rel.axis === 'main' ? (justify = rel.value) : (align = rel.value)
        break
      case 'gap':
        if (typeof rel.value === 'number') gap = projectGap(rel.value)
        break
      case 'padding':
        // 取四边最大的一边定档位 不对称的 padding 不能躲在 top 后面
        if (isResolved(rel.value))
          padding = projectPadding(Math.max(rel.value.top, rel.value.right, rel.value.bottom, rel.value.left))
        break
      // sizing / wrap / overflow 同理 略
    }
  }
  return { axis, justify, align, gap, padding, sizing, wrap, overflow }
}

// 边界写死在这里 改边界等于改证明语义 要走评审
export function projectGap(value: unknown): SkeletonGap | undefined {
  if (typeof value !== 'number') return undefined
  if (value === 0) return 'none'
  if (value >= 1 && value <= 8) return 'tight'
  if (value >= 9 && value <= 24) return 'normal'
  if (value >= 25) return 'loose'
  return undefined
}

// 9～11 和 17～19 是空洞 故意不映射 落不进档位就当没拿到事实
export function projectPadding(value: unknown): SkeletonPadding | undefined {
  if (typeof value !== 'number') return undefined
  if (value === 0) return 'none'
  if (value >= 1 && value <= 8) return 'tight'
  if (value >= 12 && value <= 16) return 'normal'
  if (value >= 20) return 'spacious'
  return undefined
}

export function skeletonDiff(a: SkeletonNode, b: SkeletonNode): SkeletonDiff[] {
  const diffs: SkeletonDiff[] = []
  for (const field of ['axis', 'justify', 'align', 'gap', 'padding', 'sizing', 'wrap', 'overflow'] as const) {
    const aVal = a.layout[field]
    const bVal = b.layout[field]
    // 两边都没有 跳过 不算差异
    if (aVal === undefined && bVal === undefined) continue
    // 一边有一边没有 算 error
    if (aVal === undefined || bVal === undefined) {
      diffs.push({ path: `layout.${field}`, expected: aVal ?? bVal, actual: undefined, severity: 'error' })
      continue
    }
    // 都有但不一样 axis / justify / align / gap 是 error 其余 warn
    if (aVal !== bVal)
      diffs.push({ path: `layout.${field}`, expected: aVal, actual: bVal,
        severity: ['axis', 'justify', 'align', 'gap'].includes(field) ? 'error' : 'warn' })
  }
  return diffs
}

// design skeleton                     // computed skeleton
{                                      {
  "id": "12:340",                        "id": "computed",
  "role": "dialog-body",
  "layout": {                            "layout": {
    "axis": "flex-row",                    "axis": "flex-col",
    "justify": "start",                    "justify": "start",
    "align": "start",                      "align": "stretch",
    "gap": "normal",                       "gap": "normal",
    "padding": "spacious",                 "padding": "spacious",
    "sizing": "fill",                      "sizing": "fill",
    "wrap": "nowrap"                       "wrap": "nowrap"
  }                                      }
}                                      }

{
  "id": "skeleton:12:340",
  "category": "layout",
  "phase": "runtime",
  "outcome": "fail",
  "differences": [
    { "path": "layout.axis", "expected": "flex-row", "actual": "flex-col", "message": "Skeleton diff: layout.axis" },
    { "path": "layout.align", "expected": "start", "actual": "stretch", "message": "Skeleton diff: layout.align" }
  ]
}

export function proveDesignAgainstComputed(designNode, designGraph, computed, evidence): ProofObligation[] {
  const id = `skeleton:${designNode.id}`
  // 元素不存在 → unknown 不是 fail 修映射和修 flex 是两件工作
  if (!computed)
    return [unknown(id, 'layout', unresolvedFact('runtime-required', `No element was found for design node ${designNode.id}.`, evidence))]

  const designSkeleton = projectDesignNode(designNode, designGraph)
  const computedSkeleton = projectComputedStyle(computed)
  // 只保留设计真正声称的字段
  // 浏览器对没写的属性也有默认值 把默认值当设计期望 几乎每张稿都会误挂
  const filtered = emptySkeleton()
  for (const field of FIELDS)
    if (designSkeleton.layout[field] !== undefined)
      filtered.layout[field] = computedSkeleton.layout[field]
  return toObligations(id, skeletonDiff(designSkeleton, filtered), 'runtime')
}

{
  "schemaVersion": 2,
  "kind": "runtime-scenario",
  "id": "settings-dialog-open",
  "target": { "kind": "route", "path": "/settings" },
  "viewport": { "width": 1280, "height": 720 },
  "theme": "light",
  "locale": "zh-CN",
  "setup": {
    "localStorage": { "feature.settingsDialog": "on" }
  },
  "designReference": {
    "nodeId": "12:300",
    "viewport": { "width": 1280, "height": 720 },
    "theme": "light",
    "locale": "zh-CN"
  },
  "selectors": {
    "12:300": "[data-d2c='dialog']",
    "12:340": "[data-d2c='dialog-body']",
    "12:341": "[data-d2c='dialog-form']",
    "12:342": "[data-d2c='dialog-aside']"
  },
  "expectedStyles": {
    "12:340": { "flex-direction": "row" }
  },
  "actions": [
    { "kind": "wait-for", "selector": "[data-d2c='open-settings']", "state": "visible" },
    { "kind": "click", "selector": "[data-d2c='open-settings']" },
    { "kind": "wait-for", "selector": "[data-d2c='dialog']", "state": "visible" }
  ],
  "network": {
    "blockExternal": true,
    "mocks": [
      { "url": "/api/settings", "method": "GET", "status": 200, "body": "{\"items\":[{\"id\":1}]}" }
    ]
  }
}

export async function verifyRuntime(options): Promise<VerifyReport> {
  const obligations: ProofObligation[] = []
  // 1. 先对指纹 对不上后面量什么都没意义
  for (const name of ['extractor', 'catalog', 'design', 'source'])
    obligations.push(fingerprintProof(name, decision.fingerprints[name], current[name]))
  try {
    // 2. 环境固定住
    const context = await browser.newContext({ viewport: scenario.viewport, locale: scenario.locale, colorScheme: scenario.theme })
    await configureNetwork(context, baseURL, scenario)
    await applyContextSetup(context, baseURL, scenario)
    // 3. 导航 状态码不对直接 fail
    const response = await page.goto(new URL(scenario.target.path, baseURL).toString(), { waitUntil: 'domcontentloaded' })
    obligations.push(response?.ok() ? pass('behavior:navigation') : fail('behavior:navigation', `Route returned ${response?.status()}.`))
    // 4. 动作逐条执行 每条一个义务 点不到就 fail
    for (const action of scenario.actions)
      obligations.push(await executeAction(page, action))
    // 5. 采样 + 证明
    const observations = await observeNodes(page, design, scenario)
    obligations.push(...proveRuntimeNodes(design, scenario, observations))
    // 6. 对照前提是否成立
    const problem = designReferenceProblem(scenario, design, observations)
    obligations.push(problem ? unknown('layout:scenario-reference', 'missing-scenario', problem) : pass('layout:scenario-reference'))
    // 7. 落 artifacts 前四类是证据 后两类只诊断
    artifacts.push(...writeObservationArtifacts(observations))
    artifacts.push(artifact('screenshot', await page.screenshot(), /* diagnosticOnly */ true))
    artifacts.push(visualDiffArtifact({ baselinesDir, nodeId: decision.designNodeId, actualPath }))
  }
  catch (error) {
    // 8. 环境起不来 整段 unknown 不是 fail 也不是 pass
    obligations.push(unknown('behavior:runtime-setup', 'missing-setup', `Runtime scenario could not be established: ${error.message}`))
  }
  const status = reportStatus(obligations)
  return VerifyReportSchema.parse({
    id: `verify:${decision.id}:${scenario.id}`,
    decisionId: decision.id,
    fingerprints, target, obligations, artifacts, evidence, status,
    disposition: status === 'pass' ? 'accepted' : status === 'fail' ? 'rejected' : 'needs-review',
  })
}

d2c verify runtime \
  --decision .d2c/decisions/settings-dialog.json \
  --design .d2c/design/settings.json \
  --scenario scenarios/settings-dialog-open.json \
  --base-url http://127.0.0.1:3000 \
  --source-fingerprint 9f2c...e1a0 \
  --out .d2c/verify/settings-dialog.runtime.json

export function mergeDualChannel(staticObs, runtimeObs, evidence): ProofObligation[] {
  for (const s of staticObs) {
    const r = runtimeById.get(s.id)
    if (!r) { merged.push(s); continue }                       // 运行时没这条 留静态
    if (s.outcome === 'unknown') { merged.push(r); continue }  // 静态 unknown → 运行时顶上 这是升级通道
    if (r.outcome === 'unknown') { merged.push(s); continue }  // 运行时 unknown → 留静态
    if (s.outcome === r.outcome) { merged.push(r); continue }  // 一致 → 留运行时 证据更强
    // 冲突 → unknown 带说明 交给人
    merged.push(unknown(s.id, 'unknown', `Dual-channel conflict for ${s.id}: static=${s.outcome}, runtime=${r.outcome}.`))
  }
  // 只有运行时有的义务 直接加进来
  return merged
}

export function visualDiffArtifact(options): VerifyArtifact {
  const baselinePath = join(options.baselinesDir, `${options.nodeId}.png`)
  // 没有 baseline → unavailable 不影响 status
  if (!existsSync(baselinePath))
    return { kind: 'visual-diff', path: baselinePath, diagnosticOnly: true, status: 'unavailable',
      detail: { reason: `No design baseline at ${baselinePath}.` } }
  // baseline 是给旧设计指纹截的 → 同样 unavailable 提醒重截
  const meta = readBaselineMetadata(options.baselinesDir, options.nodeId)
  if (meta?.designFingerprint && meta.designFingerprint !== options.designFingerprint)
    return { kind: 'visual-diff', path: baselinePath, diagnosticOnly: true, status: 'unavailable',
      detail: { reason: `Baseline was captured for design fingerprint ${meta.designFingerprint}.` } }
  // 有 baseline 且指纹对得上 → 算 diff 写 heatmap
  // 尺寸不一致时把 actual 最近邻缩放到 baseline 尺寸 只为让 heatmap 可读
  const result = computeVisualDiff({ baselinePath, actualPath: options.actualPath, heatmapPath })
  return { kind: 'visual-diff', path: heatmapPath, diagnosticOnly: true, status: 'available',
    detail: { ratio: result.ratio, diffPixels: result.diffPixels, totalPixels: result.totalPixels } }
}

export const VerifyReportSchema = z.object({ /* ... */ }).superRefine((report, ctx) => {
  const hasFail = report.obligations.some(o => o.outcome === 'fail')
  const hasUnknown = report.obligations.some(o => o.outcome === 'unknown')
  const expected = hasFail ? 'fail' : hasUnknown ? 'unknown' : 'pass'
  if (report.status !== expected)
    ctx.addIssue({ path: ['status'], message: `Report status must be ${expected} for its proof outcomes.` })
  // 只有全 pass 的报告才能 accepted
  if (report.disposition === 'accepted' && report.status !== 'pass')
    ctx.addIssue({ path: ['disposition'], message: 'Only passing proof reports can be accepted.' })
})

{
  "id": "verify:decision:settings:12:300:settings-dialog-open",
  "status": "fail",
  "disposition": "rejected",
  "obligations": [
    { "id": "boundary:fingerprint:catalog", "outcome": "pass" },
    { "id": "behavior:navigation", "outcome": "pass" },
    { "id": "behavior:action:click:[data-d2c='open-settings']", "outcome": "pass" },
    { "id": "behavior:action:wait-for:[data-d2c='dialog']", "outcome": "pass" },
    { "id": "structure:present:12:342", "outcome": "pass" },
    {
      "id": "layout:style:12:340:flex-direction",
      "outcome": "fail",
      "expected": "row",
      "actual": "column"
    },
    {
      "id": "layout:geometry:12:342",
      "outcome": "fail",
      "differences": [
        { "path": "12:342.x", "expected": 432, "actual": 24, "tolerance": 4, "message": "Geometry delta 408px exceeds 4px." },
        { "path": "12:342.y", "expected": 24, "actual": 318, "tolerance": 4, "message": "Geometry delta 294px exceeds 4px." }
      ]
    },
    { "id": "structure:containment:12:340>12:342", "outcome": "pass" },
    { "id": "structure:order:12:340", "outcome": "pass" },
    { "id": "layout:scenario-reference", "outcome": "pass" }
  ],
  "artifacts": [
    { "kind": "geometry", "path": ".d2c/artifacts/settings-dialog-open.geometry.json", "diagnosticOnly": false },
    { "kind": "screenshot", "path": ".d2c/artifacts/settings-dialog-open.png", "diagnosticOnly": true },
    { "kind": "visual-diff", "path": ".d2c/baselines/12:300.png", "diagnosticOnly": true, "status": "unavailable" }
  ]
}