cardbuddy 0.25.0 → 0.26.0

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

@@ -0,0 +1,525 @@
+#!/usr/bin/env node
+/**
+ * adapt_schema.mjs — 卡片「适配环节」执行器：把旧有 / 已过时 / 错误的 schema 形态
+ * 一次性扫出来并做确定性修复，避免每张卡靠人肉踩坑。
+ *
+ * 与相邻工具的边界（别重复实现）：
+ *   - validate_schema.py   结构合法性能不能渲染（只报不改）
+ *   - autofix_schema.py    契约级机械修复：itemValueFrom / 重复 componentId /
+ *                          data.json 派生 / $item.xxx 作用域别名
+ *   - lint_card.mjs        体验规则（漏 click、缺 color、切图命名…）
+ *   - lint_autofix.mjs     体验 lint 的机械还债（带渲染像素守护）
+ *   - **adapt_schema.mjs（本脚本）**：跨版本 / 跨宿主的「语义迁移与错误形态归一」——
+ *                          重点是那些结构合法、lint 也不报，但在当前渲染契约或
+ *                          发布链路上会出错的历史写法。
+ *
+ * 规则表见 references/schema_adaptation.md（每条规则的事故来源、判定、修复、依据）。
+ *
+ * 用法：
+ *   node scripts/adapt_schema.mjs --id <卡id>            # 只报告（默认）
+ *   node scripts/adapt_schema.mjs --id <卡id> --write    # 落盘可确定性修复项
+ *   node scripts/adapt_schema.mjs --all                  # 全量库存巡检
+ *   node scripts/adapt_schema.mjs --all --json           # 机器可读（接 CI / card-doctor）
+ *   node scripts/adapt_schema.mjs --list-rules           # 打印规则表
+ *
+ * 退出码：0 = 无 error（或 --write 后清零）；1 = 存在未修复 error；2 = 用法/路径错误。
+ * 设计约定：**不臆造语义**——需要人判断的（未声明变量取什么值、死节点该删还是该显）
+ * 只报告，不自动改；只有「改法唯一且等价保持」的才进 --write。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+// ---------- CLI ----------
+const argv = process.argv.slice(2)
+const argOf = (name) => {
+  const i = argv.indexOf(name)
+  return i >= 0 ? argv[i + 1] : undefined
+}
+const hasFlag = (name) => argv.includes(name)
+
+if (hasFlag('--help') || hasFlag('-h')) {
+  console.error(
+    'Usage: node scripts/adapt_schema.mjs (--id <cardId> | --all) [--write] [--json] [--project-root <dir>]\n' +
+      '       node scripts/adapt_schema.mjs --list-rules'
+  )
+  process.exit(2)
+}
+
+const projectRootArg = argOf('--project-root')
+if (projectRootArg) process.env.DSL_CARD_PROJECT_ROOT = path.resolve(projectRootArg)
+
+const { cardsDir, cardSchemaPath, readJson } = await import('./lib/paths.mjs')
+
+const targetId = argOf('--id')
+const runAll = hasFlag('--all')
+const writeMode = hasFlag('--write')
+const asJson = hasFlag('--json')
+
+// ---------- 规则表 ----------
+/** 布局容器：这些组件的 display 由样式类决定（.ce_row / .ce_column = flex） */
+const LAYOUT_CLASSES = new Set([
+  'Root',
+  'Row',
+  'Column',
+  'SingleColumn',
+  'MultiColumn',
+  'GridLayout',
+  'ListLayout',
+  'AbsoluteLayout',
+])
+
+/** 表达式内建变量（运行时注入，无需 inputParams 声明） */
+const BUILTIN_VARS = new Set(['_index', 'item', 'root', 'self'])
+
+/**
+ * 规则表：id → 元信息。detect/fix 在同文件下方按 id 分派。
+ * level: error（会让卡出错）/ warn（有风险或体验问题）
+ * fix: 'auto'（--write 落盘）/ 'manual'（只报告，需语义判断）/ 'nolocal'（schema 无可修点）
+ */
+const RULES = {
+  'AD-01': {
+    title: '未声明变量引用（需人工确认）',
+    level: 'warn',
+    fix: 'manual',
+    why: '表达式引用了 inputParams 未声明的变量，运行时求值抛错或恒 undefined（实例：creditCardBill column_cj 的 $listData1/$listData2，从别卡复制残留）',
+  },
+  'AD-02': {
+    title: '越界 $_index',
+    level: 'error',
+    fix: 'manual',
+    why: '$_index 只在列表项作用域（slotScope）内有定义；作用域外用会求值成 undefined，条件恒 false（实例：creditCardBill divider_7l/divider_ep 两个从未渲染过的死节点）',
+  },
+  'AD-03': {
+    title: '布局容器上的条件显隐（发布产物 display 风险）',
+    level: 'warn',
+    fix: 'nolocal',
+    why: 'v-show 在发布时由平台编译成内联 display: (expr) ? \'block\' : \'none\'；可见侧写死 block 会压掉布局元素的样式类 display:flex（实例：creditCardBill row_f1/row_77 在 H5 变 block）。schema 侧无 display 可改，需宿主渲染层兜底',
+  },
+  'AD-04': {
+    title: 'style 里写死 display',
+    level: 'error',
+    fix: 'auto',
+    why: 'display 只应由 v-show 指令产生；写进 style 会被当成未知样式键静默丢弃（validate 报 ERROR），或在旧渲染器里压掉样式类',
+  },
+  'AD-05': {
+    title: 'v-show 条件为空',
+    level: 'error',
+    fix: 'auto',
+    why: 'showType=01/02 却没有 condition.expression：编译出的 display 表达式无意义，节点显隐不可控（降级为 showType=00 等价于「无显隐控制」）',
+  },
+  'AD-06': {
+    title: '旧作用域别名 $item',
+    level: 'warn',
+    fix: 'manual',
+    why: '运行时插槽作用域没有 item 这个键（是 $$），$item.xxx 恒 undefined；用 autofix_schema.py 规则 5 归一为扁平字段名',
+  },
+}
+
+if (hasFlag('--list-rules')) {
+  for (const [id, r] of Object.entries(RULES)) {
+    console.log(`${id}  [${r.level}/${r.fix}]  ${r.title}\n      ${r.why}`)
+  }
+  // 规则表输出量小，直接退出；后面的 usage 检查不该再跑
+  process.exit(0)
+}
+
+if (!targetId && !runAll) {
+  console.error('Usage: node scripts/adapt_schema.mjs (--id <cardId> | --all) [--write] [--json]')
+  process.exit(2)
+}
+
+// ---------- 变量与文本采集 ----------
+
+/** 收集 inputParams 树里声明的全部 key（含 children 嵌套） */
+function collectDeclared(inputParams) {
+  const keys = new Set()
+  const walk = (items) => {
+    for (const p of items || []) {
+      if (p && p.key) keys.add(p.key)
+      walk(p && p.children)
+    }
+  }
+  walk(inputParams)
+  return keys
+}
+
+/** 从一段表达式文本里取出 $var 名（排除 $$ 内建与非 ASCII 标识符） */
+function varsIn(text) {
+  const out = []
+  const re = /(?<!\$)\$([A-Za-z_][A-Za-z0-9_]*)/g
+  let m
+  while ((m = re.exec(text)) !== null) out.push(m[1])
+  return out
+}
+
+/**
+ * 节点上所有「会被运行时求值」的字符串，附带出处标签。
+ * 只取表达式/绑定，不取 itemDefaultValue（那是数据不是表达式）。
+ */
+function expressionTexts(node) {
+  const out = []
+
+  for (const p of node.properties || []) {
+    if (p && typeof p.itemValue === 'string' && p.itemValue.trim()) {
+      out.push({ where: `property.${p.itemKey}`, text: p.itemValue })
+    }
+  }
+
+  for (const group of (node.style && node.style.properties) || []) {
+    for (const p of (group.itemChildren && group.itemChildren.properties) || []) {
+      if (p && typeof p.itemValue === 'string' && p.itemValue.trim()) {
+        out.push({ where: `style.${group.itemKey}.${p.itemKey}`, text: p.itemValue })
+      }
+    }
+  }
+
+  for (const d of node.directives || []) {
+    for (const p of (d.itemChildren && d.itemChildren.properties) || []) {
+      const v = p && p.itemValue
+      if (typeof v === 'string' && v.trim()) {
+        out.push({ where: `directive.${d.itemKey}.${p.itemKey}`, text: v })
+      } else if (v && typeof v === 'object' && typeof v.expression === 'string' && v.expression.trim()) {
+        out.push({ where: `directive.${d.itemKey}.${p.itemKey}.expression`, text: v.expression })
+      }
+    }
+  }
+
+  for (const ea of node.eventactions || []) {
+    const action = (ea && ea.action) || {}
+    for (const p of action.properties || []) {
+      // 事件代码是 itemValue.{code, compiled} 对象，不是字符串（早期按字符串取会静默漏检）
+      const iv = p && p.itemValue
+      const code = iv && typeof iv === 'object' ? iv.code : typeof iv === 'string' ? iv : ''
+      if (typeof code === 'string' && code.includes('$')) {
+        out.push({ where: 'eventaction.code', text: code, isCode: true })
+      }
+    }
+  }
+
+  return out
+}
+
+/** 取节点 v-show 指令的 { showType, condition, expression } */
+function readVShow(node) {
+  for (const d of node.directives || []) {
+    if (!d || d.itemKey !== 'v-show') continue
+    const props = (d.itemChildren && d.itemChildren.properties) || []
+    const get = (k) => props.find((p) => p && p.itemKey === k)
+    const showType = (get('showType') || {}).itemValue
+    const condItem = get('condition')
+    const condition = condItem && condItem.itemValue
+    const expression =
+      condition && typeof condition === 'object' ? condition.expression : typeof condition === 'string' ? condition : ''
+    return { directive: d, showType, condition, expression: expression || '' }
+  }
+  return null
+}
+
+/**
+ * 收集运行时动态写入的 state 字段名。
+ *
+ * 卡片事件代码里常见两类写入（实测：monthlyBill 的 renderListData、
+ * creditCardAmortiztionLoan 的 hideButton），这些字段不需要也不应该在
+ * inputParams 声明，AD-01 必须放行，否则每张带计算字段的卡都会误报。
+ *
+ *   this.setData({ renderListData: renderList })
+ *   this.state.hideButton = false
+ */
+function collectDynamicKeys(schema) {
+  const keys = new Set()
+  const walk = (node) => {
+    if (!node || typeof node !== 'object') return
+    for (const ea of node.eventactions || []) {
+      for (const p of ((ea && ea.action) || {}).properties || []) {
+        const iv = p && p.itemValue
+        const code = iv && typeof iv === 'object' ? iv.code : typeof iv === 'string' ? iv : ''
+        if (typeof code !== 'string' || !code) continue
+        let m
+        const reSetData = /setData\s*\(\s*\{([\s\S]*?)\}\s*\)/g
+        while ((m = reSetData.exec(code)) !== null) {
+          const reKey = /([A-Za-z_$][\w$]*)\s*:/g
+          let k
+          while ((k = reKey.exec(m[1])) !== null) keys.add(k[1])
+        }
+        const reState = /\.state\.([A-Za-z_$][\w$]*)\s*=/g
+        while ((m = reState.exec(code)) !== null) keys.add(m[1])
+      }
+    }
+    for (const slot of node.slots || []) for (const c of (slot && slot.components) || []) walk(c)
+    for (const c of node.components || []) walk(c)
+  }
+  walk(schema.view)
+  return keys
+}
+
+/** 深度遍历组件树，回调 (node, inListScope) */
+function walkTree(node, inListScope, visit) {
+  if (!node || typeof node !== 'object') return
+  if (node.componentId) visit(node, inListScope)
+  for (const slot of node.slots || []) {
+    const childScope = inListScope || Boolean(slot && slot.slotScope)
+    for (const c of (slot && slot.components) || []) walkTree(c, childScope, visit)
+  }
+  for (const c of node.components || []) walkTree(c, inListScope, visit)
+}
+
+// ---------- 检测 ----------
+function analyzeCard(id) {
+  const schemaPath = cardSchemaPath(id)
+  const schema = readJson(schemaPath, null)
+  if (!schema) return { id, ok: false, reason: 'schema.json 不存在或无法解析', findings: [] }
+
+  const declared = collectDeclared((schema.dictionary || {}).inputParams)
+  const dynamicKeys = collectDynamicKeys(schema)
+  const findings = []
+  const push = (rule, node, extra) =>
+    findings.push({
+      card: id,
+      rule,
+      level: RULES[rule].level,
+      fix: RULES[rule].fix,
+      nodeId: node.componentId,
+      className: node.className || '',
+      ...extra,
+    })
+
+  walkTree(schema.view, false, (node, inListScope) => {
+    const cn = node.className || ''
+
+    // AD-01 未声明变量（列表作用域内豁免：那里的自由变量就是 item 字段）
+    if (!inListScope) {
+      const seen = new Set()
+      for (const { where, text, isCode } of expressionTexts(node)) {
+        for (const v of varsIn(text)) {
+          if (BUILTIN_VARS.has(v) || declared.has(v) || seen.has(v)) continue
+          seen.add(v)
+          const dynamic = dynamicKeys.has(v)
+          push('AD-01', node, {
+            where,
+            detail: dynamic
+              ? `$${v} 未在 inputParams 声明，但事件代码里有运行时写入（动态 state 字段）——确认注入时机早于首次渲染`
+              : `$${v} 未在 inputParams 声明，也无运行时写入痕迹——可能是从别卡复制的残留，或外部 dataResponse 直传字段`,
+            evidence: text.replace(/\s+/g, ' ').slice(0, 90),
+            // 未声明变量一律 warn：外部 dataResponse 直传字段是合法用法，
+            // 机器无法与「复制残留」确定区分，交人工按 detail 判定
+            level: 'warn',
+          })
+        }
+      }
+    }
+
+    // AD-02 越界 $_index
+    if (!inListScope) {
+      for (const { where, text } of expressionTexts(node)) {
+        if (text.includes('$_index')) {
+          push('AD-02', node, {
+            where,
+            detail: '$_index 在列表项作用域外求值为 undefined，条件恒 false',
+            evidence: text.replace(/\s+/g, ' ').slice(0, 90),
+          })
+          break
+        }
+      }
+    }
+
+    // AD-03 布局容器 + 条件显隐 → 发布产物 display 风险
+    const vs = readVShow(node)
+    if (vs && (vs.showType === '01' || vs.showType === '02') && LAYOUT_CLASSES.has(cn)) {
+      push('AD-03', node, {
+        where: `directive.v-show.showType=${vs.showType}`,
+        detail: `布局容器 ${cn} 的条件显隐：发布产物可见侧写死 display:'block'，会压掉 .ce_* 的 flex`,
+        evidence: vs.expression.replace(/\s+/g, ' ').slice(0, 90),
+        fixHint: 'schema 无可修点；宿主需安装 display 补丁（ai-assistant-h5 src/flame/cardStylePatch.js），或改用非布局容器包裹',
+      })
+    }
+
+    // AD-04 style 里写死 display
+    for (const group of (node.style && node.style.properties) || []) {
+      for (const p of (group.itemChildren && group.itemChildren.properties) || []) {
+        if (p && p.itemKey === 'display') {
+          push('AD-04', node, {
+            where: `style.${group.itemKey}.display`,
+            detail: 'style 不应出现 display（只由 v-show 指令产生）',
+            evidence: JSON.stringify(p.itemValue).slice(0, 60),
+          })
+        }
+      }
+    }
+
+    // AD-05 v-show 条件为空
+    if (vs && (vs.showType === '01' || vs.showType === '02') && !vs.expression.trim()) {
+      push('AD-05', node, {
+        where: 'directive.v-show.condition',
+        detail: `showType=${vs.showType} 但 condition.expression 为空`,
+        evidence: JSON.stringify(vs.condition).slice(0, 80),
+      })
+    }
+
+    // AD-06 旧作用域别名 $item（排除 $$ 与已声明同名变量）
+    if (!declared.has('item')) {
+      for (const { where, text } of expressionTexts(node)) {
+        if (/\$item\s*\./.test(text) || /(^|[^\w$])\$item(?![\w])/.test(text)) {
+          push('AD-06', node, {
+            where,
+            detail: '$item 不是运行时作用域键（应为 $$ 或扁平字段名）',
+            evidence: text.replace(/\s+/g, ' ').slice(0, 90),
+          })
+          break
+        }
+      }
+    }
+  })
+
+  return { id, ok: true, schemaPath, schema, findings }
+}
+
+// ---------- 修复（只处理 fix==='auto' 的规则） ----------
+function applyFixes(result) {
+  const { schema } = result
+  let changed = 0
+  const fixed = []
+
+  walkTree(schema.view, false, (node) => {
+    // AD-04：删掉 style 里 display 子项
+    for (const group of (node.style && node.style.properties) || []) {
+      const props = (group.itemChildren && group.itemChildren.properties) || []
+      const next = props.filter((p) => !(p && p.itemKey === 'display'))
+      if (next.length !== props.length) {
+        group.itemChildren.properties = next
+        changed += next.length !== props.length ? 1 : 0
+        fixed.push({ rule: 'AD-04', nodeId: node.componentId, className: node.className })
+      }
+    }
+
+    // AD-05：showType 01/02 且条件为空 → 降级 00（等价于无显隐控制）
+    const vs = readVShow(node)
+    if (vs && (vs.showType === '01' || vs.showType === '02') && !vs.expression.trim()) {
+      const props = (vs.directive.itemChildren && vs.directive.itemChildren.properties) || []
+      const st = props.find((p) => p && p.itemKey === 'showType')
+      if (st) {
+        st.itemValue = '00'
+        changed += 1
+        fixed.push({ rule: 'AD-05', nodeId: node.componentId, className: node.className })
+      }
+    }
+  })
+
+  if (changed) fs.writeFileSync(result.schemaPath, JSON.stringify(schema, null, 2) + '\n')
+  return { changed, fixed }
+}
+
+// ---------- 输出 ----------
+const GROUP_ORDER = Object.keys(RULES)
+
+function printHuman(results, fixSummary) {
+  let errorCount = 0
+  let warnCount = 0
+  const byRule = new Map()
+
+  for (const r of results) {
+    if (!r.ok) {
+      console.error(`✗ ${r.id}: ${r.reason}`)
+      continue
+    }
+    for (const f of r.findings) {
+      const level = f.level || RULES[f.rule].level
+      if (level === 'error') errorCount += 1
+      else warnCount += 1
+      if (!byRule.has(f.rule)) byRule.set(f.rule, [])
+      byRule.get(f.rule).push(f)
+    }
+  }
+
+  for (const rule of GROUP_ORDER) {
+    const list = byRule.get(rule)
+    if (!list || !list.length) continue
+    const meta = RULES[rule]
+    console.log(`\n[${rule}] ${meta.title}  (${list.length} 处, ${meta.level}/${meta.fix})`)
+    const capped = list.slice(0, 12)
+    for (const f of capped) {
+      const loc = f.where ? ` ${f.where}` : ''
+      console.log(`  - ${f.card}${f.nodeId ? '/' + f.nodeId : ''} (${f.className})${loc}`)
+      if (f.evidence) console.log(`      ${f.evidence}`)
+      if (f.detail) console.log(`      → ${f.detail}`)
+      if (f.fixHint) console.log(`      ↳ ${f.fixHint}`)
+    }
+    if (list.length > capped.length) console.log(`  … 其余 ${list.length - capped.length} 处同类，见 --json`)
+  }
+
+  if (fixSummary && fixSummary.changed) {
+    console.log(`\n已落盘修复 ${fixSummary.changed} 处：`)
+    for (const f of fixSummary.fixed) console.log(`  ✓ [${f.rule}] ${f.card || ''}${f.nodeId ? '/' + f.nodeId : ''}`)
+  }
+
+  const autoFixable = results.flatMap((r) => r.findings || []).filter((f) => RULES[f.rule].fix === 'auto').length
+  console.log(`\n汇总：error ${errorCount} / warn ${warnCount}${autoFixable ? ` / 可自动修复 ${autoFixable}（加 --write）` : ''}`)
+
+  const tips = []
+  if (results.some((r) => (r.findings || []).some((f) => f.rule === 'AD-06')))
+    tips.push('AD-06 → python3 scripts/autofix_schema.py <schema> 归一 $item 别名')
+  if (results.some((r) => (r.findings || []).some((f) => f.rule === 'AD-01')))
+    tips.push('AD-01 → 补 inputParams 声明，或确认该表达式是否从别卡复制残留（需人工判定语义）')
+  if (results.some((r) => (r.findings || []).some((f) => f.rule === 'AD-03')))
+    tips.push('AD-03 → schema 无可修点，属发布链路问题：确认目标宿主已安装 display 补丁')
+  if (tips.length) {
+    console.log('\n下一步：')
+    for (const t of tips) console.log('  · ' + t)
+  }
+
+  return { errorCount, warnCount }
+}
+
+// ---------- main ----------
+let ids = []
+if (runAll) {
+  ids = fs
+    .readdirSync(cardsDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && fs.existsSync(path.join(cardsDir, d.name, 'schema.json')))
+    .map((d) => d.name)
+    .sort()
+} else {
+  ids = [targetId]
+}
+
+const results = ids.map((id) => {
+  try {
+    return analyzeCard(id)
+  } catch (e) {
+    return { id, ok: false, reason: e.message, findings: [] }
+  }
+})
+
+let fixSummary = { changed: 0, fixed: [] }
+if (writeMode) {
+  for (const r of results) {
+    if (!r.ok) continue
+    if (!r.findings.some((f) => RULES[f.rule].fix === 'auto')) continue
+    const { changed, fixed } = applyFixes(r)
+    fixSummary.changed += changed
+    fixSummary.fixed.push(...fixed.map((x) => ({ ...x, card: r.id })))
+    // 修完重新检测，保证报告与落盘后状态一致（幂等）
+    r.findings = analyzeCard(r.id).findings
+  }
+}
+
+if (asJson) {
+  const flat = results.flatMap((r) => (r.findings || []).map((f) => ({ ...f, level: f.level || RULES[f.rule].level })))
+  console.log(
+    JSON.stringify(
+      {
+        ok: !flat.some((f) => f.level === 'error'),
+        cards: results.filter((r) => r.ok).length,
+        findings: flat,
+        fixed: fixSummary.fixed,
+        rules: Object.fromEntries(Object.entries(RULES).map(([k, v]) => [k, { title: v.title, level: v.level, fix: v.fix }])),
+      },
+      null,
+      2
+    )
+  )
+  // 用 exitCode 而非 exit：大 JSON 走管道时 process.exit 会截断未 flush 的 stdout
+  process.exitCode = flat.some((f) => f.level === 'error') ? 1 : 0
+} else {
+  const { errorCount } = printHuman(results, fixSummary)
+  process.exitCode = errorCount > 0 ? 1 : 0
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cardbuddy",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Local dev service for the CardBuddy card editor — decouples card CRUD (sync/save/validate/render-status/screenshot) from the static public editor, so the editor can be deployed to any static host while each developer runs a local service against their own card source.",
   "type": "module",
   "bin": {