@qilitt-mickey/vue3-temp-skill 1.1.62 → 1.1.64

package/scripts/design-audit.mjs

@@ -0,0 +1,878 @@
+#!/usr/bin/env node
+
+/**
+ * 设计层闭环审计 — 「样式逻辑 → 效果」的生效性断言。
+ *
+ * 发布闸（scripts/validate.mjs）校验的是技能包自身结构；本脚本校验的是
+ * **一次落地是否真的把变更集落成了有效样式**：声明了不等于生效，生效了不等于对。
+ * 它只做静态分析，不依赖浏览器与开发服务器。
+ *
+ * 用法：
+ *   node scripts/design-audit.mjs                        # 审计当前目录（落地项目根）
+ *   node scripts/design-audit.mjs --project <dir>         # 指定落地项目
+ *   node scripts/design-audit.mjs --json                  # 机器可读输出
+ *   node scripts/design-audit.mjs --container-width 1624  # 表格容器可用宽（列宽预算用）
+ *   node scripts/design-audit.mjs --report <file.md>      # 另存 Markdown 报告（可选，便于交付留档）
+ *
+ * 退出码：0 = 无 ERROR；1 = 存在 ERROR。
+ *
+ * 审计项：
+ *   E1 变量悬空      设计层 var(--x) 项目内无定义且无回退
+ *   E2 层错位        内层盒属性族写在表格宿主盒上（会被 EP 内层 .cell 覆盖）
+ *   E3 层叠败北      设计层声明特指度低于组件 scoped 同名类规则（含 [data-v] 加成）→ 不生效
+ *   E4 选择器挂空    设计层使用的项目类名在 src 中不存在（假锚点）
+ *   E5 列宽预算      存在无宽列（既无 width 又无 min-width）；Σ列宽超出容器
+ *   E6 收口断言      visible:false 的 sid 必须有 display:none（+提权）落点
+ *   E7 激活态越层    分组标题被写入叶子项的激活态（胶囊/指示条）
+ *   E8 浮层残留      form 要求收口下拉浮层，但组件仍消费 #dropdown
+ *   E9 形态收口缺件  form=icon_only 只显图标、未在同一作用域内收口文案（且不被兄弟变体规则骗过）
+ *   E10 scoped 挂空  组件 scoped 规则依赖运行时并不存在的类（重构残留，永不命中）
+ */
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SKILL_ROOT = path.resolve(__dirname, "..");
+
+const argv = process.argv.slice(2);
+const argValue = (name, def) => {
+  const i = argv.indexOf(name);
+  return i >= 0 && argv[i + 1] ? argv[i + 1] : def;
+};
+const PROJECT = path.resolve(argValue("--project", process.cwd()));
+const AS_JSON = argv.includes("--json");
+const CONTAINER_EXPLICIT = argv.includes("--container-width");
+const CONTAINER_WIDTH = Number(argValue("--container-width", "1200")) || 1200;
+
+const DESIGN_LAYER_GLOBS = [
+  "src/styles/design-shell.scss",
+  "src/styles/design-tokens.scss",
+  "src/styles/dark.scss",
+];
+const SRC_DIRS = ["src"];
+const IGNORES = new Set(["node_modules", ".git", "dist", "build", ".vite", "public"]);
+const SRC_EXT = new Set([".vue", ".ts", ".tsx", ".js", ".mjs", ".scss", ".css", ".html"]);
+const JSON_EXT = new Set([".json"]);
+
+/** 内层盒属性族：必须落 EP 内层 .cell，落宿主 th/td 会被 .cell 覆盖 */
+const INNER_ONLY_PROPS = new Set([
+  "white-space",
+  "text-overflow",
+  "overflow",
+  "word-break",
+  "text-align",
+  "line-height",
+  "vertical-align",
+  "text-align-last",
+]);
+
+/** 项目自有变量前缀（--el-* 为出厂，不参与悬空判定） */
+const OWNED_VAR_PREFIXES = ["--ds-", "--vts-", "--re-", "--brand-", "--table-", "--pagination-", "--filter-", "--page-", "--action-bar-", "--empty-", "--menu-", "--sidebar-"];
+
+/** 项目自有类名前缀（用于选择器挂空判定） */
+const OWNED_CLASS_PREFIXES = ["vts-", "re-", "col-", "navbar-", "header-", "sider-", "sidebar-", "menu-", "card-tab", "tab-", "language-", "app-", "list-"];
+
+const errors = [];
+const warnings = [];
+const infos = [];
+
+const err = (id, msg) => errors.push({ id, msg });
+const warn = (id, msg) => warnings.push({ id, msg });
+const info = (id, msg) => infos.push({ id, msg });
+
+// ── 文件工具 ────────────────────────────────────────────────
+function walk(dir, out = [], exts = SRC_EXT) {
+  if (!fs.existsSync(dir)) return out;
+  for (const name of fs.readdirSync(dir)) {
+    if (IGNORES.has(name)) continue;
+    const full = path.join(dir, name);
+    let st;
+    try {
+      st = fs.statSync(full);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) walk(full, out, exts);
+    else if (exts.has(path.extname(name))) out.push(full);
+  }
+  return out;
+}
+
+const readIf = (p) => (fs.existsSync(p) ? fs.readFileSync(p, "utf-8") : null);
+
+// ── 迷你 CSS/SCSS 展平器 ────────────────────────────────────
+function stripComments(css) {
+  return css
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/(^|[\s;}])[/]{2}[^\n]*/g, "$1");
+}
+
+function addDecls(decls, chunk) {
+  const text = String(chunk);
+  if (!text.trim()) return;
+  for (const piece of text.split(";")) {
+    const t = piece.trim();
+    if (!t || t.startsWith("$") || t.startsWith("@")) continue;
+    const idx = t.indexOf(":");
+    if (idx <= 0) continue;
+    const prop = t.slice(0, idx).trim().toLowerCase();
+    const value = t.slice(idx + 1).trim();
+    if (!prop || /[{}]/.test(prop)) continue;
+    decls[prop] = value;
+  }
+}
+
+const splitList = (s) => String(s).split(",").map((x) => x.trim()).filter(Boolean);
+
+function joinSelector(parent, child) {
+  const parts = splitList(child);
+  if (!parent) return parts.join(", ");
+  const parents = splitList(parent);
+  const out = [];
+  for (const part of parts) {
+    if (part.includes("&")) {
+      for (const p of parents) out.push(part.replace(/&/g, p));
+    } else {
+      for (const p of parents) out.push(`${p} ${part}`);
+    }
+  }
+  return out.join(", ");
+}
+
+/**
+ * 把一段 SCSS 正文拆成「本层声明」与「子块」。
+ * 关键：声明与子块是交错的，必须逐字符按 `;` / `{}` 切分，
+ * 否则「先声明后嵌套」的规则会把声明粘到下一个子选择器上（错位出幽灵规则）。
+ */
+function parseRule(body) {
+  const blocks = [];
+  let declText = "";
+  let buf = "";
+  let i = 0;
+  while (i < body.length) {
+    const ch = body[i];
+    if (ch === '"' || ch === "'") {
+      let j = i + 1;
+      while (j < body.length && body[j] !== ch) j += body[j] === "\\" ? 2 : 1;
+      buf += body.slice(i, j + 1);
+      i = j + 1;
+    } else if (ch === "{" && buf.endsWith("#")) {
+      buf += ch; // SCSS 插值 #{}，不是块
+      i++;
+    } else if (ch === "{") {
+      const sel = buf.trim();
+      buf = "";
+      let depth = 1;
+      let j = i + 1;
+      let inner = "";
+      while (j < body.length && depth > 0) {
+        const c = body[j];
+        if (c === "{") depth++;
+        else if (c === "}") {
+          depth--;
+          if (depth === 0) break;
+        }
+        inner += c;
+        j++;
+      }
+      if (sel) blocks.push({ sel, body: inner });
+      i = j + 1;
+    } else if (ch === ";") {
+      declText += buf + ";";
+      buf = "";
+      i++;
+    } else if (ch === "}") {
+      i++;
+    } else {
+      buf += ch;
+      i++;
+    }
+  }
+  declText += buf;
+  return { declText, blocks };
+}
+
+const AT_SKIP = /^@(keyframes|-webkit-keyframes|-moz-keyframes|-o-keyframes|font-face|import|use|forward|charset|tailwind|apply|extend)/i;
+
+function flattenCss(css, parentSel = "", acc = []) {
+  const { declText, blocks } = parseRule(stripComments(css));
+  if (parentSel && declText.trim()) {
+    const decls = {};
+    addDecls(decls, declText);
+    if (Object.keys(decls).length) acc.push({ selector: parentSel, decls });
+  }
+  for (const b of blocks) {
+    const sel = b.sel.trim();
+    if (!sel || AT_SKIP.test(sel)) continue;
+    if (sel.startsWith("@")) {
+      flattenCss(b.body, parentSel, acc);
+      continue;
+    }
+    flattenCss(b.body, joinSelector(parentSel, sel), acc);
+  }
+  return acc;
+}
+
+const classTokens = (selector) => [...selector.matchAll(/\.(-?[A-Za-z_][\w-]*)/g)].map((m) => m[1]);
+/** 去掉伪元素后的「末位复合选择器」——它才是这条规则真正作用的那一层元素 */
+const lastCompound = (sel) => {
+  const parts = String(sel)
+    .replace(/::[a-z-]+(\([^)]*\))?/gi, "")
+    .split(/[\s>+~]+/)
+    .filter(Boolean);
+  return parts[parts.length - 1] || "";
+};
+const allVars = (text) => [...text.matchAll(/var\(\s*(--[\w-]+)\s*(,)?/g)].map((m) => ({ name: m[1], hasFallback: !!m[2] }));
+
+// ── 采集：设计层 / 项目源 / 变更集 / 词典 ────────────────────
+const designFiles = DESIGN_LAYER_GLOBS.map((g) => path.join(PROJECT, g)).filter((p) => fs.existsSync(p));
+const extraDesign = walk(path.join(PROJECT, "src", "styles")).filter((p) => /design-.*\.(scss|css)$/i.test(path.basename(p)));
+const DESIGN_FILES = [...new Set([...designFiles, ...extraDesign])];
+
+const srcFiles = SRC_DIRS.flatMap((d) => walk(path.join(PROJECT, d)));
+const srcTextByFile = new Map();
+for (const f of srcFiles) srcTextByFile.set(f, readIf(f) ?? "");
+
+const designSet = new Set(DESIGN_FILES.map((p) => path.resolve(p)));
+const projectText = [...srcTextByFile.entries()]
+  .filter(([f]) => !designSet.has(path.resolve(f)))
+  .map(([, t]) => t)
+  .join("\n");
+
+const designCss = DESIGN_FILES.map((f) => srcTextByFile.get(f) ?? readIf(f) ?? "").join("\n");
+// 每条规则带上来源文件：用于区分「本次落地的设计层」与「历史遗留层」的告警级别
+const designRules = DESIGN_FILES.flatMap((f) =>
+  flattenCss(srcTextByFile.get(f) ?? readIf(f) ?? "").map((r) => ({ ...r, file: f })),
+);
+const PRIMARY_LAYER = path.resolve(PROJECT, argValue("--design-layer", "src/styles/design-shell.scss"));
+const isPrimary = (file) => path.resolve(file) === PRIMARY_LAYER;
+
+// 变更集（取 .codebuddy/design 下第一个 changeset-*.json）
+const designDir = path.join(PROJECT, ".codebuddy", "design");
+let changeset = null;
+let changesetFile = null;
+if (fs.existsSync(designDir)) {
+  const cand = fs.readdirSync(designDir).filter((f) => /^changeset.*\.json$/i.test(f)).sort();
+  if (cand.length) {
+    changesetFile = path.join(designDir, cand[0]);
+    try {
+      changeset = JSON.parse(fs.readFileSync(changesetFile, "utf-8"));
+    } catch (e) {
+      err("E0", `变更集解析失败：${changesetFile} — ${e.message}`);
+    }
+  }
+}
+
+// 词典（技能包自带 mapping/）
+const dictSidMap = new Map();
+const dictEntries = [];
+(function loadMapping() {
+  const roots = ["mapping/scenes", "mapping/component", "mapping/layout", "mapping/basic"].map((r) => path.join(SKILL_ROOT, r));
+  const files = roots.flatMap((r) => walk(r, [], JSON_EXT));
+  for (const f of files) {
+    try {
+      const json = JSON.parse(fs.readFileSync(f, "utf-8"));
+      for (const [sid, entry] of Object.entries(json.mappings || {})) {
+        if (!entry || typeof entry !== "object") continue;
+        dictSidMap.set(sid, { ...entry, __file: f });
+        dictEntries.push({ sid, entry });
+      }
+    } catch {
+      /* 忽略无法解析的映射文件 */
+    }
+  }
+})();
+
+// ── E1 变量悬空 ─────────────────────────────────────────────
+(function checkE1() {
+  if (!designCss) return;
+  const defined = new Set();
+  for (const t of [designCss, projectText].filter(Boolean)) {
+    for (const m of t.matchAll(/(--[\w-]+)\s*:/g)) defined.add(m[1]);
+  }
+  if (changeset) {
+    // 令牌名可能只在变更集里出现（由项目侧再映射），一并视为已声明
+    for (const m of JSON.stringify(changeset).matchAll(/--[\w-]+/g)) defined.add(m[0]);
+  }
+  const missing = new Map();
+  for (const { name, hasFallback } of allVars(designCss)) {
+    if (hasFallback || defined.has(name)) continue;
+    if (!OWNED_VAR_PREFIXES.some((p) => name.startsWith(p))) continue;
+    missing.set(name, (missing.get(name) || 0) + 1);
+  }
+  for (const [name, count] of missing) {
+    err("E1", `变量悬空：设计层使用了 ${name}（${count} 处），但项目内无定义、也无 var() 回退 —— 该声明整条失效。`);
+  }
+  if (!missing.size) info("E1", `变量悬空：0 处（受检前缀 ${OWNED_VAR_PREFIXES.join(" ")}）`);
+})();
+
+// ── E2 层错位 ───────────────────────────────────────────────
+(function checkE2() {
+  const hits = [];
+  for (const rule of designRules) {
+    const sel = rule.selector;
+    if (!/el-table|(^|[\s,>])(th|td)(\.|[\s,:{]|$)/.test(sel)) continue;
+    if (/\.cell\b/.test(sel)) continue; // 已锚定内层文本盒
+    const offenders = Object.keys(rule.decls).filter((p) => INNER_ONLY_PROPS.has(p));
+    if (offenders.length) hits.push({ sel, offenders });
+  }
+  for (const h of hits.slice(0, 12)) {
+    err("E2", `层错位：${h.sel} 声明了内层盒属性族 [${h.offenders.join(", ")}]，但未锚定 > .cell —— 会被 Element Plus 内层 .cell 覆盖，等于没写。`);
+  }
+  if (hits.length > 12) err("E2", `层错位：另有 ${hits.length - 12} 处未列出。`);
+  if (!hits.length) info("E2", "层错位：0 处");
+})();
+
+// ── E3 层叠胜负 / E10 scoped 挂空 ───────────────────────────
+// 组件 scoped 规则编译后末位选择器会追加 [data-v-xxx] 属性选择器，等价 +1 个类级特指度。
+// 因此「设计层声明是否真的生效」必须算特指度，不能只看有没有同名类。
+const SCOPED_ATTR = 1000;
+const STATE_PSEUDO = /:(hover|focus|active|visited|disabled|checked|focus-within|focus-visible|first-child|last-child|nth-[\w-]+)/i;
+
+const pseudoElOf = (sel) => (sel.match(/::([a-z-]+)/i) || [])[1] || "";
+
+function specOf(selector) {
+  const s = selector
+    .replace(/::[a-z-]+(\([^)]*\))?/gi, " ")
+    .replace(/:not\(([^)]*)\)/g, ":not");
+  const ids = (s.match(/#[\w-]+/g) || []).length;
+  const classes =
+    (s.match(/\.[\w-]+/g) || []).length +
+    (s.match(/\[[^\]]*\]/g) || []).length +
+    (s.match(/:(?!:)[\w-]+(\([^)]*\))?/g) || []).length;
+  const elems = (s.match(/(?:^|[\s>+~])[a-zA-Z][\w-]*/g) || []).length;
+  return ids * 1e6 + classes * 1e3 + elems;
+}
+
+/** 状态类 / 第三方类不属于「项目自有挂载点」，挂空判定不参与 */
+const isOwnedClass = (c) =>
+  OWNED_CLASS_PREFIXES.some((p) => c.startsWith(p)) && !/^(is|has|van|el|n)-/.test(c);
+const IGNORE_DEAD = new Set(["language-text", "language-text__item"]);
+
+// 模板/脚本源码（剔掉 style 块，避免样式里的类名自证「已挂载」）
+const markupText = [...srcTextByFile.entries()]
+  .filter(([f]) => f.endsWith(".vue"))
+  .map(([, t]) => t.replace(/<style[\s\S]*?<\/style>/g, ""))
+  .join("\n");
+
+// 收集组件 scoped 规则，并标记「挂空」的（选择器链条上存在运行时不存在的类）
+const scopedRules = [];
+const scopedDead = [];
+for (const [f, t] of srcTextByFile) {
+  if (!f.endsWith(".vue")) continue;
+  for (const m of t.matchAll(/<style[^>]*scoped[^>]*>([\s\S]*?)<\/style>/g)) {
+    for (const r of flattenCss(m[1])) {
+      const cls = [...new Set(classTokens(r.selector))];
+      if (!cls.length) continue;
+      if (/:deep\(|::v-deep|:global\(/.test(r.selector)) continue;
+      const owned = cls.filter(isOwnedClass);
+      const missing = owned.filter((c) => !markupText.includes(c));
+      const dead = missing.length > 0;
+      scopedRules.push({ ...r, file: f, dead });
+      if (dead) scopedDead.push({ sel: r.selector, file: f, missing });
+    }
+  }
+}
+
+// 竞争者索引：只登记「与目标同一元素（同末位复合选择器）」且非挂空的规则
+const scopedIdx = new Map();
+for (const r of scopedRules) {
+  if (r.dead) continue; // 挂空的规则永不命中，不能算作竞争者
+  if (STATE_PSEUDO.test(r.selector)) continue; // 状态态不参与基态竞争
+  const pe = pseudoElOf(r.selector);
+  const spec = specOf(r.selector) + SCOPED_ATTR;
+  for (const cls of new Set(classTokens(lastCompound(r.selector)))) {
+    for (const prop of Object.keys(r.decls)) {
+      const key = `${cls}|${prop}|${pe}`;
+      const cur = scopedIdx.get(key);
+      if (!cur || spec > cur.spec) scopedIdx.set(key, { spec, selector: r.selector, file: r.file });
+    }
+  }
+}
+
+(function checkE3() {
+  if (!scopedIdx.size) {
+    info("E3", "层叠胜负：无同属性竞争的组件 scoped 规则");
+    return;
+  }
+  const hits = [];
+  const seen = new Set();
+  for (const r of designRules) {
+    const pe = pseudoElOf(r.selector);
+    for (const part of splitList(r.selector)) {
+      const last = lastCompound(part);
+      const clsList = [...new Set(classTokens(last))];
+      if (!clsList.length) continue;
+      const mine = specOf(part);
+      for (const prop of Object.keys(r.decls)) {
+        for (const cls of clsList) {
+          const comp = scopedIdx.get(`${cls}|${prop}|${pe}`);
+          if (!comp || mine > comp.spec) continue;
+          const key = `${part}|${prop}`;
+          if (seen.has(key)) continue;
+          seen.add(key);
+          hits.push({ sel: part, prop, cls, mine, comp });
+        }
+      }
+    }
+  }
+  const shown = hits.slice(0, 12);
+  for (const h of shown) {
+    const rel = path.relative(PROJECT, h.comp.file).replace(/\\/g, "/");
+    err(
+      "E3",
+      `层叠败北：${h.sel} 的 ${h.prop} 特指度 ${h.mine} ≤ 组件 scoped 竞争者 ${h.comp.selector}（${rel}）的 ${h.comp.spec}（scoped 追加 [data-v] 属性选择器，等价 +1 类级）—— 该声明不会生效：收口类提权加 !important，形态类须提高锚定层级（补上 .is-active / .card-item 等对方使用的限定类）。`,
+    );
+  }
+  if (hits.length > shown.length) {
+    const byFile = new Map();
+    for (const h of hits.slice(shown.length)) {
+      const rel = path.relative(PROJECT, h.comp.file).replace(/\\/g, "/");
+      byFile.set(rel, (byFile.get(rel) || 0) + 1);
+    }
+    const detail = [...byFile.entries()].sort((a, b) => b[1] - a[1]).map(([f, n]) => `${f}(${n})`).join("、");
+    err("E3", `层叠败北：另有 ${hits.length - shown.length} 处未列出，集中在 ${detail} —— 同一文件成片败北说明该区域的锚定层级整体偏低，应按文件批量提权。`);
+  }
+  if (!hits.length) info("E3", `层叠胜负：0 处败北（竞争者 ${scopedIdx.size} 组）`);
+})();
+
+// ── E10 组件 scoped 规则挂空（重构残留） ────────────────────
+(function checkE10() {
+  const dead = scopedDead.filter((d) => d.missing.some((c) => !IGNORE_DEAD.has(c)));
+  if (!dead.length) {
+    info("E10", "组件 scoped 挂空：0 处");
+    return;
+  }
+  for (const d of dead.slice(0, 15)) {
+    const rel = path.relative(PROJECT, d.file).replace(/\\/g, "/");
+    warn(
+      "E10",
+      `scoped 规则挂空：${rel} 的 ${d.sel} 依赖运行时并不存在的类 [${d.missing.join(", ")}] —— 整条规则永不命中（多在结构重构后残留），既不会生效也会误导后续收口判断。`,
+    );
+  }
+  if (dead.length > 15) warn("E10", `scoped 规则挂空：另有 ${dead.length - 15} 处未列出。`);
+})();
+
+// ── E4 选择器挂空 ───────────────────────────────────────────
+(function checkE4() {
+  const used = new Map(); // 类名 → 声明它的设计层文件集合
+  for (const rule of designRules) {
+    for (const c of classTokens(rule.selector)) {
+      if (!OWNED_CLASS_PREFIXES.some((p) => c.startsWith(p))) continue;
+      if (!used.has(c)) used.set(c, new Set());
+      used.get(c).add(rule.file);
+    }
+  }
+  const phantom = [...used.keys()].filter((c) => !projectText.includes(c));
+  const hard = phantom.filter((c) => [...used.get(c)].some(isPrimary));
+  const soft = phantom.filter((c) => !hard.includes(c));
+  for (const c of hard.slice(0, 15)) {
+    err("E4", `选择器挂空：设计层选择器使用了 .${c}，但 src/ 全量源码里没有该类的挂载点 —— 规则命中不到任何元素（锚点必须锚「实际在」，不能锚「应该在」）。`);
+  }
+  if (hard.length > 15) err("E4", `选择器挂空：另有 ${hard.length - 15} 个未列出。`);
+  for (const c of soft.slice(0, 10)) {
+    const files = [...used.get(c)].map((f) => path.basename(f)).join(", ");
+    warn("E4", `选择器挂空（历史层）：.${c} 只出现在 ${files}，项目内无挂载点 —— 静态遗留，非本次落地引入，但同样永不命中。`);
+  }
+  if (soft.length > 10) warn("E4", `选择器挂空（历史层）：另有 ${soft.length - 10} 个未列出。`);
+  if (!phantom.length) info("E4", `选择器挂空：0 个（受检类名 ${used.size} 个）`);
+})();
+
+// ── E5 列宽预算 ─────────────────────────────────────────────
+function extractObjectLiterals(arrSrc) {
+  const out = [];
+  let depth = 0;
+  let start = -1;
+  for (let i = 0; i < arrSrc.length; i++) {
+    const ch = arrSrc[i];
+    if (ch === "{") {
+      if (depth === 0) start = i;
+      depth++;
+    } else if (ch === "}") {
+      depth--;
+      if (depth === 0 && start >= 0) {
+        out.push(arrSrc.slice(start, i + 1));
+        start = -1;
+      }
+    }
+  }
+  return out;
+}
+
+function matchArrayLiteral(text, anchorRe) {
+  const m = anchorRe.exec(text);
+  if (!m) return null;
+  const open = text.indexOf("[", m.index);
+  if (open < 0) return null;
+  let depth = 0;
+  for (let i = open; i < text.length; i++) {
+    if (text[i] === "[") depth++;
+    else if (text[i] === "]") {
+      depth--;
+      if (depth === 0) return text.slice(open + 1, i);
+    }
+  }
+  return null;
+}
+
+(function checkE5() {
+  const tableFiles = [...srcTextByFile.entries()].filter(([, t]) => t.includes("el-table-column"));
+  if (!tableFiles.length) {
+    info("E5", "列宽预算：未在 src 中发现 el-table-column");
+    return;
+  }
+  const pxOf = (s) => {
+    const m = String(s).match(/(\d+(?:\.\d+)?)\s*(px)?/);
+    return m ? Number(m[1]) : null;
+  };
+  // 表头文案最小占宽：CJK ≈ 1em，ASCII ≈ 0.6em；两侧各留 16px 宿主内边距
+  const HEADER_FS = 14;
+  const CELL_PAD = 16;
+  const textWidth = (label) => {
+    let w = 0;
+    for (const ch of String(label)) w += /[\u2e80-\u9fff\uff00-\uffef]/.test(ch) ? HEADER_FS : HEADER_FS * 0.6;
+    return Math.ceil(w);
+  };
+  const minFit = (label) => textWidth(label) + CELL_PAD * 2;
+  // 列名可能是 $t('类型') 这类 i18n 调用，需取出引号内的真实文案
+  const cleanLabel = (raw) => {
+    const s = String(raw).trim();
+    const q = s.match(/[`'"]([^`'"]+)[`'"]/);
+    return ((q ? q[1] : s).trim() || "?");
+  };
+  const labelOf = (src) => {
+    const m =
+      src.match(/label:\s*([^,\n}]+)/) || src.match(/\blabel="([^"]*)"/) || src.match(/\blabel='([^']*)'/);
+    return m ? cleanLabel(m[1]) : "?";
+  };
+  const OPS = ["operate", "operation", "actions"];
+
+  for (const [file, text] of tableFiles) {
+    const rel = path.relative(PROJECT, file).replace(/\\/g, "/");
+    const declared = [];
+    const noWidth = [];
+
+    // 1) 列定义数组（模板常用动态列）
+    const arr = matchArrayLiteral(text, /(?:const|let|var)\s+\w*[Cc]olumn\w*\s*(?::[^=]+)?=\s*\[/);
+    if (arr) {
+      for (const objSrc of extractObjectLiterals(arr)) {
+        const label = labelOf(objSrc);
+        const prop = (objSrc.match(/prop:\s*[`'"]([^`'"]+)/) || [])[1] || "?";
+        const w = objSrc.match(/\bwidth:\s*[`'"]?([\d.]+)/);
+        const mw = objSrc.match(/\bminWidth:\s*[`'"]?([\d.]+)/);
+        if (w) declared.push({ label, prop, w: pxOf(w[1]) });
+        else if (mw) declared.push({ label, prop, mw: pxOf(mw[1]) });
+        else noWidth.push({ label, prop });
+      }
+    }
+
+    // 2) 内联列（selection / index / 手工列）
+    for (const tag of text.matchAll(/<el-table-column\b[\s\S]*?(?:\/>|>)/g)) {
+      const src = tag[0];
+      const type = (src.match(/:?type="['"]([^'"]+)/) || [])[1] || "";
+      const label = (src.match(/:?label="([^"]*)"/) || src.match(/:?label='([^']*)'/) || [])[1];
+      const labelText = label ? cleanLabel(label) : type || "?";
+      const hasW = /(^|\s):?width=/.test(src) || /\bwidth=/.test(src);
+      const hasMw = /:?min-width=/.test(src) || /:?minWidth=/.test(src);
+      if (hasW || hasMw) continue;
+      if (type === "selection" || type === "index") {
+        warn("E5", `${rel}：${type === "selection" ? "选择列" : "序号列"}（${labelText}）未声明 width / min-width，只能按出厂兜底宽度参与布局（§11.132 要求逐列声明意图）。`);
+      } else if (type) {
+        noWidth.push({ label: labelText, prop: type });
+      }
+    }
+
+    const realNoWidth = noWidth.filter((c) => !OPS.includes(c.prop));
+    for (const c of realNoWidth) {
+      err(
+        "E5",
+        `${rel}：列「${c.label}」(prop=${c.prop}) 既无 width 也无 min-width —— 无宽列由出厂兜底宽度参与布局，会被相邻固定宽列挤压；本列表头文案需 ≥ ${minFit(c.label)}px（文案 ${textWidth(c.label)}px + 内边距 ${CELL_PAD * 2}px），请按此反推 width / min-width（换行与省略号截断都源于此）。`,
+      );
+    }
+
+    // 3) 已声明 min-width 的列：min-width 必须容得下自己的表头文案
+    for (const c of declared) {
+      if (c.mw == null) continue;
+      const need = minFit(c.label);
+      if (c.mw < need) {
+        err(
+          "E5",
+          `${rel}：列「${c.label}」min-width=${c.mw}px < 表头文案最小占宽 ${need}px —— 布局算法压缩到 min-width 时表头必然换行或截断（「${c.label}」→「${c.label.slice(0, 2)}…」）。`,
+        );
+      }
+    }
+
+    const total = declared.reduce((s, c) => s + (c.w ?? 0), 0);
+    const minTotal = declared.reduce((s, c) => s + (c.mw ?? 0), 0);
+    const fixedCount = declared.filter((c) => c.w).length;
+    const flexCount = declared.filter((c) => c.mw).length;
+    const budget = total + minTotal;
+    const noWidthNeed = realNoWidth.reduce((s, c) => s + minFit(c.label), 0);
+    const line = `${rel}：固定宽 ${fixedCount} 列(${total}px) / 伸缩列 ${flexCount} 列(${minTotal}px) / 无宽列 ${realNoWidth.length} 列(需 ${noWidthNeed}px)`;
+    if (CONTAINER_EXPLICIT && budget + noWidthNeed > CONTAINER_WIDTH) {
+      err(
+        "E5",
+        `${line} —— 合计 ${budget + noWidthNeed}px > 容器可用宽 ${CONTAINER_WIDTH}px：列宽预算溢出，必须在设计侧收敛（减少列 / 降 min-width / 显式声明横向滚动），不允许靠静默压缩消化。`,
+      );
+    } else if (!CONTAINER_EXPLICIT && budget + noWidthNeed > CONTAINER_WIDTH) {
+      warn(
+        "E5",
+        `${line} —— 合计 ${budget + noWidthNeed}px 超出假定容器宽 ${CONTAINER_WIDTH}px。容器宽为估值，请用 --container-width <px> 传入实际内容区宽度后复跑，据以判定是否溢出。`,
+      );
+    } else {
+      info("E5", `${line}，合计 ${budget + noWidthNeed}px ≤ ${CONTAINER_WIDTH}px`);
+    }
+  }
+})();
+
+// ── E6 visible:false 收口断言 ──────────────────────────────
+(function checkE6() {
+  if (!changeset) {
+    info("E6", "未发现变更集（.codebuddy/design/changeset*.json），跳过收口断言");
+    return;
+  }
+  const changes = changeset.changes || [];
+  const closable = changes.filter((c) => c.visible === false || c.style?.visible === false);
+  if (!closable.length) {
+    info("E6", "收口断言：变更集无 visible:false 项");
+    return;
+  }
+  for (const change of closable) {
+    const entry = dictSidMap.get(change.id);
+    const selector = entry?.selector;
+    if (!selector) {
+      warn("E6", `${change.id} 声明 visible:false，但词典无 selector，无法断言收口落点。`);
+      continue;
+    }
+    const target = classTokens(selector).slice(-1)[0];
+    if (!target) {
+      warn("E6", `${change.id} 的词典 selector「${selector}」不含类名，无法断言收口落点。`);
+      continue;
+    }
+    const rule = designRules.find(
+      (r) => r.selector.includes(`.${target}`) && /none/i.test(r.decls.display || ""),
+    );
+    if (!rule) {
+      err("E6", `${change.id} 声明 visible:false，但设计层没有任何「命中 .${target} 且 display:none」的收口规则 —— 元素会照旧显示。`);
+    } else if (!/!important/i.test(rule.decls.display)) {
+      warn("E6", `${change.id} 的收口规则 ${rule.selector} 的 display:none 未加 !important，存在被组件 scoped 同权重反压的风险。`);
+    } else {
+      info("E6", `${change.id} → ${rule.selector} display:none !important ✓`);
+    }
+  }
+})();
+
+// ── E7 激活态越层 ───────────────────────────────────────────
+(function checkE7() {
+  const hits = designRules.filter((r) => {
+    const sel = r.selector;
+    const onGroup = /el-sub-menu|__title/.test(sel);
+    const active = /is-active|\.active\b|\[aria-current|\.is-opened/.test(sel);
+    if (!onGroup || !active) return false; // 必须同时命中「分组标题」与「激活态」才是越层
+    const setsSurface = Object.keys(r.decls).some(
+      (p) => p === "background" || p.startsWith("background") || p === "box-shadow" || p === "border-inline-start",
+    );
+    const pseudoBar = /::?(before|after)/.test(sel);
+    return setsSurface || pseudoBar;
+  });
+  for (const r of hits.slice(0, 10)) {
+    err("E7", `激活态越层：${r.selector} 把激活态（胶囊/指示条）写到了可展开分组的标题上 —— 分组标题会同时长出胶囊与竖向指示条，并与右侧展开箭头叠压（§6.15/§6.16 要求激活态只作用叶子项，分组标题须以 :not(.el-sub-menu__title) 排除）。`);
+  }
+  if (!hits.length) info("E7", "激活态越层：0 处");
+})();
+
+// ── E8 浮层残留 ─────────────────────────────────────────────
+(function checkE8() {
+  if (!changeset) {
+    info("E8", "未发现变更集，跳过浮层残留检查");
+    return;
+  }
+  for (const change of changeset.changes || []) {
+    const form = change.form;
+    if (!form) continue;
+    const entry = dictSidMap.get(change.id);
+    if (!entry) continue;
+    const required = entry.suppress_rules?.[form] || [];
+    const structural = [...required, ...(entry.structure_ops_required?.[form] || [])].join(" ");
+    if (!/popper|dropdown|浮层/i.test(structural)) continue;
+    const compFile = entry.file && typeof entry.file === "string" ? entry.file.match(/(src\/[\w./-]+\.vue)/) : null;
+    if (!compFile) continue;
+    const p = path.join(PROJECT, compFile[1]);
+    const t = readIf(p);
+    if (!t) continue;
+    if (/#dropdown|ElDropdown|el-dropdown/.test(t)) {
+      err("E8", `${change.id} 的 form=${form} 要求收口下拉浮层，但 ${compFile[1]} 仍保留 ElDropdown / #dropdown 消费 —— 点击触发器仍会弹出浮层（浮层属 teleport popper，样式层收不掉）。`);
+    } else {
+      info("E8", `${change.id} 浮层收口 ✓`);
+    }
+  }
+})();
+
+// ── E9 形态收口缺件 ─────────────────────────────────────────
+// 形态类 form（如 icon_only）落地必须「成对」：显图标 + 隐文案，且收口要落回该语义元素
+// 自己的作用域内。只按「全局有没有 .tag-title{display:none}」判断会被兄弟变体规则骗过。
+const normSel = (s) => String(s).replace(/\s+/g, " ").trim();
+const lastClassOutsideNot = (sel) => {
+  const cleaned = String(sel).replace(/:not\([^)]*\)/g, "");
+  const parts = splitList(cleaned);
+  const last = parts.length ? lastCompound(parts[parts.length - 1]) : "";
+  const cls = classTokens(last);
+  if (cls.length) return cls[cls.length - 1];
+  const all = classTokens(cleaned);
+  return all.length ? all[all.length - 1] : null;
+};
+
+(function checkE9() {
+  if (!changeset) {
+    info("E9", "未发现变更集，跳过形态收口检查");
+    return;
+  }
+  for (const change of changeset.changes || []) {
+    if (!/^(icon_only|icon)$/.test(change.form || "")) continue;
+    const entry = dictSidMap.get(change.id);
+    if (!entry) {
+      warn("E9", `${change.id} 的 form=${change.form} 在词典里找不到条目，无法断言形态收口。`);
+      continue;
+    }
+    const scope = normSel(entry.selector || "");
+    const subs = entry.sub_selectors || {};
+    const textSub = subs.title || subs.text;
+    const iconSub = subs.icon || subs.leading_icon;
+    if (!scope || !textSub) {
+      warn("E9", `${change.id} 的词典缺少 selector 或 sub_selectors.title，无法断言「显图标 + 隐文案」是否成对。`);
+      continue;
+    }
+    const textTarget = lastClassOutsideNot(textSub);
+    const iconTarget = iconSub ? lastClassOutsideNot(iconSub) : null;
+    const inScope = (r) => {
+      const s = normSel(r.selector);
+      return s.includes(scope);
+    };
+    const closed = designRules.filter(
+      (r) => inScope(r) && /none/i.test(r.decls.display || "") && (!textTarget || normSel(r.selector).includes(`.${textTarget}`)),
+    );
+    const shown =
+      (iconTarget &&
+        designRules.find((r) => inScope(r) && normSel(r.selector).includes(`.${iconTarget}`) && /(block|inline-flex|flex|inline-block)/i.test(r.decls.display || ""))) ||
+      null;
+    const closedIcon = designRules.find((r) => inScope(r) && /\.card-tab-icon|\.tag-icon|icon/i.test(normSel(r.selector)) && /none/i.test(r.decls.display || ""));
+    // 图标与文案至少要有一边在本作用域内被显式声明，否则说明该形态未在本层落地
+    const landed = shown || closedIcon || closed.length;
+    if (!landed) continue;
+    if (!closed.length) {
+      err(
+        "E9",
+        `${change.id} 的 form=${change.form} 只落了「显图标」，没有在同一作用域 ${scope} 内收口文案（需要 .${textTarget} 的 display:none，锚定 ${scope}）—— 图标与文案并存会把固定窄宽挤爆，文案被截断（如「工作台」→「工…」）。注意：作用域外的兄弟变体收口（如 :not(:nth-child(1))）不算成对。`,
+      );
+      continue;
+    }
+    if (!/!important/i.test(closed[0].decls.display || "")) {
+      warn("E9", `${change.id} 的文案收口 ${closed[0].selector} 未加 !important，存在被组件 scoped 同权反压的风险。`);
+    } else {
+      info("E9", `${change.id} 图标/文案收口成对 ✓（${closed[0].selector}）`);
+    }
+  }
+})();
+
+// ── @sid 标记覆盖率（可选增强） ─────────────────────────────
+(function checkSidCoverage() {
+  const marked = new Set([...designCss.matchAll(/@sid\s*:\s*([\w.$-]+)/g)].map((m) => m[1]));
+  if (!marked.size) {
+    info("SID", "设计层未使用 @sid 标记；建议每条设计层规则上方标注 /* @sid: <语义ID> */，即可启用「变更集 ↔ 设计层」逐条覆盖对账。");
+    return;
+  }
+  const declared = new Set((changeset?.changes || []).map((c) => c.id));
+  const missing = [...declared].filter((sid) => !marked.has(sid));
+  for (const sid of missing) {
+    warn("SID", `变更集声明了 ${sid}，但设计层没有对应 @sid 标记 —— 无法证明该条已落到样式/结构。`);
+  }
+  info("SID", `@sid 覆盖率：${declared.size - missing.length}/${declared.size}`);
+})();
+
+// ── 输出 ────────────────────────────────────────────────────
+const result = { project: PROJECT, errors, warnings, infos };
+
+const CHECK_TITLES = {
+  E1: "变量悬空",
+  E2: "层错位",
+  E3: "层叠败北",
+  E4: "选择器挂空",
+  E5: "列宽预算",
+  E6: "visible:false 收口断言",
+  E7: "激活态越层",
+  E8: "浮层残留",
+  E9: "形态收口缺件",
+  E10: "scoped 规则挂空",
+  SID: "@sid 覆盖率",
+};
+
+const REPORT_PATH = argValue("--report", null);
+if (REPORT_PATH) {
+  const rel = (p) => path.relative(PROJECT, p).replace(/\\/g, "/");
+  const rows = Object.keys(CHECK_TITLES)
+    .map((id) => {
+      const e = errors.filter((x) => x.id === id).length;
+      const w = warnings.filter((x) => x.id === id).length;
+      return { id, title: CHECK_TITLES[id], e, w };
+    })
+    .filter((r) => r.e || r.w);
+
+  const lines = [
+    "# 设计层闭环审计报告",
+    "",
+    `- 项目：\`${PROJECT}\``,
+    `- 设计层文件：${DESIGN_FILES.map(rel).join("、") || "(未发现)"}`,
+    `- 变更集：${changesetFile ? rel(changesetFile) : "(未发现)"}`,
+    `- 词典条目：${dictEntries.length} ｜ 设计层规则：${designRules.length} ｜ 容器可用宽：${CONTAINER_WIDTH}px${CONTAINER_EXPLICIT ? "" : "（估值，用 --container-width 校准）"}`,
+    `- 结论：**ERROR ${errors.length} ｜ WARN ${warnings.length}**`,
+    "",
+    "## 命中分布",
+    "",
+    "| 检查项 | 含义 | ERROR | WARN |",
+    "|---|---|---|---|",
+    ...rows.map((r) => `| ${r.id} | ${r.title} | ${r.e} | ${r.w} |`),
+    "",
+    "## 待修项（ERROR）",
+    "",
+    ...(errors.length ? errors.map((e, i) => `${i + 1}. **[${e.id}] ${CHECK_TITLES[e.id] || ""}** — ${e.msg}`) : ["（无）"]),
+    "",
+    "## 提示项（WARN）",
+    "",
+    ...(warnings.length ? warnings.map((w, i) => `${i + 1}. **[${w.id}] ${CHECK_TITLES[w.id] || ""}** — ${w.msg}`) : ["（无）"]),
+    "",
+    "## 已通过项",
+    "",
+    ...(infos.length ? infos.map((i) => `- [${i.id}] ${i.msg}`) : ["（无）"]),
+    "",
+    `> 复跑：\`node scripts/design-audit.mjs --project "${PROJECT}" --container-width ${CONTAINER_WIDTH}\``,
+    "",
+  ];
+  const out = path.resolve(REPORT_PATH);
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  fs.writeFileSync(out, lines.join("\n"), "utf-8");
+  console.log(`\n审计报告已写入：${out}`);
+}
+
+if (AS_JSON) {
+  console.log(JSON.stringify(result, null, 2));
+} else {
+  console.log("\n设计层闭环审计\n");
+  console.log(`项目: ${PROJECT}`);
+  console.log(`设计层文件: ${DESIGN_FILES.map((f) => path.relative(PROJECT, f).replace(/\\/g, "/")).join(", ") || "(未发现)"}`);
+  console.log(`变更集: ${changesetFile ? path.relative(PROJECT, changesetFile) : "(未发现)"}`);
+  console.log(`词典条目: ${dictEntries.length} | 设计层规则: ${designRules.length}\n`);
+  for (const i of infos) console.log(`  · [${i.id}] ${i.msg}`);
+  for (const w of warnings) console.log(`  ! [${w.id}] ${w.msg}`);
+  for (const e of errors) console.log(`  \u2717 [${e.id}] ${e.msg}`);
+  console.log(`\n${"=".repeat(50)}`);
+  console.log(`闭环审计：ERROR ${errors.length} | WARN ${warnings.length}`);
+  if (errors.length) {
+    console.log("\n\u2717 设计层存在「声明了却不会生效 / 形态未落地」的问题，修复后重跑。\n");
+  } else {
+    console.log("\n\u2713 设计层闭环审计通过（样式声明均已具备生效条件）。\n");
+  }
+}
+
+process.exit(errors.length ? 1 : 0);