基于 FigmaMCP 的 D2C 工具(五): decide——reuse / extend / new 的判定

export function solveReuse(
  design: DesignIntentIR,     // 上一篇 ingest 的产物
  catalog: CatalogSnapshot,   // 第三篇三层合并后的快照 这里只读
  options: SolveOptions,
): DecisionRecord

export interface SolveOptions {
  taskId: string
  scope: string                        // 目标代码路径 hazard / recipe 都按它匹配
  designNodeId?: string                // 不传时按约定找默认节点 排障时我建议显式传
  retrievedCandidates?: RetrievedCandidate[]      // 调用方额外塞的候选 只参与排序
  providedBindings?: Record<string, BindingValue> // 调用方直接给的 prop 值
  extensionRequests?: ExtensionRequest[]          // 请求按配方做扩展
  candidateUniverseComplete?: boolean  // 调用方断言候选宇宙完整 能不能判 new 看它
  sourceFingerprint?: string           // 实现侧源码指纹 verify 时对账
  createdAt?: string
}

export interface DecisionRecord {
  schemaVersion: 2
  kind: 'decision'
  id: string                      // decision:<taskId>:<designNodeId>
  taskId: string
  designIntentId: string
  designNodeId: string
  fingerprints: FingerprintSet    // 四个输入哈希 见第 7 节
  candidateUniverse: {
    scope: string
    status: 'complete' | 'incomplete'
    fingerprint: string           // 就是 catalog 指纹
  }
  candidates: Array<CandidateEvaluation | CompactCandidate>
  verdict: 'reuse' | 'extend' | 'new' | 'needs-review'
  target?: string                 // 选中的组件 id
  bindingPlan?: BindingPlan       // 见第 4 节
  pendingObligations?: ProofObligation[]  // 选中候选上仍为 unknown 的约束 留给 verify
  unresolved: UnresolvedFact[]    // 本轮解不开的事实
  review?: { status: 'unreviewed' | 'approved' | 'rejected', reviewer?: string, reviewedAt?: string }
  createdAt: string
}

// 每个候选各自一份评估
export interface CandidateEvaluation {
  componentId: string
  retrieval: {
    rank: number                  // 排序后的位置 从 0 开始
    sources: Array<'identity-link' | 'role-index' | 'structure-index' | 'history' | 'embedding' | 'model'>
    rankingScore?: number
  }
  outcome: 'satisfiable' | 'unsatisfiable' | 'unknown'
  constraints: ProofObligation[]  // 全部硬约束的结果
  unsatisfiedCore: string[]       // fail 掉的约束 id
  bindingPlan?: BindingPlan
}

function retrieveCandidates(design, catalog, external, includeCompleteUniverse) {
  const merged = new Map<string, RetrievedCandidate>()

  // 1. identity-link：设计节点自带 codeComponentId，或 componentKey 经 links 映到组件
  //    rankingScore 用 Number.MAX_SAFE_INTEGER 不用 Infinity 原因见 2.2
  const explicit = design.component?.codeComponentId
    ?? catalog.links.find(l => l.componentKey === design.component?.componentKey)?.componentId
  if (explicit && catalog.contracts.some(c => c.id === explicit))
    merged.set(explicit, { componentId: explicit, source: 'identity-link', rankingScore: MAX_SAFE_INTEGER })

  if (design.role) {
    // 2. role-index：契约 roles 包含设计 role
    for (const c of catalog.contracts.filter(c => c.roles.includes(design.role)))
      if (!merged.has(c.id)) merged.set(c.id, { componentId: c.id, source: 'role-index' })
    // 3. structure-index：契约 structureFamilies 命中设计 role
    //    verifiedSupport（overrides 回灌的批过次数）折进 rankingScore 只在同 source 内靠前
    for (const c of catalog.contracts.filter(c => c.structureFamilies.includes(design.role)))
      if (!merged.has(c.id)) merged.set(c.id, structureIndexEntry(c))
  }

  // 4. 外部候选（history 等）：不在 catalog 里的直接丢
  for (const cand of external)
    if (catalog.contracts.some(c => c.id === cand.componentId) && !merged.has(cand.componentId))
      merged.set(cand.componentId, cand)

  // 调用方断言宇宙完整时 把带结构签名或人工盖章 eligible 的契约全部拉进来
  // 门槛不变：无签名且没盖章的契约照样不放行
  if (includeCompleteUniverse)
    for (const c of catalog.contracts)
      if ((c.structureFamilies.length || c.autoMatch.eligible) && !merged.has(c.id))
        merged.set(c.id, structureIndexEntry(c))

  // 排序：source 优先级 → rankingScore 降序 → componentId 字典序
  return [...merged.values()].sort((a, b) =>
    sourceRank(a.source) - sourceRank(b.source)
    || (b.rankingScore ?? 0) - (a.rankingScore ?? 0)
    || a.componentId.localeCompare(b.componentId))
}

function sourceRank(source) {
  return ['identity-link', 'role-index', 'structure-index', 'history', 'embedding', 'model'].indexOf(source)
}

export interface ProofObligation {
  id: string                    // 如 contract:prop:type、semantic:role
  category: 'contract' | 'semantic' | 'behavior' | 'structure' | 'layout' | 'boundary'
  phase?: 'static' | 'runtime'  // decide 里产出的全是 static
  outcome: 'pass' | 'fail' | 'unknown'
  expected?: unknown
  actual?: unknown
  differences?: Array<{ path: string, expected: unknown, actual: unknown, message: string }>
  unresolved?: UnresolvedFact   // outcome 为 unknown 时必填 其余情况禁止出现
  evidence?: EvidenceRef[]
}

function evaluateCandidate(ctx, retrieved, rank): CandidateEvaluation {
  const constraints: ProofObligation[] = []

  // 第一组：不看绑定 只看身份与契约状态
  constraints.push(identityConstraint(ctx))      // semantic:identity
  constraints.push(reviewConstraint(ctx))        // contract:auto-match-review
  constraints.push(completenessConstraint(ctx))  // contract:completeness
  constraints.push(semanticConstraint(ctx))      // semantic:role
  constraints.push(hazardConstraint(ctx))        // boundary:hazards
  constraints.push(...designFactConstraints(ctx))// semantic:design-fact:* 把 IR 上的 unresolved 原样带进来

  // 第二组：先构建 BindingPlan 再基于 plan 判剩下三类
  const binding = buildBindingPlan(ctx)
  constraints.push(...binding.constraints)                            // contract:prop:* / behavior:event:* / structure:slot:*
  constraints.push(...requiredSlotConstraints(ctx, binding.plan))     // contract:required-slot:*
  constraints.push(...layoutCapabilityConstraints(ctx, binding.plan)) // layout:capability:*
  constraints.push(...extensionConstraints(ctx, binding.plan))        // boundary:extension:*

  // 汇总：有 fail 就是 unsatisfiable 没 fail 有 unknown 就是 unknown 全 pass 才 satisfiable
  const failures = constraints.filter(c => c.outcome === 'fail')
  const unknown = constraints.filter(c => c.outcome === 'unknown')
  const outcome = failures.length ? 'unsatisfiable' : unknown.length ? 'unknown' : 'satisfiable'

  return {
    componentId: ctx.contract.id,
    retrieval: { rank, sources: [retrieved.source], rankingScore: retrieved.rankingScore },
    outcome,
    constraints,
    unsatisfiedCore: failures.map(c => c.id),
    bindingPlan: binding.plan,
  }
}

export interface BindingPlan {
  schemaVersion: 2
  kind: 'binding-plan'
  componentId: string
  operations: BindingOperation[]
  unresolved: UnresolvedFact[]
}

// 每个操作都带 designEvidence / contractEvidence
// source 记来源 extensionRecipeId 只有走配方的操作才有
type BindingOperation =
  | { kind: 'set-prop', prop: string, value: BindingValue, ...Evidence }
  | { kind: 'bind-model', model: string, prop: string, event: string, value: BindingValue, ...Evidence }
  | { kind: 'bind-event', event: string, handler: BindingValue, ...Evidence }
  | { kind: 'fill-slot', slot: string, contentNodeIds: string[], ...Evidence }
  | { kind: 'token-override', token: string, value: BindingValue, ...Evidence }
  | { kind: 'compose-wrapper', wrapperComponentId: string, ...Evidence }
  | { kind: 'outer-layout', layout: LayoutConstraintGraph, ...Evidence }

interface Evidence {
  designEvidence: EvidenceRef[]
  contractEvidence: EvidenceRef[]
  extensionRecipeId?: string
  source?: 'provided' | 'component-property' | 'link' | 'rule' | 'default'
}

function buildBindingPlan(ctx) {
  const mapped = new Map<string, BindingValue>()
  const provenance = new Map<string, 'provided' | 'component-property' | 'link' | 'rule'>()

  // 1. provided：调用方直接给的 先写进去 但 4.4 节会再卡一道
  for (const [name, value] of Object.entries(ctx.providedBindings))
    mapped.set(name, value), provenance.set(name, 'provided')

  // 2. component-property：Figma componentProperties / variantProperties
  //    名字归一化后（去掉非字母数字 转小写）和契约 prop 同名的直接映 值保留 Figma 原样
  for (const [figmaName, raw] of Object.entries(designProperties)) {
    const prop = ctx.contract.props.find(p => normalizeName(p.name) === normalizeName(figmaName))
    if (prop) mapped.set(prop.name, literal(raw)), provenance.set(prop.name, 'component-property')
  }

  // 3. link：links 上的 propertyMappings 目标可以是 prop / model / event / slot / token
  //    prop 会覆盖上一步同名结果 其余四种直接产出 bind-model / bind-event / fill-slot / token-override
  const link = ctx.links.find(l => l.componentKey === ctx.design.component?.componentKey)
  for (const m of link?.propertyMappings ?? []) { /* 略 */ }

  // 4. rule：按组件 id 索引的硬编码变体规则 只补 link 没映到的洞 link 赢过 rule
  for (const token of variantTokens(ctx.design)) {
    const matched = VARIANT_BINDING_RULES[ctx.contract.id]?.[token]
    if (matched && !mapped.has(matched.target))
      mapped.set(matched.target, matched.value), provenance.set(matched.target, 'rule')
  }

  // 后面几步按顺序：
  // - 设计上还有状态没被任何一步吃掉 → unknown（unresolved-symbol） 不忽略 挂账
  // - mapped 里每个 prop 逐一过：契约有没有这个 prop → 值过不过类型 / validator → provided 有没有配方声明
  // - 必填 prop 没来源 → unknown（runtime-required）
  // - 有文字节点且契约有 default slot → fill-slot default
  // - interactions 里带 click → 契约有 click 事件就 bind-event 没有就 fail
  // - extensionRequests 逐个找 recipe 找到且 target 存在就物化成操作
}

// provenance 为 provided 且值过了类型校验 还要看 scope 内有没有 recipe 声明了这个 prop
if (provenance.get(name) === 'provided' && proof.outcome === 'pass' && !providedBindingDeclared(ctx, name, value)) {
  const fact = unresolvedFact('undeclared-provided-binding',
    `Provided binding ${name} is not declared by an extension recipe for ${ctx.contract.id}; human review is required.`)
  constraints.push(unknown(`contract:provided-binding:${name}`, 'contract', fact))
  continue   // 不产出 set-prop
}

function providedBindingDeclared(ctx, name, value) {
  return findRecipe(ctx.contract.extensionRecipes, { kind: 'set-prop', target: name, value }, ctx.scope) !== undefined
}

export interface ExtensionRecipe {
  id: string
  scopes: string[]              // glob 支持 * 和 **
  operations: Array<{
    kind: 'set-prop' | 'bind-event' | 'fill-slot' | 'compose-wrapper' | 'outer-layout' | 'token-override'
    targets?: string[]          // 不写表示该 kind 下任意 target
    constraints?: Record<string, BindingValue | BindingValue[]>  // 按 target 限定允许的值
  }>
}

{
  "id": "button-order-page",
  "scopes": ["src/views/order/**"],
  "operations": [
    { "kind": "outer-layout" },
    {
      "kind": "set-prop",
      "targets": ["loading"],
      "constraints": { "loading": { "kind": "literal", "value": true } }
    },
    { "kind": "compose-wrapper", "targets": ["Card"] }
  ]
}

function extensionConstraints(ctx, plan): ProofObligation[] {
  return ctx.extensionRequests.map((request, index) => {
    const recipe = findRecipe(ctx.contract.extensionRecipes, request, ctx.scope)
    // 没配方 → fail
    if (!recipe)
      return fail(`boundary:extension:${index}`, 'boundary', `No extension recipe permits ${request.kind}.`)
    // 配方有 但 target 不在契约里 → fail
    if (!extensionTargetExists(ctx.contract, request))
      return fail(`boundary:extension:${index}`, 'boundary', `Extension target ${request.target} is not declared.`)
    // 配方有 target 有 还要看 plan 里真的物化出了带 extensionRecipeId 的操作
    const applied = plan.operations.some(op => op.extensionRecipeId === recipe.id && op.kind === request.kind)
    return applied ? pass(`boundary:extension:${index}`, 'boundary') : fail(`boundary:extension:${index}`, 'boundary', 'could not be materialized')
  })
}

// target 必须在契约里真实存在 每种 kind 查的表不一样
function extensionTargetExists(contract, request) {
  if (request.kind === 'outer-layout') return request.target == null   // outer-layout 不需要 target
  if (!request.target) return false
  if (request.kind === 'set-prop') return contract.props.some(p => p.name === request.target)
  if (request.kind === 'bind-event') return contract.events.some(e => e.name === request.target)
  if (request.kind === 'fill-slot') return contract.slots.some(s => s.name === request.target || (s.dynamic && s.name === '*'))
  if (request.kind === 'compose-wrapper') return contract.dependencies.some(d => d.componentId === request.target)
  return request.kind === 'token-override'
}

function hasExtension(plan?: BindingPlan): boolean {
  return Boolean(plan?.operations.some(op => op.extensionRecipeId))
}
verdict = hasExtension(selected.bindingPlan) ? 'extend' : 'reuse'

const satisfiable = evaluations.filter(c => c.outcome === 'satisfiable')
const exact = exactId ? evaluations.find(c => c.componentId === exactId) : undefined

if (exact) {
  // 显式身份优先于一切排序 link 指着 A A 不满足 不会换成 B
  if (exact.outcome === 'satisfiable') {
    selected = exact
    verdict = hasExtension(exact.bindingPlan) ? 'extend' : 'reuse'
  } else {
    verdict = 'needs-review'
    unresolved.push(...unknownFacts(exact))
    if (exact.outcome === 'unsatisfiable')
      unresolved.push(unresolvedFact('incomplete-component-contract', `Explicit Figma identity ${exact.componentId} violates hard constraints.`))
  }
}
else if (satisfiable.length === 1) {
  // 排名否决：前面还有 unknown 的候选 不能让后面碰巧 satisfiable 的直接过
  const unknownHigherPriority = evaluations.some(c => c.outcome === 'unknown' && c.retrieval.rank < satisfiable[0].retrieval.rank)
  if (unknownHigherPriority) {
    verdict = 'needs-review'
    unresolved.push(...evaluations.flatMap(unknownFacts))
  } else {
    selected = satisfiable[0]
    verdict = hasExtension(selected.bindingPlan) ? 'extend' : 'reuse'
  }
}
// 其余分支：>1 个 satisfiable → ambiguous-component-resolution
//          全部 unsatisfiable 且 isCompleteUniverse → new
//          否则 needs-review 并带上 incomplete-candidate-universe

// 选中候选上的 unknown 约束带走 留给 verify 继续证
const pendingObligations = selected?.constraints.filter(c => c.outcome === 'unknown')

function isCompleteUniverse(catalog, evaluated, asserted?: boolean): boolean {
  if (!asserted) return false   // 调用方没断言 直接 false
  // 宇宙 = 入场门槛放行的契约：带结构签名 或人工盖章 eligible
  const universe = catalog.contracts.filter(c => c.structureFamilies.length > 0 || c.autoMatch.eligible)
  const evaluatedIds = new Set(evaluated.map(c => c.componentId))
  // 每个都评估过 且每个契约都 complete 才算完整
  return universe.every(c => evaluatedIds.has(c.id) && c.completeness.status === 'complete')
}

export interface FingerprintSet {
  extractor: string   // 契约抽取器版本指纹 来自 catalog
  catalog: string     // CatalogSnapshot 指纹
  design: string      // DesignIntentIR 的 source.fingerprint
  source?: string     // 可选 实现侧源码指纹 verify 时再和 usage 对
}

export interface CompactCandidate {
  componentId: string
  retrieval: CandidateEvaluation['retrieval']
  outcome: 'unsatisfiable' | 'unknown'
  unsatisfiedCore: string[]
  unresolvedReasons?: string[]   // unknown 约束的 reason 去重
  compact: true
}

d2c decide \
  --input .d2c/design-intent.json \
  --scope "src/views/order/**" \
  --node-id 12:34 \
  --task-id order-submit \
  --out .d2c/decision.json

{
  "schemaVersion": 2,
  "kind": "decision",
  "id": "decision:order-submit:12:34",
  "taskId": "order-submit",
  "designIntentId": "design-intent:figma-rest:file-abc",
  "designNodeId": "12:34",
  "fingerprints": {
    "extractor": "sha256:9c2e…",
    "catalog": "sha256:41d7…",
    "design": "sha256:b08f…"
  },
  "candidateUniverse": { "scope": "src/views/order/**", "status": "incomplete", "fingerprint": "sha256:41d7…" },
  "candidates": [
    {
      "componentId": "Button",
      "retrieval": { "rank": 0, "sources": ["identity-link"], "rankingScore": 9007199254740991 },
      "outcome": "satisfiable",
      "constraints": [
        { "id": "semantic:identity", "category": "semantic", "outcome": "pass" },
        { "id": "contract:auto-match-review", "category": "contract", "outcome": "pass" },
        { "id": "contract:completeness", "category": "contract", "outcome": "pass" },
        { "id": "semantic:role", "category": "semantic", "outcome": "pass" },
        { "id": "boundary:hazards", "category": "boundary", "outcome": "pass" },
        { "id": "contract:prop:type", "category": "contract", "outcome": "pass" },
        { "id": "contract:prop:size", "category": "contract", "outcome": "pass" },
        { "id": "semantic:default-slot-content", "category": "semantic", "outcome": "pass" },
        { "id": "behavior:event:click", "category": "behavior", "outcome": "pass" }
      ],
      "unsatisfiedCore": [],
      "bindingPlan": {
        "schemaVersion": 2,
        "kind": "binding-plan",
        "componentId": "Button",
        "operations": [
          { "kind": "set-prop", "prop": "type", "value": { "kind": "literal", "value": "primary" }, "source": "link" },
          { "kind": "set-prop", "prop": "size", "value": { "kind": "literal", "value": "Small" }, "source": "component-property" },
          { "kind": "fill-slot", "slot": "default", "contentNodeIds": ["12:35"] },
          { "kind": "bind-event", "event": "click", "handler": { "kind": "reference", "name": "handleClick" } }
        ],
        "unresolved": []
      }
    },
    {
      "componentId": "LegacyButton",
      "retrieval": { "rank": 1, "sources": ["role-index"] },
      "outcome": "unknown",
      "unsatisfiedCore": [],
      "unresolvedReasons": ["incomplete-component-contract"],
      "compact": true
    }
  ],
  "verdict": "reuse",
  "target": "Button",
  "bindingPlan": { "…": "同 candidates[0].bindingPlan" },
  "pendingObligations": [],
  "unresolved": [],
  "createdAt": "2026-03-02T09:12:41.000Z"
}