cardbuddy 0.11.0 → 0.12.1

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

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+/**
+ * slices_normalize.mjs — 存量切图归一化：语义化改名 + 同内容去重 + 引用/manifest 成套改写。
+ *
+ * 背景（slices_convention.md §1.1 / §3.1）：历史切图沿用设计稿图层名 / 导出目录前缀 / 中文名落地，
+ * 同一张图还常以多个名字并存。本脚本把「改名要成套做」机械化：
+ *   ① 文件名（src/slices/）② 所有卡片 schema/data 里的 `/slices/<name>` 引用（原样文本替换，保留格式）
+ *   ③ src/slices/manifest.json（改名保留 url/sha 记 renamedFrom；合并副本记 mergedInto）
+ *   ④ 若被合并副本已上传过（manifest 有 url）而保留名没有 → 把卡片里的 `@filestore` 引用改写到保留名的 url
+ *
+ * 默认 **dry-run 只出报告**，加 `--write` 才落盘。判重唯一权威判据 = 内容 sha256（lib/slice_dedupe.mjs）。
+ *
+ * 用法：
+ *   node slices_normalize.mjs                          # 报告：改名计划 / 重复组 / 悬空引用 / 剪枝候选
+ *   node slices_normalize.mjs --write                  # 应用内置存量改名映射（LEGACY_RENAMES）
+ *   node slices_normalize.mjs --rename '编组 4.png=iconArrowRightOrange.png' --write
+ *   node slices_normalize.mjs --map renames.json --write
+ *   node slices_normalize.mjs --dedupe --write         # 额外把 sha256 相同的副本并进语义名
+ *   node slices_normalize.mjs --prune-unreferenced --write   # 删除无引用且未上传的孤儿切图（谨慎）
+ *   node slices_normalize.mjs --no-legacy              # 不用内置映射，只用 --rename/--map/--dedupe
+ *   node slices_normalize.mjs --json                   # 机器可读输出
+ *
+ * 退出码：0=正常 / 2=改名冲突或参数错误。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { buildContentIndex, checkSliceName, sha256File } from './lib/slice_dedupe.mjs'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const REPO_ROOT = path.resolve(HERE, '../../..')
+const SLICES_DIR = path.join(REPO_ROOT, 'src/slices')
+const CARDS_DIR = path.join(REPO_ROOT, 'src/cards')
+const MANIFEST = path.join(SLICES_DIR, 'manifest.json')
+
+/**
+ * 存量改名映射（2026-09-17 逐张核图确认，见 slices_convention.md §1.1）：
+ * 同组多个名字 = 同一张图（sha256 一致），统一收敛到一个语义名；
+ * 目标名已存在且内容一致时自动退化为「合并删除副本」，不产生改名动作。
+ */
+const LEGACY_RENAMES = {
+  // 60×60 橙色右箭头（三卡共用一张图）
+  'chevron_right.png': 'iconArrowRightOrange.png',
+  'assetAllocRadar_arrow_right.png': 'iconArrowRightOrange.png',
+  '编组 4.png': 'iconArrowRightOrange.png',
+  // 运营位 banner（同名副本）
+  'bannerEquityActivity1.png': 'bannerEquityActivity.png',
+  // 40×40 深色右箭头
+  'chevron_right_alt2.png': 'iconArrowRightDark.png',
+  '编组 4_alt2.png': 'iconArrowRightDark.png',
+  // 48×48 双 chevron 向下 = 展开更多
+  'icon_collapse.png': 'iconExpandMore.png',
+  '展开.png': 'iconExpandMore.png',
+  // 编辑铅笔图标
+  'icon_edit.png': 'iconEdit.png',
+  'icon_edit_pen.png': 'iconEdit.png',
+  'icon_编辑.png': 'iconEdit.png',
+  // 单选框未选中
+  'icon_radio_off2.png': 'iconRadioUnchecked.png',
+  'icon_单选框_未选中.png': 'iconRadioUnchecked.png',
+  // 192×168 烘焙磁贴（头像 + 专属服务文案）
+  'icon_等级权益_左.png': 'tileExclusiveService.png',
+  'icon_等级权益_搜集银行转账免费_alt.png': 'tileExclusiveService.png',
+  'icon_等级权益_搜集银行转账免费_alt2.png': 'tileExclusiveService.png',
+}
+
+function parseArgs(argv) {
+  const opts = { write: false, dedupe: false, prune: false, legacy: true, json: false, renames: [], map: null }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--write') opts.write = true
+    else if (a === '--dedupe') opts.dedupe = true
+    else if (a === '--prune-unreferenced') opts.prune = true
+    else if (a === '--no-legacy') opts.legacy = false
+    else if (a === '--json') opts.json = true
+    else if (a === '--rename') opts.renames.push(argv[++i])
+    else if (a === '--map') opts.map = argv[++i]
+    else if (a === '-h' || a === '--help') { opts.help = true }
+    else { console.error(`[slices_normalize] 未知参数：${a}`); process.exit(2) }
+  }
+  return opts
+}
+
+/** 扫全部卡片目录的 json，收集 `/slices/<name>` 引用与 `@filestore` url（原样文本口径）。 */
+function scanCardRefs(cardsDir, slicesDir) {
+  const cards = []
+  const referenced = new Map() // name -> Set("card/file")
+  const dangling = new Map()
+  if (!fs.existsSync(cardsDir)) return { cards, referenced, dangling }
+  for (const card of fs.readdirSync(cardsDir).sort()) {
+    const dir = path.join(cardsDir, card)
+    if (!fs.statSync(dir).isDirectory()) continue
+    for (const f of fs.readdirSync(dir).sort()) {
+      if (!f.endsWith('.json')) continue
+      const file = path.join(dir, f)
+      const text = fs.readFileSync(file, 'utf8')
+      cards.push({ card, file, text })
+      for (const m of text.matchAll(/\/slices\/[^"'`)\s\\]+/g)) {
+        let name = m[0].replace(/^\/slices\//, '')
+        try { name = decodeURIComponent(name) } catch { /* 保持原样 */ }
+        const where = `${card}/${f}`
+        if (fs.existsSync(path.join(slicesDir, name))) {
+          if (!referenced.has(name)) referenced.set(name, new Set())
+          referenced.get(name).add(where)
+        } else {
+          if (!dangling.has(name)) dangling.set(name, new Set())
+          dangling.get(name).add(where)
+        }
+      }
+    }
+  }
+  return { cards, referenced, dangling }
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2))
+  if (opts.help) {
+    console.error('用法：node slices_normalize.mjs [--write] [--dedupe] [--prune-unreferenced] [--rename old=new ...] [--map file.json] [--no-legacy] [--json]')
+    process.exit(0)
+  }
+
+  // ── 1. 收集现状 ──
+  const manifest = fs.existsSync(MANIFEST) ? JSON.parse(fs.readFileSync(MANIFEST, 'utf8')) : { version: 1, files: {} }
+  const manifestFiles = manifest.files || {}
+  const index = buildContentIndex(SLICES_DIR)
+  const shaOf = new Map()
+  for (const [sha, names] of index) for (const n of names) shaOf.set(n, sha)
+  const onDisk = [...shaOf.keys()].sort()
+  const { cards, referenced, dangling } = scanCardRefs(CARDS_DIR, SLICES_DIR)
+
+  // ── 2. 改名计划：old → new（多对一 = 同图多名收敛）──
+  const plan = new Map()
+  const addRenames = (obj, origin) => {
+    for (const [old, neu] of Object.entries(obj)) {
+      if (!old || !neu || old === neu) continue
+      if (plan.has(old) && plan.get(old) !== neu) {
+        console.error(`[slices_normalize] 改名冲突：${old} 被 ${origin} 与先前来源映射到不同目标（${plan.get(old)} vs ${neu}）`)
+        process.exit(2)
+      }
+      plan.set(old, neu)
+    }
+  }
+  if (opts.legacy) {
+    const live = {}
+    for (const [old, neu] of Object.entries(LEGACY_RENAMES)) if (onDisk.includes(old)) live[old] = neu
+    addRenames(live, 'LEGACY_RENAMES')
+  }
+  for (const spec of opts.renames) {
+    const eq = spec.indexOf('=')
+    if (eq <= 0) { console.error(`[slices_normalize] --rename 格式应为 old=new：${spec}`); process.exit(2) }
+    addRenames({ [spec.slice(0, eq)]: spec.slice(eq + 1) }, '--rename')
+  }
+  if (opts.map) addRenames(JSON.parse(fs.readFileSync(opts.map, 'utf8')), `--map ${opts.map}`)
+
+  // ── 3. --dedupe：sha256 同组收敛到语义名（计划里已有目标则并入该目标）──
+  const dupGroups = []
+  for (const [sha, names] of [...index].filter(([, n]) => n.length > 1).sort()) {
+    dupGroups.push({ sha, names: [...names].sort() })
+    if (!opts.dedupe) continue
+    const targets = new Set(names.map((n) => plan.get(n)).filter(Boolean))
+    let canonical = targets.size === 1 ? [...targets][0] : null
+    if (!canonical) {
+      canonical =
+        names.find((n) => plan.has(n) && plan.get(n)) ||
+        names.find((n) => checkSliceName(n).semantic && referenced.has(n)) ||
+        names.find((n) => checkSliceName(n).semantic) ||
+        names[0]
+    }
+    for (const n of names) if (n !== canonical && !plan.has(n)) plan.set(n, canonical)
+  }
+
+  // ── 4. 把多对一计划拆成「改名 / 合并删除」动作 ──
+  const byTarget = new Map()
+  for (const [old, neu] of plan) {
+    if (!onDisk.includes(old)) continue // 源已不存在，忽略
+    if (!byTarget.has(neu)) byTarget.set(neu, [])
+    byTarget.get(neu).push(old)
+  }
+  const renames = [] // { from, to }
+  const merges = [] // { name, into, sameContent }
+  const conflicts = []
+  for (const [target, sources] of [...byTarget].sort()) {
+    const targetExists = onDisk.includes(target) && !sources.includes(target)
+    if (targetExists) {
+      const same = sources.every((s) => shaOf.get(s) === shaOf.get(target))
+      if (!same) { conflicts.push({ target, sources }); continue }
+      for (const s of sources) merges.push({ name: s, into: target, sameContent: true })
+      continue
+    }
+    const origin = sources.find((s) => referenced.has(s)) || sources.find((s) => checkSliceName(s).semantic) || sources[0]
+    renames.push({ from: origin, to: target })
+    for (const s of sources) if (s !== origin) merges.push({ name: s, into: target, sameContent: shaOf.get(s) === shaOf.get(origin) })
+  }
+  if (conflicts.length) {
+    for (const c of conflicts) console.error(`[slices_normalize] 冲突：目标 ${c.target} 已存在且与源内容不同（${c.sources.join('、')}）→ 放弃该组，请人工处理`)
+    process.exit(2)
+  }
+
+  // ── 5. 剪枝候选：无 /slices/ 引用、无 manifest 记录（未上传真源）──
+  const renamedAway = new Set([...renames.map((r) => r.from), ...merges.map((m) => m.name)])
+  const pruneList = opts.prune
+    ? onDisk.filter((n) => !referenced.has(n) && !manifestFiles[n] && !renamedAway.has(n) && !byTarget.has(n))
+    : []
+
+  // ── 6. 引用改写对（最长优先，避免前缀误伤）──
+  const pairs = []
+  for (const r of renames) pairs.push([`/slices/${r.from}`, `/slices/${r.to}`])
+  for (const m of merges) pairs.push([`/slices/${m.name}`, `/slices/${m.into}`])
+  pairs.sort((a, b) => b[0].length - a[0].length)
+  // 被合并副本若已上传而保留名未上传 → @filestore 引用改写到保留名 url（保留名接管其 manifest 记录时不需要）
+  const filestorePairs = []
+
+  // ── 7. manifest 同步计划 ──
+  const manifestNext = JSON.parse(JSON.stringify(manifest))
+  const manifestFilesNext = manifestNext.files || (manifestNext.files = {})
+  const manifestActions = []
+  const ensureEntry = (name) => manifestFilesNext[name]
+  for (const r of renames) {
+    const entry = manifestFilesNext[r.from]
+    if (!entry) continue
+    delete manifestFilesNext[r.from]
+    const target = ensureEntry(r.to)
+    if (target) {
+      // 目标已有记录：源记录并入（同内容同 url 语义）
+      filestorePairs.push([entry.url, target.url].filter(Boolean))
+      manifestFilesNext[r.to].mergedFrom = [...new Set([...(target.mergedFrom || []), r.from])]
+      manifestActions.push(`${r.from} → 并入 ${r.to}（manifest 已有记录，url 改写到 ${target.url}）`)
+    } else {
+      manifestFilesNext[r.to] = { ...entry, renamedFrom: r.from }
+      manifestActions.push(`${r.from} → ${r.to}（保留 url=${entry.url}，记 renamedFrom）`)
+    }
+  }
+  for (const m of merges) {
+    const entry = manifestFilesNext[m.name]
+    if (!entry) continue
+    delete manifestFilesNext[m.name]
+    const keeper = ensureEntry(m.into)
+    if (keeper) {
+      if (entry.url && keeper.url && entry.url !== keeper.url) filestorePairs.push([entry.url, keeper.url])
+      keeper.mergedFrom = [...new Set([...(keeper.mergedFrom || []), m.name])]
+      manifestActions.push(`${m.name} → 并入 ${m.into}（记 mergedFrom；${entry.url === keeper.url ? 'url 相同' : `引用改写 ${entry.url} → ${keeper.url}`}）`)
+    } else {
+      manifestFilesNext[m.into] = { ...entry, renamedFrom: m.name }
+      manifestActions.push(`${m.name} → ${m.into}（接管 manifest 记录 url=${entry.url}）`)
+    }
+  }
+  for (const p of pruneList) {
+    if (manifestFilesNext[p]) { delete manifestFilesNext[p]; manifestActions.push(`${p} → 剪枝并移除 manifest 记录`) }
+  }
+  const fsPairs = filestorePairs.filter((p) => p.length === 2 && p[0] && p[1] && p[0] !== p[1]).map(([from, to]) => [from, to])
+
+  // ── 8. 落盘 or 报告 ──
+  const rewriteHits = new Map()
+  if (opts.write) {
+    for (const c of cards) {
+      let next = c.text
+      for (const [from, to] of pairs) if (next.includes(from)) next = next.split(from).join(to)
+      for (const [from, to] of fsPairs) if (next.includes(from)) next = next.split(from).join(to)
+      if (next !== c.text) {
+        fs.writeFileSync(c.file, next)
+        rewriteHits.set(`${c.card}/${path.basename(c.file)}`, (next.match(/\/slices\//g) || []).length >= 0 ? 1 : 1)
+      }
+    }
+    for (const r of renames) fs.renameSync(path.join(SLICES_DIR, r.from), path.join(SLICES_DIR, r.to))
+    for (const m of merges) fs.rmSync(path.join(SLICES_DIR, m.name), { force: true })
+    for (const p of pruneList) fs.rmSync(path.join(SLICES_DIR, p), { force: true })
+    if (manifestActions.length || renames.length || merges.length || pruneList.length) {
+      fs.writeFileSync(MANIFEST, `${JSON.stringify(manifestNext, null, 2)}\n`)
+    }
+  } else {
+    // dry-run：统计会被改写的卡片文件数
+    for (const c of cards) {
+      let next = c.text
+      for (const [from, to] of pairs) if (next.includes(from)) next = next.split(from).join(to)
+      for (const [from, to] of fsPairs) if (next.includes(from)) next = next.split(from).join(to)
+      if (next !== c.text) rewriteHits.set(`${c.card}/${path.basename(c.file)}`, 1)
+    }
+  }
+
+  // ── 9. 输出 ──
+  const afterNonSemantic = [...referenced.keys()]
+    .map((n) => ({ n, to: plan.get(n) }))
+    .filter(({ n, to }) => !checkSliceName(to || n).semantic)
+  const report = {
+    mode: opts.write ? 'write' : 'dry-run（加 --write 落盘）',
+    slicesDir: path.relative(REPO_ROOT, SLICES_DIR),
+    stats: {
+      filesBefore: onDisk.length,
+      uniqueContent: index.size,
+      referenced: referenced.size,
+      danglingRefs: dangling.size,
+      filesAfter: onDisk.length - merges.length - pruneList.length,
+    },
+    renames,
+    merges,
+    prune: pruneList,
+    cardFilesRewritten: [...rewriteHits.keys()],
+    manifestActions,
+    danglingRefs: [...dangling].map(([name, where]) => ({ name, refs: [...where] })),
+    stillNonSemanticReferenced: afterNonSemantic.map(({ n, to }) => ({ name: n, planned: to || null })),
+    note: '悬空引用 = 卡片引用了 src/slices 里不存在的文件，改名救不了，需回设计稿重新导出或换图（见交付说明）。',
+  }
+  if (opts.json) { console.log(JSON.stringify(report, null, 2)); return }
+  console.log(`🧹 切图归一化（${report.mode}）  ${report.slicesDir}/`)
+  console.log(`   文件 ${report.stats.filesBefore} → ${report.stats.filesAfter}（唯一内容 ${report.stats.uniqueContent}；被引用 ${report.stats.referenced}；悬空引用 ${report.stats.danglingRefs}）`)
+  if (renames.length) { console.log('\n改名：'); for (const r of renames) console.log(`   ${r.from} → ${r.to}`) }
+  if (merges.length) { console.log('\n同内容合并删除：'); for (const m of merges) console.log(`   ${m.name} ≡ ${m.into}（sha 一致）→ 删副本`) }
+  if (pruneList.length) { console.log('\n剪枝（无引用且未上传）：'); for (const p of pruneList) console.log(`   ${p}`) }
+  if (rewriteHits.size) console.log(`\n引用改写：${rewriteHits.size} 个卡片文件（${[...rewriteHits.keys()].join('、')}）`)
+  if (manifestActions.length) { console.log('\nmanifest 同步：'); for (const a of manifestActions) console.log(`   ${a}`) }
+  if (report.danglingRefs.length) { console.log('\n⚠️ 悬空引用（改名无法修复，需重新导出/换图）：'); for (const d of report.danglingRefs) console.log(`   ${d.name}  <- ${d.refs.join(', ')}`) }
+  if (report.stillNonSemanticReferenced.length) { console.log('\n⚠️ 仍非语义化的被引用切图：'); for (const s of report.stillNonSemanticReferenced) console.log(`   ${s.name}${s.planned ? ` → 计划改名 ${s.planned}` : '（无计划，需 --rename 指定）'}`) }
+  if (!opts.write && (renames.length || merges.length || pruneList.length)) console.log('\n（dry-run，未落盘；确认无误后加 --write 重跑）')
+}
+
+main()