cardbuddy 0.11.0 → 0.12.1

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

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+/**
+ * check_fidelity.mjs — 保真度门禁（L4 / fidelity 层）
+ *
+ * 读 spec.json 标注，对产物 schema.json 做「元素级对齐断言」：
+ *   1. 文本覆盖：spec 每个文本元素应在 schema 中找到对应 Text（内容匹配）。
+ *   2. 字号对齐：匹配项 |spec.fontSize − schema.fontSize| ≤ --font-tol（默认 2）。
+ *   3. 颜色对齐：匹配项 rgba 各通道差 ≤ --color-tol（默认 24）。
+ *
+ * 这是唯一能覆盖「间距/颜色/字号」的门禁层，也是设计稿链路最高频错误。
+ * 前四层（validate / lint / preflight / diff）查不出这类偏差。
+ *
+ * 复用 preflight.mjs 的 spec↔schema 交叉校验骨架（spec 侧读 card.elements，
+ * schema 侧 walk view 树收集 Text 节点）。
+ *
+ * 退出码：0 = 无偏差；非 0 = 存在未覆盖 / 超差项（供 CI 识别）。
+ *
+ * 用法：
+ *   node scripts/check_fidelity.mjs --spec UI/<画板>/spec.json --schema src/cards/<id>/schema.json
+ *   node scripts/check_fidelity.mjs --spec <spec.json> --schema <schema.json> --card 1 --json
+ *   node scripts/check_fidelity.mjs --spec <spec.json> --schema <schema.json> --font-tol 1 --color-tol 16
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+function parseArgs(argv) {
+  const out = { spec: '', schema: '', card: 1, json: false, fontTol: 2, colorTol: 24, data: '' }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--spec') out.spec = argv[++i] || ''
+    else if (a === '--schema') out.schema = argv[++i] || ''
+    else if (a === '--data') out.data = argv[++i] || ''
+    else if (a === '--card') out.card = Number(argv[++i]) || 1
+    else if (a === '--json') out.json = true
+    else if (a === '--font-tol') out.fontTol = Number(argv[++i]) || 2
+    else if (a === '--color-tol') out.colorTol = Number(argv[++i]) || 24
+    else if (a === '-h' || a === '--help') {
+      console.log('Usage: node check_fidelity.mjs --spec <spec.json> --schema <schema.json> [--data data.json] [--card 1] [--json] [--font-tol 2] [--color-tol 24]')
+      process.exit(0)
+    }
+  }
+  if (!out.spec || !out.schema) {
+    console.error('缺少 --spec 或 --schema')
+    process.exit(1)
+  }
+  return out
+}
+
+/* ── spec 侧：收集文本元素 ───────────────────────────────────── */
+function collectSpecTexts(card) {
+  const els = card.elements || []
+  const out = []
+  for (const el of els) {
+    const t = el.text
+    if (!t || !String(t).trim()) continue
+    const ts = el.textStyle || {}
+    out.push({
+      text: String(t).trim(),
+      fontSize: ts.fontSize != null ? Number(ts.fontSize) : null,
+      color: ts.color || null,
+    })
+  }
+  return out
+}
+
+/* ── schema 侧：walk view 树收集 Text 节点 ──────────────────── */
+function collectSchemaTexts(node, acc) {
+  if (!node || typeof node !== 'object') return
+  if (node.className === 'Text') {
+    // v3 文本值存于 node.properties（与 style 同级的数组，itemKey==='value'）；
+    // 字号/颜色存于 node.style.properties 的 itemKey==='font' 子节点。
+    // 旧版(0.x)文本值可能直接存于 style.properties。两处都扫，兼容两种结构。
+    // 注意：原实现用 `node.style?.properties || node.properties` 在 style.properties
+    // 存在时永不回退到 node.properties，导致 v3 文本 100% 漏读（满屏 missing-text 误报）。
+    const textProps = [...(node.properties || []), ...(node.style?.properties || [])]
+    let value = null
+    let itemDefaultValue = null
+    let fontSize = null
+    let color = null
+    for (const p of textProps) {
+      if (!p || typeof p !== 'object') continue
+      if (p.itemKey === 'value') {
+        value = p.itemValue
+        if (p.itemDefaultValue != null) itemDefaultValue = p.itemDefaultValue
+      } else if (p.itemKey === 'font' && p.itemChildren && p.itemChildren.properties) {
+        for (const c of p.itemChildren.properties) {
+          if (c.itemKey === 'fontSize') fontSize = Number(c.itemValue)
+          else if (c.itemKey === 'color') color = c.itemValue
+        }
+      }
+    }
+    acc.push({ value, itemDefaultValue, fontSize, color })
+  }
+  // 子组件
+  const kids = node.components || node.children || []
+  if (Array.isArray(kids)) for (const k of kids) collectSchemaTexts(k, acc)
+  // 插槽
+  const slots = node.slots || []
+  if (Array.isArray(slots)) {
+    for (const s of slots) {
+      collectSchemaTexts(s, acc)
+      if (Array.isArray(s.components)) for (const k of s.components) collectSchemaTexts(k, acc)
+    }
+  }
+}
+
+/* ── 匹配与比较 ──────────────────────────────────────────────── */
+function norm(s) {
+  return (s == null ? '' : String(s)).replace(/\s+/g, '').trim()
+}
+
+/* ── 绑定表达式解析：$key / $key.sub / $key[0] 查变量值表；三元分支里的字面量也算候选 ── */
+function lookupPath(p, values) {
+  const parts = String(p).split(/\.|\[(\d+)\]/).filter((x) => x !== undefined && x !== '')
+  let cur = values
+  for (const k of parts) {
+    if (cur == null) return undefined
+    cur = cur[k]
+  }
+  return cur
+}
+
+/**
+ * 表达式 Text 的候选字面量：把 $ 绑定按变量值表（data.json / dictionary 默认值）解析回文案。
+ * 不解析的话「绑了变量」的卡会 100% 报 missing-text —— 门禁逼着模型把变量拆回字面量，
+ * 这正是此前产物 dictionary / data.json 全空的直接推手之一。
+ */
+function resolveExprCandidates(expr, values) {
+  const out = []
+  const re = /\$([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z0-9_]+|\[\d+\])*)/g
+  let m
+  while ((m = re.exec(expr))) {
+    const v = lookupPath(m[1], values)
+    if (v != null && typeof v !== 'object') out.push(String(v))
+  }
+  // '$showAll ? "收起" : "查看更多"' 这类分支字面量也是真实会显示的文案
+  for (const q of expr.match(/'([^']*)'|"([^"]*)"/g) || []) out.push(q.slice(1, -1))
+  return out
+}
+
+// 一个 schema Text 节点的候选字面量：直接字面 value + 绑定解析值 + itemDefaultValue
+function candidates(t, values = {}) {
+  const c = []
+  if (typeof t.value === 'string' && !t.value.includes('$') && !t.value.includes("'")) c.push(t.value)
+  if (typeof t.value === 'string' && t.value.includes('$')) c.push(...resolveExprCandidates(t.value, values))
+  if (t.itemDefaultValue != null) c.push(String(t.itemDefaultValue))
+  return c.map(norm).filter(Boolean)
+}
+
+function parseRgba(s) {
+  if (!s) return null
+  const m = String(s).match(/rgba?\(([^)]+)\)/)
+  if (!m) return null
+  const p = m[1].split(',').map((x) => parseFloat(x))
+  if (p.length < 3 || p.some((n) => Number.isNaN(n))) return null
+  return { r: p[0], g: p[1], b: p[2], a: p[3] == null ? 1 : p[3] }
+}
+
+function colorClose(a, b, tol) {
+  const ca = parseRgba(a)
+  const cb = parseRgba(b)
+  if (!ca || !cb) return null // 未知格式：交由人工层判断，不算违规
+  return Math.abs(ca.r - cb.r) <= tol && Math.abs(ca.g - cb.g) <= tol && Math.abs(ca.b - cb.b) <= tol
+}
+
+/* ── 主流程 ─────────────────────────────────────────────────── */
+function main() {
+  const args = parseArgs(process.argv.slice(2))
+  const specPath = path.resolve(args.spec)
+  const schemaPath = path.resolve(args.schema)
+  if (!fs.existsSync(specPath)) { console.error(`spec.json 不存在: ${specPath}`); process.exit(1) }
+  if (!fs.existsSync(schemaPath)) { console.error(`schema.json 不存在: ${schemaPath}`); process.exit(1) }
+
+  const spec = JSON.parse(fs.readFileSync(specPath, 'utf8'))
+  const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'))
+  // 变量值表：dictionary 默认值 → mocks → data.json（后者是渲染真正吃的值）
+  const dataPath = args.data ? path.resolve(args.data) : path.join(path.dirname(schemaPath), 'data.json')
+  const values = {}
+  for (const p of schema.dictionary?.inputParams || []) if (p && p.key) values[p.key] = p.defaultValue
+  Object.assign(values, schema.dictionary?.mocks || {})
+  try {
+    if (fs.existsSync(dataPath)) Object.assign(values, JSON.parse(fs.readFileSync(dataPath, 'utf8')))
+  } catch {
+    /* data.json 坏了不阻断文本对齐检查 */
+  }
+  const cards = spec.cards || []
+  const card = cards[args.card - 1]
+  if (!card) { console.error(`卡片序号 ${args.card} 不存在（共 ${cards.length} 张卡）`); process.exit(1) }
+
+  const specTexts = collectSpecTexts(card)
+  const schemaTexts = []
+  collectSchemaTexts(schema.view || schema, schemaTexts)
+
+  const findings = []
+  let matched = 0
+
+  for (const st of specTexts) {
+    const stN = norm(st.text)
+    const hit = schemaTexts.find((s) => candidates(s, values).some((c) => c === stN || c.includes(stN) || stN.includes(c)))
+    if (!hit) {
+      findings.push({ type: 'missing-text', spec: st.text, detail: 'schema 中无对应 Text 节点（可能漏建）' })
+      continue
+    }
+    matched++
+    if (st.fontSize != null && hit.fontSize != null && Math.abs(st.fontSize - hit.fontSize) > args.fontTol) {
+      findings.push({
+        type: 'font-size',
+        spec: st.text,
+        specFontSize: st.fontSize,
+        schemaFontSize: hit.fontSize,
+        detail: `字号偏差 ${Math.abs(st.fontSize - hit.fontSize)} > 容差 ${args.fontTol}`,
+      })
+    }
+    const cc = colorClose(st.color, hit.color, args.colorTol)
+    if (cc === false) {
+      findings.push({
+        type: 'color',
+        spec: st.text,
+        specColor: st.color,
+        schemaColor: hit.color,
+        detail: `颜色通道差超过容差 ${args.colorTol}`,
+      })
+    }
+  }
+
+  const violations = findings.length
+  const report = {
+    spec: path.relative(process.cwd(), specPath),
+    schema: path.relative(process.cwd(), schemaPath),
+    card: args.card,
+    specTextCount: specTexts.length,
+    schemaTextCount: schemaTexts.length,
+    matched,
+    violations,
+    fontTol: args.fontTol,
+    colorTol: args.colorTol,
+    findings,
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(report, null, 2))
+  } else {
+    console.log(`spec 文本元素 ${specTexts.length} 个，schema Text 节点 ${schemaTexts.length} 个，匹配 ${matched} 个`)
+    if (!violations) {
+      console.log('[OK] 保真度对齐：文本覆盖完整，字号/颜色均在容差内。')
+    } else {
+      console.log(`\n发现 ${violations} 处保真度偏差：`)
+      for (const f of findings) {
+        console.log(`  [${f.type}] "${f.spec}" — ${f.detail}`)
+      }
+    }
+  }
+
+  process.exit(violations ? 1 : 0)
+}
+
+main()

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

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * check_magic_values.mjs — 魔法值门禁（L3，防回潮）
+ *
+ * 扫描 v3 生成器源码（spec_to_schema_v3.mjs），
+ * 找出 layout 魔法值（gap/padding/borderRadius/fontSize 裸数字）——按 L1 纪律，
+ * 这些值必须引用 lib/layout-tokens.mjs 的 TOKEN（T.gap/T.pad/T.radius/T.font/T.color）。
+ *
+ * 用法：
+ *   node scripts/check_magic_values.mjs            # 检查三个生成器
+ *   node scripts/check_magic_values.mjs --fix      # 列出允许豁免的例外（人工确认后改用 --exempt 行号）
+ *
+ * 退出码：0 = 无违规；70 = 发现魔法值（供 CI 识别）。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const TARGETS = ['spec_to_schema_v3.mjs']
+
+/** 需要 Token 化的样式键 → 允许的 Token 访问器 */
+const KEY_ACCESSOR = {
+  gap: 'T.gap',
+  padding: 'T.pad',
+  paddingTop: 'T.pad',
+  paddingBottom: 'T.pad',
+  paddingLeft: 'T.pad',
+  paddingRight: 'T.pad',
+  borderRadius: 'T.radius',
+  fontSize: 'T.font',
+}
+
+// 容器 opts 形式：gap: 8 / padding: '16 12' / radius: 12 / width: '100%'（仅数值型）
+const OPTS_RE = /(?:^|[\s,(])(gap|padding|paddingTop|paddingBottom|paddingLeft|paddingRight|borderRadius|fontSize|radius):\s*'?(\d[\d ]*)'?/g
+// setStyleChild 形式：setStyleChild(n, 'gap', '8') / setStyleChild(n, 'padding', '12')
+const SET_RE = /setStyleChild\([^)]*'(gap|padding|paddingTop|paddingBottom|paddingLeft|paddingRight|borderRadius|fontSize)',\s*'?(\d[\d ]*)'?/g
+
+function isExempt(line) {
+  const t = line.trim()
+  if (!t || t.startsWith('//') || t.startsWith('*') || t.startsWith('/*')) return true // 注释
+  if (/T\.(gap|pad|radius|font|color)\(/.test(line)) return true // 已 Token 化
+  if (/(String|Math\.(round|max|min|abs))\(/.test(line)) return true // 动态计算
+  if (/opts\.|pv\[|topGap|padM|bandGap|hGap|item\.|\.gap\b|\.padding\b/.test(line)) return true // 变量/参数传递
+  return false
+}
+
+let violations = 0
+for (const f of TARGETS) {
+  const p = path.join(__dirname, f)
+  if (!fs.existsSync(p)) continue
+  const lines = fs.readFileSync(p, 'utf8').split('\n')
+  lines.forEach((line, i) => {
+    if (isExempt(line)) return
+    const hits = []
+    for (const m of line.matchAll(OPTS_RE)) {
+      const [full, key, num] = m
+      if (num.trim() === '0') continue // 0 = 无间距/无内边距（语义「无」，非布局决策），与 SET_RE 路径豁免一致
+      if (key === 'radius' && num === '12') continue // whiteCard 统一 radius 由 T.radius('card') 表达
+      hits.push(`${key}=${num.trim()}`)
+    }
+    for (const m of line.matchAll(SET_RE)) {
+      const [full, key, num] = m
+      if (num.trim() === '0') continue // padding 0 = 无内边距（T.pad('root') 兜底，允许）
+      hits.push(`setStyleChild ${key}=${num.trim()}`)
+    }
+    if (hits.length) {
+      violations++
+      console.log(`[MAGIC] ${f}:${i + 1}  ${hits.join(' | ')}  →  ${line.trim().slice(0, 100)}`)
+    }
+  })
+}
+
+if (violations) {
+  console.log(`\n发现 ${violations} 处魔法值。L1 纪律：必须引用 lib/layout-tokens.mjs（T.gap/T.pad/T.radius/T.font/T.color）。`)
+  process.exit(70)
+} else {
+  console.log('[OK] v3 生成器无 layout 魔法值（全部 Token 化）。')
+}

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

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * crop_slices.mjs — 从聚焦截图（card-N.png）按矩形派生缺失切图。
+ *
+ * 背景：MeaXure 导出的切图集经常不全（整 tile 切图缺失、或同一张切图被标到内容不同的
+ * 多个位置）。spec_audit.mjs 会把这类缺口连同建议裁剪矩形一起报出来；本脚本负责把
+ * 缺口补成 src/slices/ 下的扁平切图（设计稿几倍图就产几倍图，渲染器按逻辑尺寸缩放）。
+ *
+ * 用法：
+ *   node crop_slices.mjs --design <card-N.png> --card-width 343 --out <slicesDir> \
+ *        --crop name@x,y,w,h [--crop ...]
+ *   node crop_slices.mjs --design <card-N.png> --card-width 343 --out <slicesDir> \
+ *        --from-audit <audit.json>          # 直接消费 spec_audit 的 missing[].crop
+ *
+ * 坐标为卡片本地 1x 坐标（与 spec_audit 输出一致）；缩放比 = design.png 宽 / card-width。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+const { PNG } = await import('pngjs')
+
+function parseArgs(argv) {
+  const out = { design: '', cardWidth: 0, out: '', crops: [], fromAudit: '' }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--design') out.design = argv[++i] || ''
+    else if (a === '--card-width') out.cardWidth = Number(argv[++i]) || 0
+    else if (a === '--out') out.out = argv[++i] || ''
+    else if (a === '--crop') out.crops.push(argv[++i] || '')
+    else if (a === '--from-audit') out.fromAudit = argv[++i] || ''
+    else if (a === '-h' || a === '--help') {
+      console.log('Usage: node crop_slices.mjs --design <png> --card-width <n> --out <dir> --crop name@x,y,w,h [...] | --from-audit <audit.json>')
+      process.exit(0)
+    }
+  }
+  if (!out.design || !out.out) {
+    console.error('缺少 --design 或 --out')
+    process.exit(1)
+  }
+  return out
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2))
+  const src = PNG.sync.read(fs.readFileSync(args.design))
+  const cardWidth = args.cardWidth || Math.round(src.width / 2)
+  const scale = src.width / cardWidth
+
+  const jobs = []
+  for (const c of args.crops) {
+    const at = c.indexOf('@')
+    if (at <= 0) throw new Error(`--crop 须为 name@x,y,w,h 形式: "${c}"`)
+    const [x, y, w, h] = c
+      .slice(at + 1)
+      .split(',')
+      .map((v) => Number(v))
+    if (![x, y, w, h].every((v) => Number.isFinite(v))) throw new Error(`--crop 坐标非法: "${c}"`)
+    jobs.push({ name: c.slice(0, at), x, y, w, h })
+  }
+  if (args.fromAudit) {
+    const audit = JSON.parse(fs.readFileSync(args.fromAudit, 'utf8'))
+    for (const m of audit.missing || []) {
+      for (const c of m.crops || [m.crop]) {
+        if (c) jobs.push({ name: c.name || m.name, x: c.x, y: c.y, w: c.w, h: c.h })
+      }
+    }
+  }
+  if (!jobs.length) {
+    console.log(JSON.stringify({ written: [] }))
+    return
+  }
+
+  fs.mkdirSync(args.out, { recursive: true })
+  const written = []
+  for (const j of jobs) {
+    const cx = Math.round(j.x * scale)
+    const cy = Math.round(j.y * scale)
+    const cw = Math.round(j.w * scale)
+    const ch = Math.round(j.h * scale)
+    if (cx < 0 || cy < 0 || cx + cw > src.width || cy + ch > src.height) {
+      throw new Error(`裁剪矩形越界: ${j.name} @${j.x},${j.y} ${j.w}x${j.h}（design ${src.width}x${src.height}, scale ${scale}）`)
+    }
+    const o = new PNG({ width: cw, height: ch })
+    for (let y = 0; y < ch; y++) {
+      for (let x = 0; x < cw; x++) {
+        const si = ((cy + y) * src.width + (cx + x)) * 4
+        const di = (y * cw + x) * 4
+        for (let k = 0; k < 4; k++) o.data[di + k] = src.data[si + k]
+      }
+    }
+    const file = path.join(args.out, path.extname(j.name) ? j.name : `${j.name}.png`)
+    fs.writeFileSync(file, PNG.sync.write(o))
+    written.push({ name: path.basename(file), px: [cw, ch], logical: [j.w, j.h] })
+  }
+  console.log(JSON.stringify({ scale, written }, null, 2))
+}
+
+main()