cardbuddy 0.14.3 → 0.16.0

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

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 /**
- * preflight.mjs — 生成前/后一键机械检查（替代 AI 手动过 Pre-flight Checklist）。
+ * preflight.mjs — 生成前/后一键机械检查（把 AI 需手动过的机械项一次性跑完）。
  *
- * 检查项（对应 quickref.md Pre-flight Checklist 12 条中可机械化的 10 条）：
+ * 检查项（共 14 项；语义清单见 SKILL.md §8 Workflow A 步骤 4）：
  *   1. 元素清单：spec text/slice/shape 数 vs schema 节点数（R29）
  *   2. 组件白名单：className ∈ component-meta.json（R28）
- *   3. Image itemValueFrom：静态路径必须 "2"，变量 "1"（R25）
+ *   3. Image itemValueFrom：静态路径必须 "2"，变量 "1"（双向都拦：`"0"` 常量放路径、
+ *      `"1"` 变量放非 `$` 值、`"2"` 图片槽放 `$` 表达式——末者会被原样透传成 url($icon)）（R25）
  *   4. Image rect.height：必须有显式高度（R32，否则被 aspect-ratio:16/9 压缩）
  *   5. 切图文件名：含空格/特殊字符必须重命名（R31）
  *   6. Icon eventaction：嵌套格式 event.eventKey（R30）
@@ -13,6 +14,12 @@
  *   8. 分割线用 Divider：禁止 Row 模拟分割线（R28）
  *   9. 卡片根样式全量提取：bg shape 有 border 但 schema 根容器未设（R33）
  *  10. 空样式 itemId：style 子项 itemId 为空串 → 运行时静默丢弃
+ *  11. 切图引用含 URL 保留字符（`# ? % & +`）→ 浏览器截断请求、图片静默不显示（R31b）
+ *  12. 横向流父容器里的容器子节点未写 rect.width + flexShrink:0 → 默认 100% 吃掉整行（R22b）
+ *  13. 切图引用在 src/slices 里没有对应文件 → 渲染 404、图空白零报错（R31c）
+ *  14. 组件契约：属性键 / 样式组 / 样式子键必须在 component-meta.json + style-meta.json 白名单内（R28b）
+ *      —— 不存在的键被运行时**整条静默丢弃**（Image 键写错 ⇒ 破图），历史四道闸全放行。
+ *      —— 11/12/13 与 lint_card.mjs 共用 lib/layout_rules.mjs 与 lib/slice_dedupe.mjs；14 共用 lib/component_contract.mjs，避免双写漂移。
  *
  * 用法：
  *   node preflight.mjs --spec UI/<画板>/spec.json --id <卡id>
@@ -24,6 +31,11 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { metaDir, cardsDir, slicesDir } from './lib/paths.mjs'
+import { buildSliceFileIndex, collectSliceRefStrings, findUrlReservedChars, isRemoteSliceRef, resolveSliceRefOnDisk, sliceNameFromRef } from './lib/slice_dedupe.mjs'
+import { collectRowChildNoWidth } from './lib/layout_rules.mjs'
+import { loadContract, collectContractViolations, describeViolation } from './lib/component_contract.mjs'
+import { collectImageValueFrom, collectImageNoHeight } from './lib/rules/image.mjs'
+import { collectExprNoMathRound } from './lib/rules/expr.mjs'
 
 /* ── args ── */
 const args = {}
@@ -53,10 +65,12 @@ if (!schema) {
 const spec = args.spec ? loadJSONSafe(args.spec) : null
 const specCards = spec?.cards || []
 
-/* ── Load meta ── */
-const CM = loadJSONSafe(path.join(metaDir, 'component-meta.json'))
-const SM = loadJSONSafe(path.join(metaDir, 'style-meta.json'))
-const knownClasses = new Set(Object.keys(CM?.components || {}))
+/* ── Load meta ──
+ * 组件/样式白名单唯一来源：lib/component_contract.mjs（内部编译 component-meta.json + style-meta.json）。
+ * 原先这里自建 `new Set(Object.keys(CM.components))`，与 lint 侧经 loadContract 得到的
+ * `contract.classes` **并不相等**——后者含内置类 `Root`（CM 里没有），且元数据读不到时
+ * 前者会把全部组件报成「不在白名单」。统一到一处，消除这条口径差。 */
+const contract = loadContract({ metaDir })
 
 /* ── helpers ── */
 function getStyleChild(node, groupKey, childKey) {
@@ -106,33 +120,28 @@ if (specCards.length > 0) {
   }
 }
 
-/* ══ Check 2: Component whitelist (R28) ══ */
-for (const n of allNodes) {
-  if (n.className && !knownClasses.has(n.className)) {
-    check('r28-unknown-class', 'error', `${n.className} "${n.componentId}" 不在 component-meta.json 中 → 渲染空白（R28）`)
+/* ══ Check 2: Component whitelist (R28) ══
+ * 白名单 = contract.classes（component-meta.json 的 components 键 ∪ 内置类 Root）。
+ * 元数据读不到时**不报**——满屏「不在白名单」只会淹没真正的问题（与 lint 同口径）。 */
+if (contract.loaded.components) {
+  for (const n of allNodes) {
+    if (n.className && !contract.classes.has(n.className)) {
+      check('r28-unknown-class', 'error', `${n.className} "${n.componentId}" 不在 component-meta.json 中 → 渲染空白（R28）`)
+    }
   }
 }
 
-/* ══ Check 3: Image itemValueFrom (R25) ══ */
-for (const n of allNodes.filter(n => n.className === 'Image')) {
-  const valProp = getProp(n, 'value')
-  if (!valProp) continue
-  const from = String(valProp.itemValueFrom || '')
-  const val = String(valProp.itemValue || '')
-  if (from === '0' && !val.startsWith('$')) {
-    check('r25-image-from-0', 'error', `Image "${n.componentId}" itemValueFrom="0"(常量) 但值是路径 → 渲染器不走图片逻辑，空白（R25）。静态路径用 "2"`)
-  }
-  if (from === '1' && !val.startsWith('$')) {
-    check('r25-image-from-1', 'error', `Image "${n.componentId}" itemValueFrom="1"(变量) 但值不以 $ 开头 → 表达式求值失败，空白（R25）`)
-  }
+/* ══ Check 3: Image itemValueFrom (R25) ══
+ * 判定与文案共享 lib/rules/image.mjs（与 lint_card.mjs 同一实现）。
+ * reportMissingProp=true —— 键名写错（如 itemKey:"image"）会让本项与 Check 5 **双双短路跳过**，
+ * 四道闸全绿而图片死掉，故缺失 value 本身必须是 ERROR。 */
+for (const f of collectImageValueFrom(schema.view, { reportMissingProp: true })) {
+  check(f.code, f.severity, f.message, f.detail)
 }
 
-/* ══ Check 4: Image rect.height (R32) ══ */
-for (const n of allNodes.filter(n => n.className === 'Image')) {
-  const h = getStyleChild(n, 'rect', 'height')
-  if (!h || !String(h.itemValue).trim()) {
-    check('r32-image-no-height', 'error', `Image "${n.componentId}" 缺 rect.height → CSS aspect-ratio:16/9 会压缩图片高度（R32）。设显式高度`)
-  }
+/* ══ Check 4: Image rect.height (R32) ══（共享 lib/rules/image.mjs） */
+for (const f of collectImageNoHeight(schema.view)) {
+  check(f.code, f.severity, f.message, f.detail)
 }
 
 /* ══ Check 5: Slice filename spaces (R31) ══ */
@@ -155,21 +164,10 @@ for (const n of allNodes.filter(n => n.className === 'Icon')) {
   }
 }
 
-/* ══ Check 7: Percentage expression Math.round (R23) ══ */
-function walkExprs(node) {
-  const props = [...(node.properties || [])]
-  for (const sp of node.style?.properties || []) {
-    for (const c of sp.itemChildren?.properties || []) props.push(c)
-  }
-  for (const p of props) {
-    if (String(p.itemValueFrom) === '1' && typeof p.itemValue === 'string') {
-      if (/\*\s*100/.test(p.itemValue) && !/Math\.round/.test(p.itemValue)) {
-        check('r23-no-math-round', 'error', `"${node.componentId}" 表达式含 *100 但无 Math.round → JS 浮点精度问题（R23）: ${p.itemValue.slice(0, 50)}`)
-      }
-    }
-  }
+/* ══ Check 7: Percentage expression Math.round (R23) ══（共享 lib/rules/expr.mjs） */
+for (const f of collectExprNoMathRound(schema.view)) {
+  check(f.code, f.severity, f.message, f.detail)
 }
-for (const n of allNodes) walkExprs(n)
 
 /* ══ Check 8: Divider for separators (R28) ══ */
 // Heuristic: Row with height ≤2 and background color but no children = likely a divider
@@ -227,6 +225,52 @@ for (const n of allNodes) {
   }
 }
 
+/* ══ Check 11: Slice refs with URL reserved chars (R31b) ══
+ * `#` 之后被当 fragment，浏览器根本不发这部分（实测 /slices/警示-#999.png → 请求 /slices/警示-）。
+ * 未命中时静态中间件返回 HTML 兜底（旧行为 200）⇒ 图空白、网络面板 200、零报错。 */
+for (const ref of collectSliceRefStrings(schema)) {
+  const hit = findUrlReservedChars(sliceNameFromRef(ref))
+  if (hit) {
+    check('r31b-slice-url-reserved-char', 'error', `切图引用含 URL 保留字符 ${hit.map((c) => `"${c}"`).join(' ')}: "${ref}" → 浏览器会截断请求，图片静默不显示（R31b）。重命名切图为纯 ASCII 名并同步改写引用`)
+  }
+}
+
+/* ══ Check 12: Row-child container without rect.width + flexShrink:0 (R22b) ══ */
+for (const hit of collectRowChildNoWidth(schema.view)) {
+  check('r22b-row-child-container-no-width', 'error', hit.message, `${hit.className} ${hit.componentId} ← ${hit.parentClass} ${hit.parentId}（${hit.siblingCount} 个并列子节点）`)
+}
+
+/* ══ Check 13: Slice ref target missing on disk (R31c) ══
+ * 审计给了正确的名字、但文件还在 bundle 里没落进 src/slices ⇒ 引用 404、图空白、零报错。
+ * 这一条把「引用名 ↔ 磁盘名同源」变成每轮迭代都能看到的硬约束。 */
+{
+  const sliceIndex = buildSliceFileIndex(slicesDir)
+  for (const ref of collectSliceRefStrings(schema)) {
+    if (isRemoteSliceRef(ref)) continue
+    const { resolved, name } = resolveSliceRefOnDisk(sliceIndex, ref)
+    if (resolved) continue
+    check(
+      'r31c-slice-ref-missing-file',
+      'error',
+      `切图引用 "${ref}" 在 src/slices 里不存在（期望文件名 ${name}）→ 渲染时 404，图片位置一片空白且控制台不报错（R31c）。把切图按引用名落盘（crop_slices.mjs --from-audit 会收养审计判定存在的资产），或把引用改成磁盘上真实存在的文件名 —— 两者必须同源`,
+    )
+  }
+}
+
+/* ══ Check 14: Component contract — 属性键 / 样式组 / 样式子键白名单 ══
+ * 2026-09-24 事故：模型给 Image 写 itemKey:"image"（合法键只有 "value"），
+ * 运行时按 itemKey 绑定、不存在的键被整条静默丢弃 ⇒ value 为空、图片渲染成破图；
+ * 而 validate / lint / preflight / elements.missing **全部放行**。
+ * 全仓 82 处 Image 有 81 处写 value，唯一写 image 的正是这张卡 ⇒ 必须机械兜底。
+ * 白名单唯一来源 card-editor/meta/component-meta.json（经 lib/component_contract.mjs 编译）。 */
+{
+  for (const v of collectContractViolations(schema, contract)) {
+    // unknown-class 由 Check 2 报（r28-unknown-class），此处只报属性键 / 样式组 / 样式子键
+    if (v.code === 'unknown-class') continue
+    check(`r28b-${v.code}`, v.severity, describeViolation(v), v.where ? `节点路径 ${v.where}` : '')
+  }
+}
+
 /* ── Output ── */
 const errors = results.filter(r => r.severity === 'error')
 const warns = results.filter(r => r.severity === 'warn')