@qilitt-mickey/vue3-temp-skill 1.2.5 → 1.2.7

package/scripts/check-landing.mjs

@@ -1,24 +1,29 @@
 #!/usr/bin/env node
 
 /**
- * 契约落地自检 —— 判断「契约 → 样式 → 挂载」三个闭环在哪一环断了
+ * 旧格式文本诊断 —— 默认禁用，不提供业务/视觉验收结论。
  *
  * 用法:
- *   node check-landing.mjs --project <项目根目录>
- *   node check-landing.mjs --project . --json
+ *   node check-landing.mjs --help
+ *   node check-landing.mjs --legacy-diagnostics --project <项目根目录> [--json]
  *
- * 退出码: 0 = 八项全过 / 1 = 有 FAIL 项
+ * 退出码: 0 = 帮助 / 2 = 未验收（包括旧文本检查没有 FAIL 的情况）
  *
- * 设计原则: 纯读取 + 确定性判断。不猜测、不修改、不联网。
+ * 设计原则: 显式启用后仅只读诊断。不修改、不联网。
  */
 
 import fs from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { execSync } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const IGNORE_DIRS = new Set([
   "node_modules", "dist", ".git", ".vite", "coverage",
   "__pycache__", ".idea", ".vscode", ".workbuddy", "unpackage",
+  // AI 工具配置 / 技能分发目录：技能脚本文本含 CSS 文件名与角色类名，
+  // 不排除会被 checkImported / checkMounting 自匹配成假 PASS
+  ".agents", ".codebuddy", ".cursor", ".qoder", ".windsurf", ".gemini",
+  ".trae", ".claude", ".github",
 ]);
 
 const CSS_FILES = ["ui-tokens.css", "ui-roles.css", "ui-layout.css"];
@@ -26,27 +31,37 @@ const SOURCE_EXT = new Set([".vue", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"
 const STYLE_EXT = new Set([".css", ".scss", ".less"]);
 
 const EXIT_OK = 0;
-const EXIT_FAIL = 1;
+const EXIT_UNVERIFIED = 2;
+const NOTICE = "check-landing.mjs 仅为旧格式文本诊断，不是业务/视觉验收，不得据此宣称还原通过。";
+const MIGRATION = "请迁移到 references/design-apply.md 和 references/visual-verification.md，以原稿为事实源手写项目视图，并逐区域、逐实例、逐状态进行浏览器验收。";
+const HELP = `用法: node check-landing.mjs --legacy-diagnostics --project <项目根目录> [--json]
+${NOTICE}
+默认不读取项目；只有显式 --legacy-diagnostics 才运行旧的只读文本诊断。
+旧格式检查与建议仅供理解历史数据，不是当前实施指令。
+${MIGRATION}
+--help / -h 退出 0；其他调用均退出 2，visualStatus=unverified。`;
 
 // ────────────────────────────── 参数解析
 
 function parseArgs(argv) {
-  const out = { project: process.cwd(), json: false };
+  const out = { project: process.cwd(), json: false, legacyDiagnostics: false, help: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--project" || a === "-p") {
       const v = argv[i + 1];
-      if (!v || v.startsWith("--")) {
-        console.error("错误: --project 后面必须跟项目根目录路径");
-        process.exit(EXIT_FAIL);
+      if (!v || v.startsWith("-")) {
+        throw new Error("--project 后面必须跟项目根目录路径");
       }
       out.project = path.resolve(v);
       i++;
     } else if (a === "--json") {
       out.json = true;
+    } else if (a === "--legacy-diagnostics") {
+      out.legacyDiagnostics = true;
     } else if (a === "--help" || a === "-h") {
-      console.log("用法: node check-landing.mjs --project <项目根目录> [--json]");
-      process.exit(EXIT_OK);
+      out.help = true;
+    } else {
+      throw new Error(`未知参数: ${a}`);
     }
   }
   return out;
@@ -222,7 +237,24 @@ function expectedClassName(roleName) {
   );
 }
 
-function checkMounting(projectRoot, roleNames) {
+/** 页面绑定引用的角色集合（pages.*.nodes 的 role + pages.*.regions 的 role）—— 挂载检查的「必需集」。
+ *  契约角色库可能大于单页实际用量（可选复用角色如 card.base），未被任何页面引用的角色缺失不应阻塞落地。 */
+function boundRoles(contract) {
+  const pages = (contract && contract.pages) || {};
+  const set = new Set();
+  for (const page of Object.values(pages)) {
+    if (!page || typeof page !== "object") continue;
+    for (const n of Array.isArray(page.nodes) ? page.nodes : []) {
+      if (n && n.role) set.add(String(n.role));
+    }
+    for (const b of Array.isArray(page.regions) ? page.regions : []) {
+      if (b && b.role) set.add(String(b.role));
+    }
+  }
+  return set;
+}
+
+function checkMounting(projectRoot, roleNames, requiredSet) {
   const vueFiles = walk(projectRoot, SOURCE_EXT, []);
   const roleClassRe = /\brole-[a-z0-9]+(?:-[a-z0-9]+)*/g;
   const usedClasses = new Map();
@@ -239,9 +271,19 @@ function checkMounting(projectRoot, roleNames) {
   const expected = roleNames.map(expectedClassName);
   const mounted = [];
   const missing = [];
+  const optionalMissing = [];
+  let optionalMounted = 0;
   for (let i = 0; i < roleNames.length; i++) {
-    if (usedClasses.has(expected[i])) mounted.push(expected[i]);
-    else missing.push(`${roleNames[i]} → .${expected[i]}`);
+    // 必需集为空时回退旧语义（全部必需）—— 兼容无 pages 绑定的契约
+    const required = !requiredSet || requiredSet.size === 0 || requiredSet.has(roleNames[i]);
+    if (usedClasses.has(expected[i])) {
+      mounted.push(expected[i]);
+      if (!required) optionalMounted++;
+    } else if (required) {
+      missing.push(`${roleNames[i]} → .${expected[i]}`);
+    } else {
+      optionalMissing.push(`${roleNames[i]} → .${expected[i]}`);
+    }
   }
 
   const layoutClassRe = /\bui-(?:page|region-[a-z0-9]+(?:-[a-z0-9]+)*)\b/g;
@@ -256,6 +298,8 @@ function checkMounting(projectRoot, roleNames) {
     scannedFileCount: vueFiles.length,
     mounted,
     missing,
+    optionalMissing,
+    optionalMounted,
     layoutClasses: [...layoutClasses],
     hasLayout: layoutClasses.has("ui-page"),
   };
@@ -263,14 +307,34 @@ function checkMounting(projectRoot, roleNames) {
 
 // ────────────────────────────── 结构校验（契约 §7）
 
-const LIBRARY_DIR = path.resolve(
-  path.dirname(fileURLToPath(import.meta.url)),
-  "../../project-ui-design/references/library"
-);
+/**
+ * 角色库目录多级探测（project-ui-design/references/library）：
+ * 1. 环境变量 UI_DESIGN_LIBRARY_DIR（显式指定，最高优先）
+ * 2. 双包同级（源码仓 skills/ 下、universal/rules 分发后的同级安装目录）
+ * 3. 上两层兜底
+ * 均不可达时返回 { dir: null, tried } —— 白名单校验降级为 WARN（预期降级，非故障）。
+ */
+function resolveLibraryDir() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const candidates = [];
+  if (process.env.UI_DESIGN_LIBRARY_DIR) {
+    candidates.push(path.resolve(process.env.UI_DESIGN_LIBRARY_DIR));
+  }
+  candidates.push(
+    path.resolve(here, "../../project-ui-design/references/library"),
+    path.resolve(here, "../../../project-ui-design/references/library"),
+  );
+  for (const dir of candidates) {
+    if (fs.existsSync(dir)) return { dir, tried: candidates };
+  }
+  return { dir: null, tried: candidates };
+}
 
 /** 加载角色库名集合：<场景>.json + components.json；目录不可达返回 null（降级 WARN） */
 function loadRoleLibrary(scene) {
+  const { dir: LIBRARY_DIR } = resolveLibraryDir();
   const merged = new Set();
+  if (!LIBRARY_DIR) return null;
   for (const f of [`${scene}.json`, "components.json"]) {
     const p = path.join(LIBRARY_DIR, f);
     if (!exists(p)) continue;
@@ -377,6 +441,159 @@ function checkCssRules(cssPathOf, contract, roleNames) {
   return missing;
 }
 
+// ────────────────────────────── 第 9 项：demo 内容泄漏（no-demo-leak）
+
+/** 通用 UI 词 —— 项目自身业务同样会用到，命中不计泄漏 */
+const GENERIC_WORDS = new Set([
+  "操作", "查看", "编辑", "删除", "新增", "修改", "保存", "取消", "确认", "确定",
+  "搜索", "查询", "重置", "刷新", "导入", "导出", "展开", "收起", "全选", "反选",
+  "状态", "类型", "时间", "名称", "编号", "序号", "备注", "图片", "地址", "金额",
+  "密度", "列设置", "批量删除", "批量导出", "全部", "启用", "停用", "更多",
+]);
+
+/** 承载演示文案的键名白名单（其余键是控件类型/变体/对齐/图标等形态值，不判） */
+const TEXT_KEYS = new Set([
+  "label", "title", "subtitle", "text", "placeholder", "total", "unit", "options",
+]);
+
+/** 整段演示数据的键名 —— 其下字符串全部视为演示内容 */
+const SAMPLE_KEYS = new Set(["rowsSampleOnly", "sampleRows", "sampleRowsOnly"]);
+
+/** 从契约 structure 收集 sampleOnly 演示文案：text -> 声明位置。
+ *  inSample 上下文必须穿透数组/对象层级向下传播 —— 整段演示数据（rowsSampleOnly 等）
+ *  内部无论嵌多深、键名叫什么，全部按演示内容处理。 */
+function collectDemoTexts(node, key, out, inSample = false) {
+  if (node === null || node === undefined) return out;
+  if (Array.isArray(node)) {
+    const here = inSample || SAMPLE_KEYS.has(key);
+    for (const item of node) collectDemoTexts(item, key, out, here);
+    return out;
+  }
+  if (typeof node === "object") {
+    const here = inSample || SAMPLE_KEYS.has(key);
+    for (const [k, v] of Object.entries(node)) collectDemoTexts(v, k, out, here);
+    return out;
+  }
+  if (typeof node !== "string") return out;
+  if (!inSample && !TEXT_KEYS.has(key)) return out;
+  const t = node.trim();
+  if (t.length < 2) return out;                                  // 单字符不判
+  if (/^[\d\s.,:%/+\-–—:]+$/.test(t)) return out;                // 纯数字/时间/标点不判
+  if (/^(M[\d.]|rect:|circle:)/.test(t)) return out;             // icon path 记法不判
+  if (GENERIC_WORDS.has(t)) return out;                          // 通用 UI 词不判
+  if (!out.has(t)) out.set(t, key);
+  return out;
+}
+
+function gitTry(projectRoot, args) {
+  try {
+    // 禁止刷新索引及调用项目配置的 fsmonitor，保持旧诊断只读。
+    return execSync(`git --no-optional-locks -c core.fsmonitor=false ${args}`, {
+      cwd: projectRoot,
+      encoding: "utf-8",
+      maxBuffer: 32 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+  } catch {
+    return null;
+  }
+}
+
+const SCANNABLE_EXT = new Set([...SOURCE_EXT, ...STYLE_EXT, ".json", ".md"]);
+
+/** 解析 git diff 输出 → [{ file, line }]（仅新增行，按文件归属） */
+function parseAddedLines(diffText) {
+  const out = [];
+  let file = null;
+  for (const raw of diffText.split("\n")) {
+    if (raw.startsWith("+++ b/")) {
+      file = raw.slice(6).trim();
+    } else if (raw.startsWith("+") && !raw.startsWith("+++")) {
+      if (file) out.push({ file, line: raw.slice(1).trim() });
+    }
+  }
+  return out;
+}
+
+/** 第 9 项：设计稿 demo 内容（sampleOnly 文案/数据）不得出现在项目新增代码里 */
+function checkDemoLeak(projectRoot, contract) {
+  const structure = contract && typeof contract.structure === "object" ? contract.structure : null;
+  if (!structure) {
+    return { status: "WARN", detail: "契约没有 structure 字段，无从提取演示文案，跳过本项", fix: null };
+  }
+  const demoTexts = collectDemoTexts(structure, "", new Map());
+  if (demoTexts.size === 0) {
+    return { status: "PASS", detail: "契约 structure 无可提取的演示文案，无需拦截", fix: null };
+  }
+
+  const insideRepo = gitTry(projectRoot, "rev-parse --is-inside-work-tree");
+  if (!insideRepo || insideRepo.trim() !== "true") {
+    return {
+      status: "WARN",
+      detail: `项目不是 git 仓库，无法定位新增代码做泄漏比对（已提取 ${demoTexts.size} 条演示文案）。请人工确认：项目里没有出现设计稿的文案/数据/演示页面`,
+      fix: null,
+    };
+  }
+
+  const leaks = [];
+  const isDesignDir = (f) => f.replace(/\\/g, "/").startsWith(".design/");
+
+  // ① untracked 文件：整份内容都在比对范围（设计稿整页被生成进项目就是这个形态）
+  const statusOut = gitTry(projectRoot, "status --porcelain");
+  if (statusOut) {
+    for (const raw of statusOut.split("\n")) {
+      if (!raw.startsWith("?? ")) continue;
+      let f = raw.slice(3).trim();
+      if (f.startsWith('"') && f.endsWith('"')) f = f.slice(1, -1);
+      f = f.replace(/\\/g, "/").replace(/\/$/, "");
+      if (isDesignDir(f)) continue;
+      const abs = path.join(projectRoot, f.replace(/\//g, path.sep));
+      let isFile = false;
+      try { isFile = fs.statSync(abs).isFile(); } catch { continue; }
+      const ext = path.extname(f).toLowerCase();
+      if (!isFile || !SCANNABLE_EXT.has(ext)) continue;
+      const content = readSafe(abs);
+      for (const [text, src] of demoTexts) {
+        if (content.includes(text)) leaks.push({ text, src, where: `${f}(untracked)` });
+      }
+    }
+  }
+
+  // ② 已跟踪文件的改动行：禁用外部 diff/textconv，避免执行项目配置的程序。
+  const diffOut = gitTry(projectRoot, "diff --no-ext-diff --no-textconv HEAD --unified=0");
+  if (diffOut) {
+    for (const { file, line } of parseAddedLines(diffOut)) {
+      if (isDesignDir(file)) continue;
+      const ext = path.extname(file).toLowerCase();
+      if (!SCANNABLE_EXT.has(ext)) continue;
+      for (const [text, src] of demoTexts) {
+        if (line.includes(text)) leaks.push({ text, src, where: `${file} +${line.slice(0, 60)}` });
+      }
+    }
+  }
+
+  if (leaks.length === 0) {
+    return {
+      status: "PASS",
+      detail: `已提取 ${demoTexts.size} 条演示文案，项目新增代码中零命中`,
+      fix: null,
+    };
+  }
+  // 同一文案多处泄漏只报一处
+  const seen = new Set();
+  const uniq = leaks.filter((l) => (seen.has(l.text) ? false : (seen.add(l.text), true)));
+  return {
+    status: "FAIL",
+    detail:
+      `拦截 ${uniq.length} 处设计稿 demo 内容泄漏: ` +
+      uniq.slice(0, 6).map((l) => `「${l.text}」← ${l.where}`).join("；") +
+      (uniq.length > 6 ? ` …等共 ${uniq.length} 处` : ""),
+    fix:
+      "把设计稿当需求在项目里开发了一遍 —— 删除泄漏的演示页面/演示数据/新注册的路由与菜单，" +
+      "把效果还原到项目既有业务页面上（锚点规则见 design-apply.md 第 6 步）。设计稿内容与文案是 demo，一个字都不进项目。",
+  };
+}
+
 // ────────────────────────────── 主流程
 
 function run(projectRoot) {
@@ -385,8 +602,7 @@ function run(projectRoot) {
     checks.push({ id, title, status, detail, fix });
 
   if (!exists(projectRoot)) {
-    console.error(`项目根目录不存在: ${projectRoot}`);
-    process.exit(EXIT_FAIL);
+    throw new Error(`项目根目录不存在: ${projectRoot}`);
   }
 
   // 1. 契约存在
@@ -435,12 +651,12 @@ function run(projectRoot) {
     structStatus === "PASS"
       ? `${parsed.roleNames.length} 个角色全部在角色库；regions 与 areas 一致（${parsed.info.areaCount} 个区域）；页面绑定无悬空引用`
       : structStatus === "WARN"
-        ? "角色库目录不可达，跳过「角色名在库」校验（regions↔areas 与页面绑定校验已通过）"
+        ? "角色库目录不可达，跳过「角色名在库」校验（regions↔areas 与页面绑定校验已通过）—— 分发形态下 project-ui-design 未与本项目技能同装属预期降级"
         : struct.problems.join("；"),
     structStatus === "FAIL"
       ? "设计侧结构违规 —— 回设计侧修正契约（角色名须在库、layout.regions 与 layout.areas 一致、绑定的区域名必须存在），重新出契约。"
       : structStatus === "WARN"
-        ? "确认技能包完整（project-ui-design/references/library 存在）后重跑。"
+        ? "预期降级，不阻断落地。如需启用角色白名单校验：将 project-ui-design 与 vue3-temp-skill 同级安装，或设置环境变量 UI_DESIGN_LIBRARY_DIR 指向 project-ui-design/references/library 后重跑。"
         : null
   );
   if (structStatus === "FAIL") {
@@ -481,21 +697,26 @@ function run(projectRoot) {
     );
   }
 
-  // 6. 角色类挂载
-  const mount = checkMounting(projectRoot, parsed.roleNames);
-  const mountRatio = parsed.roleNames.length
-    ? mount.mounted.length / parsed.roleNames.length
-    : 0;
+  // 6. 角色类挂载 —— 必需集 = 页面绑定（nodes/regions）引用的角色；
+  //    契约角色库大于单页用量时（可选复用角色），未引用角色的缺失只提示不计入告警
+  const requiredRoleSet = boundRoles(contract);
+  const mount = checkMounting(projectRoot, parsed.roleNames, requiredRoleSet);
+  const optionalCount = mount.optionalMounted + mount.optionalMissing.length;
+  const requiredTotal = parsed.roleNames.length - optionalCount;
+  const requiredMounted = mount.mounted.length - mount.optionalMounted;
   add(
     "roles-mounted",
     "角色类挂到模板上",
-    mount.mounted.length === parsed.roleNames.length ? "PASS"
+    mount.missing.length === 0 ? "PASS"
       : mount.mounted.length === 0 ? "FAIL" : "WARN",
-    `契约 ${parsed.roleNames.length} 个角色，模板挂载 ${mount.mounted.length} 个（覆盖率 ${(mountRatio * 100).toFixed(0)}%）；扫描 ${mount.scannedFileCount} 个源文件`,
+    `契约 ${parsed.roleNames.length} 个角色（页面绑定引用 ${requiredTotal} 个为必需，已挂载 ${requiredMounted} 个）；扫描 ${mount.scannedFileCount} 个源文件` +
+      (mount.optionalMissing.length
+        ? `；未引用可选角色缺失 ${mount.optionalMissing.length} 个（${mount.optionalMissing.slice(0, 4).map((s) => s.split(" ")[0]).join("、")}${mount.optionalMissing.length > 4 ? "…" : ""}），不影响落地`
+        : ""),
     mount.mounted.length === 0
       ? "没有任何 .vue 文件出现 role-* 类名 —— 三份 CSS 全是死样式（写了规则但没元素承载）。按 adapter 的挂载映射给组件加 class。"
       : mount.missing.length
-        ? `未挂载 ${mount.missing.length} 个角色（CSS 已生成但页面上没有对应 class，视觉不会变）: ${mount.missing.slice(0, 6).join(" | ")}${mount.missing.length > 6 ? " …" : ""}`
+        ? `必需角色未挂载 ${mount.missing.length} 个（CSS 已生成但页面上没有对应 class，视觉不会变）: ${mount.missing.slice(0, 6).join(" | ")}${mount.missing.length > 6 ? " …" : ""}`
         : null
   );
 
@@ -526,51 +747,76 @@ function run(projectRoot) {
     );
   }
 
-  const ok = checks.every((c) => c.status === "PASS");
+  // 9. demo 内容泄漏（设计稿 sampleOnly 文案/数据不得进项目）
+  const leak = checkDemoLeak(projectRoot, contract);
+  add(
+    "no-demo-leak",
+    "设计稿 demo 内容未泄漏进项目",
+    leak.status,
+    leak.detail,
+    leak.fix
+  );
+
+  const ok = checks.every((c) => c.status !== "FAIL");
   return { checks, ok, projectRoot, contractInfo: parsed.info, mount };
 }
 
 // ────────────────────────────── 输出
 
 function printHuman(result) {
-  const L = [];
-  L.push("");
-  L.push("契约落地自检");
-  L.push("=".repeat(64));
-  L.push(`项目根: ${result.projectRoot}`);
-  L.push("");
-  const mark = { PASS: "PASS", WARN: "WARN", FAIL: "FAIL" };
+  const L = [result.notice];
+  if (result.projectRoot) L.push(`项目根: ${result.projectRoot}`);
+  if (result.reason) L.push(result.reason);
+  if (result.error) L.push(`错误: ${result.error}`);
   for (const c of result.checks) {
-    L.push(`[${mark[c.status]}] ${c.id} · ${c.title}`);
+    L.push(`[LEGACY-TEXT-${c.status}] ${c.id} · ${c.title}`);
     if (c.detail) L.push(`        ${c.detail}`);
-    if (c.fix) L.push(`        修复 → ${c.fix}`);
-  }
-  L.push("");
-  L.push("-".repeat(64));
-  const firstFail = result.checks.find((c) => c.status === "FAIL");
-  if (result.ok) {
-    L.push("结论: 八项全过 —— 契约、结构、样式、挂载闭环均已接通。");
-  } else if (firstFail) {
-    L.push(`结论: 断在「${firstFail.title}」。先修这一项，重跑本脚本看下一项。`);
-    L.push("");
-    L.push("提醒: 项目侧的修正动作是「改契约或改 adapter 后重新生成」,");
-    L.push("      不要直接改已生成的 CSS —— 下次重新生成会被覆盖。");
-  } else {
-    L.push("结论: 有 WARN 项，落地链路未全覆盖。");
+    if (c.fix) L.push(`        旧格式建议（非当前实施指令） → ${c.fix}`);
   }
-  L.push("");
+  if (result.diagnosticOk) {
+    L.push("旧格式文本检查未发现 FAIL；这不证明业务正确、无 demo 泄漏或视觉还原。");
+  }
+  L.push(result.migration);
+  L.push("visualStatus=unverified；退出 2，不提供验收通过结论。");
   process.stdout.write(L.join("\n") + "\n");
 }
 
-function main() {
-  const args = parseArgs(process.argv.slice(2));
-  const result = run(args.project);
-  if (args.json) {
+export function main(argv = process.argv.slice(2)) {
+  const result = {
+    mode: "disabled",
+    ok: false,
+    visualStatus: "unverified",
+    notice: NOTICE,
+    migration: MIGRATION,
+    checks: [],
+  };
+  let json = argv.includes("--json");
+  try {
+    const args = parseArgs(argv);
+    json = args.json;
+    if (args.help) {
+      console.log(HELP);
+      return EXIT_OK;
+    }
+    if (args.legacyDiagnostics) {
+      result.mode = "legacy-diagnostics";
+      const { ok: diagnosticOk, ...diagnostic } = run(args.project);
+      Object.assign(result, diagnostic, { diagnosticOk });
+    } else {
+      result.reason = "默认不读取项目；只有显式 --legacy-diagnostics 才运行旧的只读文本诊断。";
+    }
+  } catch (error) {
+    result.error = error.message;
+    result.diagnosticOk = false;
+  }
+  if (json) {
     console.log(JSON.stringify(result, null, 2));
   } else {
     printHuman(result);
   }
-  process.exit(result.ok ? EXIT_OK : EXIT_FAIL);
+  return EXIT_UNVERIFIED;
 }
 
-main();
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.exitCode = main();
+}