cardbuddy 0.11.0 → 0.12.1

package/dist/vendored/skills/dsl-card-generator/scripts/diff_card.mjs

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+/**
+ * diff_card.mjs — 卡片 schema 变更对比工具。
+ *
+ * 用途：
+ *  - 把"未涉及节点/字段与孤儿字段逐字节保留"这条铁律从提示词约束升级到机械兜底。
+ *  - 每次 AI 整体替换 schema 后跑一次，肉眼/CI 立即看到：
+ *      · 删除了哪些 componentId（最严重，可能是误删）
+ *      · 新增了哪些 componentId（提醒是否真要新增）
+ *      · 现有 componentId 上修改了哪些字段（properties/style/events/directives）
+ *  - 支持两种基线来源：指定 JSON 文件、另一张已存在卡（不依赖宿主 git）。
+ *
+ * 用法：
+ *   node diff_card.mjs --id <cardId> --baseline <path.json>   # vs 指定基线文件
+ *   node diff_card.mjs --id <cardId> --baseline <path.json>   # vs 指定基线文件
+ *   node diff_card.mjs --id <cardId> --against <otherCardId>  # vs 另一张卡
+ *   node diff_card.mjs --id <cardId> --json                   # 机器可读输出
+ *   node diff_card.mjs --id <cardId> --strict                 # 有 diff 时 exit 1（CI 用）
+ *
+ * 输出策略：
+ *  - 按 componentId 维度组织，先列"删除/新增"（结构性变化），再列"字段修改"（细节变化）。
+ *  - 简单值用 before/after 直观对比；复杂对象（如 customAction function.code）只显示
+ *    "changed"不展开内容（避免日志被淹没）。
+ *  - 字符串值差异 ≤ 200 字符时显示完整 before/after；超出则截断并标 `...truncated`。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { cardSchemaPath, readJson } from './lib/paths.mjs'
+
+/* ------------------------------------------------------------------ */
+/* 参数解析                                                            */
+/* ------------------------------------------------------------------ */
+function parseArgs(argv) {
+  const out = { id: '', baseline: '', against: '', json: false, strict: false }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--id') out.id = argv[++i]
+    else if (a === '--baseline') out.baseline = argv[++i]
+    else if (a === '--against') out.against = argv[++i]
+    else if (a === '--json') out.json = true
+    else if (a === '--strict') out.strict = true
+    else if (a === '-h' || a === '--help') {
+      console.log(`Usage: node diff_card.mjs --id <cardId> [options]
+
+Options:
+  --baseline <path.json>   与指定 JSON 文件对比
+  --against <otherCardId>  与另一张已存在卡对比
+  --json                   机器可读 JSON 输出（便于 CI/MCP 消费）
+  --strict                 有 diff 时 exit 1（CI 用）
+  -h, --help               显示本帮助`)
+      process.exit(0)
+    }
+  }
+  if (!out.id) {
+    console.error('[error] 缺少必填参数 --id <cardId>')
+    process.exit(1)
+  }
+  return out
+}
+
+/* ------------------------------------------------------------------ */
+/* 基线加载                                                            */
+/* ------------------------------------------------------------------ */
+function loadBaseline({ id, baseline, against }) {
+  // 1) 显式基线文件
+  if (baseline) {
+    const p = path.resolve(baseline)
+    if (!fs.existsSync(p)) throw new Error(`baseline 文件不存在: ${p}`)
+    return { schema: readJson(p), source: p }
+  }
+  // 2) 对比另一张卡
+  if (against) {
+    const p = cardSchemaPath(against)
+    if (!fs.existsSync(p)) throw new Error(`对比卡不存在: ${against} (${p})`)
+    return { schema: readJson(p), source: `card:${against}` }
+  }
+  // 3) 无显式基线/对比卡：不再依赖宿主 git 仓库，直接给出可移植提示。
+  throw new Error(
+    '未指定基线来源。请使用 --baseline <path.json> 或 --against <otherCardId>（本 skill 不依赖 git 仓库）。',
+  )
+}
+
+/* ------------------------------------------------------------------ */
+/* 节点收集：扁平化为 componentId -> { node, path } 索引               */
+/* ------------------------------------------------------------------ */
+function collectNodes(view, out = new Map(), route = []) {
+  if (!view || typeof view !== 'object') return out
+  const cid = view.componentId
+  const here = cid ? [...route, cid] : route
+  if (cid) {
+    out.set(cid, { node: view, path: here })
+  }
+  // Root 用 components，其它用 slots[].components
+  const kids = []
+  if (Array.isArray(view.components)) kids.push(...view.components)
+  for (const s of view.slots || []) kids.push(...(s.components || []))
+  for (const k of kids) collectNodes(k, out, here)
+  return out
+}
+
+/* ------------------------------------------------------------------ */
+/* 节点级 diff（同一 componentId 的属性/样式/事件/指令对比）            */
+/* ------------------------------------------------------------------ */
+const TRUNCATE_AT = 200
+function fmt(v) {
+  if (v === undefined) return undefined
+  const s = typeof v === 'string' ? v : JSON.stringify(v)
+  if (s == null) return undefined
+  return s.length > TRUNCATE_AT ? s.slice(0, TRUNCATE_AT) + '...truncated' : s
+}
+
+function diffPropList(before, after, label) {
+  // before/after: properties[]（含 itemKey/itemValue/itemValueFrom/itemDefaultValue 等）
+  const out = []
+  const beforeMap = new Map((before || []).map((p) => [p.itemKey, p]))
+  const afterMap = new Map((after || []).map((p) => [p.itemKey, p]))
+  // 删除的 itemKey
+  for (const [k] of beforeMap) {
+    if (!afterMap.has(k)) out.push({ kind: 'removed', path: `${label}[${k}]`, note: '字段被删除（铁律：未涉及字段应保留）' })
+  }
+  // 新增的 itemKey
+  for (const [k] of afterMap) {
+    if (!beforeMap.has(k)) out.push({ kind: 'added', path: `${label}[${k}]`, note: '字段被新增' })
+  }
+  // 修改的字段（值/来源/默认值差异）
+  for (const [k, a] of afterMap) {
+    const b = beforeMap.get(k)
+    if (!b) continue
+    const bj = JSON.stringify(b)
+    const aj = JSON.stringify(a)
+    if (bj !== aj) {
+      // 进一步细分哪个子字段变了，便于阅读
+      const sub = []
+      for (const f of ['itemValue', 'itemValueFrom', 'itemDefaultValue', 'itemId']) {
+        if (JSON.stringify(b[f]) !== JSON.stringify(a[f])) {
+          sub.push({ field: f, before: fmt(b[f]), after: fmt(a[f]) })
+        }
+      }
+      out.push({
+        kind: 'modified',
+        path: `${label}[${k}]`,
+        sub,
+        before: fmt(b),
+        after: fmt(a),
+      })
+    }
+  }
+  return out
+}
+
+function diffEventActions(before, after, label) {
+  const out = []
+  // eventactions 没有 componentId，按 eventKey + actionType 索引（足够区分）
+  const key = (ea) => `${ea?.event?.eventKey || ''}/${ea?.action?.actionType || ''}`
+  const beforeMap = new Map((before || []).map((ea) => [key(ea), ea]))
+  const afterMap = new Map((after || []).map((ea) => [key(ea), ea]))
+  for (const [k] of beforeMap) {
+    if (!afterMap.has(k)) out.push({ kind: 'removed', path: `${label}.events[${k}]`, note: '事件被删除' })
+  }
+  for (const [k] of afterMap) {
+    if (!beforeMap.has(k)) out.push({ kind: 'added', path: `${label}.events[${k}]`, note: '事件被新增' })
+  }
+  for (const [k, a] of afterMap) {
+    const b = beforeMap.get(k)
+    if (!b) continue
+    if (JSON.stringify(b) !== JSON.stringify(a)) {
+      out.push({ kind: 'modified', path: `${label}.events[${k}]`, before: fmt(b), after: fmt(a) })
+    }
+  }
+  return out
+}
+
+function diffNode(before, after, cid) {
+  const out = []
+  // className 变更
+  if (before.className !== after.className) {
+    out.push({ kind: 'modified', path: `${cid}.className`, before: before.className, after: after.className })
+  }
+  // properties / style.properties / directives
+  out.push(...diffPropList(before.properties, after.properties, `${cid}.properties`))
+  out.push(...diffPropList(before.style?.properties, after.style?.properties, `${cid}.style.properties`))
+  out.push(...diffPropList(before.directives, after.directives, `${cid}.directives`))
+  // eventactions
+  out.push(...diffEventActions(before.eventactions, after.eventactions, cid))
+  return out
+}
+
+/* ------------------------------------------------------------------ */
+/* 主 diff                                                             */
+/* ------------------------------------------------------------------ */
+function diffSchema(beforeSchema, afterSchema) {
+  const beforeNodes = collectNodes(beforeSchema.view)
+  const afterNodes = collectNodes(afterSchema.view)
+
+  const removed = [] // 删除的 componentId（最严重）
+  const added = [] // 新增的 componentId
+  const modified = [] // 现有节点的字段修改
+
+  for (const [cid] of beforeNodes) {
+    if (!afterNodes.has(cid)) {
+      removed.push({ componentId: cid, className: beforeNodes.get(cid).node.className })
+    }
+  }
+  for (const [cid] of afterNodes) {
+    if (!beforeNodes.has(cid)) {
+      added.push({ componentId: cid, className: afterNodes.get(cid).node.className })
+    }
+  }
+  for (const [cid, a] of afterNodes) {
+    const b = beforeNodes.get(cid)
+    if (!b) continue // 新增的节点已在 added 里
+    const changes = diffNode(b.node, a.node, cid)
+    if (changes.length) modified.push({ componentId: cid, className: b.node.className, changes })
+  }
+
+  // 顶层结构变化（pageId/name/platform/version）
+  const topChanges = []
+  for (const f of ['version', 'pageId', 'name', 'platform']) {
+    if (beforeSchema[f] !== afterSchema[f]) {
+      topChanges.push({ field: f, before: beforeSchema[f], after: afterSchema[f] })
+    }
+  }
+
+  return { removed, added, modified, topChanges }
+}
+
+/* ------------------------------------------------------------------ */
+/* 输出渲染                                                            */
+/* ------------------------------------------------------------------ */
+function renderHuman(diff, baselineSource, afterId) {
+  const lines = []
+  lines.push(`[diff] card=${afterId}  baseline=${baselineSource}`)
+  lines.push('')
+
+  // 顶层变化
+  if (diff.topChanges.length) {
+    lines.push('## 顶层字段变化')
+    for (const c of diff.topChanges) lines.push(`  ${c.field}: ${fmt(c.before)} → ${fmt(c.after)}`)
+    lines.push('')
+  }
+
+  // 删除（最严重）
+  if (diff.removed.length) {
+    lines.push(`## ❌ 删除的 componentId（${diff.removed.length}）—— 铁律：未涉及节点应保留`)
+    for (const r of diff.removed) lines.push(`  - ${r.componentId} (${r.className})`)
+    lines.push('')
+  }
+
+  // 新增
+  if (diff.added.length) {
+    lines.push(`## ✨ 新增的 componentId（${diff.added.length}）`)
+    for (const a of diff.added) lines.push(`  + ${a.componentId} (${a.className})`)
+    lines.push('')
+  }
+
+  // 修改
+  if (diff.modified.length) {
+    lines.push(`## ✏️  字段修改（${diff.modified.length} 个节点）`)
+    for (const m of diff.modified) {
+      lines.push(`  ${m.componentId} (${m.className}):`)
+      for (const c of m.changes) {
+        const tag = c.kind === 'added' ? '+' : c.kind === 'removed' ? '-' : '~'
+        if (c.kind === 'modified' && c.sub) {
+          lines.push(`    ${tag} ${c.path}`)
+          for (const s of c.sub) lines.push(`        ${s.field}: ${fmt(s.before)} → ${fmt(s.after)}`)
+        } else {
+          const tail = c.note ? `  // ${c.note}` : (c.before !== undefined ? `  ${fmt(c.before)} → ${fmt(c.after)}` : '')
+          lines.push(`    ${tag} ${c.path}${tail}`)
+        }
+      }
+    }
+    lines.push('')
+  }
+
+  if (!diff.removed.length && !diff.added.length && !diff.modified.length && !diff.topChanges.length) {
+    lines.push('（无差异）')
+  }
+
+  // 总结
+  const total = diff.removed.length + diff.added.length + diff.modified.length + diff.topChanges.length
+  lines.push(`---`)
+  lines.push(`总计：删除 ${diff.removed.length} / 新增 ${diff.added.length} / 修改 ${diff.modified.length} / 顶层 ${diff.topChanges.length}（${total === 0 ? '完全一致' : '有差异'}）`)
+
+  return lines.join('\n')
+}
+
+/* ------------------------------------------------------------------ */
+/* main                                                                */
+/* ------------------------------------------------------------------ */
+function main() {
+  const args = parseArgs(process.argv.slice(2))
+  const afterSchemaPath = cardSchemaPath(args.id)
+  if (!fs.existsSync(afterSchemaPath)) {
+    console.error(`[error] 卡片不存在: ${afterSchemaPath}`)
+    process.exit(2)
+  }
+  const after = readJson(afterSchemaPath)
+  const { schema: before, source } = loadBaseline(args)
+  if (!before || !before.view) {
+    console.error(`[error] 基线 schema 结构不合法（缺 view 字段）：${source}`)
+    process.exit(2)
+  }
+  const diff = diffSchema(before, after)
+
+  if (args.json) {
+    console.log(JSON.stringify({ id: args.id, baseline: source, ...diff }, null, 2))
+  } else {
+    console.log(renderHuman(diff, source, args.id))
+  }
+
+  const total = diff.removed.length + diff.added.length + diff.modified.length + diff.topChanges.length
+  process.exit(total === 0 ? 0 : (args.strict ? 1 : 0))
+}
+
+main()