@qilitt-mickey/vue3-temp-skill 1.2.1 → 1.2.4

package/scripts/check-landing.mjs

@@ -0,0 +1,576 @@
+#!/usr/bin/env node
+
+/**
+ * 契约落地自检 —— 判断「契约 → 样式 → 挂载」三个闭环在哪一环断了
+ *
+ * 用法:
+ *   node check-landing.mjs --project <项目根目录>
+ *   node check-landing.mjs --project . --json
+ *
+ * 退出码: 0 = 八项全过 / 1 = 有 FAIL 项
+ *
+ * 设计原则: 纯读取 + 确定性判断。不猜测、不修改、不联网。
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const IGNORE_DIRS = new Set([
+  "node_modules", "dist", ".git", ".vite", "coverage",
+  "__pycache__", ".idea", ".vscode", ".workbuddy", "unpackage",
+]);
+
+const CSS_FILES = ["ui-tokens.css", "ui-roles.css", "ui-layout.css"];
+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;
+
+// ────────────────────────────── 参数解析
+
+function parseArgs(argv) {
+  const out = { project: process.cwd(), json: 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);
+      }
+      out.project = path.resolve(v);
+      i++;
+    } else if (a === "--json") {
+      out.json = true;
+    } else if (a === "--help" || a === "-h") {
+      console.log("用法: node check-landing.mjs --project <项目根目录> [--json]");
+      process.exit(EXIT_OK);
+    }
+  }
+  return out;
+}
+
+// ────────────────────────────── 文件遍历
+
+function walk(dir, extSet, acc = []) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return acc;
+  }
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      if (IGNORE_DIRS.has(e.name)) continue;
+      walk(path.join(dir, e.name), extSet, acc);
+    } else if (e.isFile()) {
+      if (extSet === null || extSet.has(path.extname(e.name).toLowerCase())) {
+        acc.push(path.join(dir, e.name));
+      }
+    }
+  }
+  return acc;
+}
+
+function readSafe(p) {
+  try {
+    return fs.readFileSync(p, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+function rel(root, p) {
+  return path.relative(root, p).split(path.sep).join("/");
+}
+
+function exists(p) {
+  try {
+    fs.statSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ────────────────────────────── 契约侧
+
+function findContract(projectRoot) {
+  const designDir = path.join(projectRoot, ".design");
+  if (!exists(designDir)) return { file: null, reason: "项目根下没有 .design/ 目录" };
+
+  let names;
+  try {
+    names = fs.readdirSync(designDir);
+  } catch {
+    return { file: null, reason: ".design/ 目录无法读取" };
+  }
+  const hit = names.find((n) => /^visual-contract.*\.json$/.test(n));
+  if (!hit) {
+    return { file: null, reason: ".design/ 下没有 visual-contract-*.json" };
+  }
+  return { file: path.join(designDir, hit), name: hit, reason: null };
+}
+
+function inspectContract(contract) {
+  const problems = [];
+  const warns = [];
+  const info = {};
+
+  if (!contract || typeof contract !== "object") {
+    return { ok: false, problems: ["契约内容不是合法 JSON 对象"], warns, info };
+  }
+
+  info.schema = contract.schema || "(缺失)";
+  if (contract.schema !== "ui.visual-contract/1.0") {
+    warns.push(`schema 是 "${contract.schema}"，期望 "ui.visual-contract/1.0"`);
+  }
+
+  const meta = contract.meta || {};
+  info.scene = meta.scene || "(缺失)";
+  info.pageTypes = Array.isArray(meta.pageTypes) ? meta.pageTypes.join(",") : "(缺失)";
+  info.mockup = (meta.source && meta.source.mockup) || "(缺失)";
+  if (!meta.scene) problems.push("meta.scene 缺失 —— 项目侧无法判断用哪套角色与布局预期");
+  if (!meta.source || !meta.source.mockup) {
+    problems.push("meta.source.mockup 缺失 —— 目视对照没有比对目标");
+  }
+
+  const colorTokens = (contract.tokens && contract.tokens.color) || {};
+  info.tokenCount = Object.keys(colorTokens).length;
+  if (info.tokenCount === 0) problems.push("tokens.color 为空 —— 令牌层没有值");
+
+  const roles = contract.roles && typeof contract.roles === "object" ? contract.roles : {};
+  const roleNames = Object.keys(roles);
+  info.roleCount = roleNames.length;
+  const emptyRoles = roleNames.filter((n) => {
+    const r = roles[n] || {};
+    const hasHost = Array.isArray(r.host) && r.host.length > 0;
+    const hasInner = Array.isArray(r.inner) && r.inner.length > 0;
+    return !hasHost && !hasInner;
+  });
+  info.emptyRoles = emptyRoles;
+  if (roleNames.length === 0) {
+    problems.push("roles 为空 —— 角色层没抽出来，三份 CSS 只能生成空壳");
+  } else if (emptyRoles.length > 0) {
+    problems.push(`这些角色没有任何声明: ${emptyRoles.join(", ")}`);
+  }
+  if (roleNames.length > 0 && roleNames.length < 5) {
+    warns.push(`契约只有 ${roleNames.length} 个角色，很可能设计侧抽取不完整（一页通常 20+ 个角色）`);
+  }
+
+  const layout = contract.layout || {};
+  const areas = Array.isArray(layout.areas) ? layout.areas : [];
+  info.areaCount = areas.length;
+  info.grid = layout.grid || "(缺失)";
+  if (areas.length === 0) {
+    problems.push("layout.areas 为空 —— 布局层没定，骨架无法生成");
+  }
+
+  const pages = contract.pages || {};
+  info.pageTypesDeclared = Object.keys(pages).join(",");
+  if (Object.keys(pages).length === 0) {
+    warns.push("pages 为空 —— 没有区域到角色的绑定，区域内部不知道该用什么角色");
+  }
+
+  return { ok: problems.length === 0, problems, warns, info, roleNames };
+}
+
+// ────────────────────────────── CSS 侧
+
+function findGeneratedCss(projectRoot) {
+  const found = { files: [], pathOf: {} };
+  const allFiles = walk(projectRoot, null, []);
+  for (const name of CSS_FILES) {
+    const hits = allFiles.filter((p) => path.basename(p) === name);
+    if (hits.length > 0) {
+      found.files.push(hits[0]);
+      found.pathOf[name] = hits[0];
+    }
+  }
+  return found;
+}
+
+function checkImported(projectRoot, cssFileAbs) {
+  const base = path.basename(cssFileAbs);
+  const sources = walk(projectRoot, SOURCE_EXT, []);
+  const refs = [];
+  for (const s of sources) {
+    const content = readSafe(s);
+    if (content.includes(base)) refs.push(rel(projectRoot, s));
+  }
+  const styleRefs = [];
+  for (const s of walk(projectRoot, STYLE_EXT, [])) {
+    if (path.basename(s) === base) continue;
+    const content = readSafe(s);
+    if (content.includes(base)) styleRefs.push(rel(projectRoot, s));
+  }
+  return { imported: refs.length > 0 || styleRefs.length > 0, refs, styleRefs };
+}
+
+// ────────────────────────────── 挂载侧
+
+function expectedClassName(roleName) {
+  return (
+    "role-" +
+    roleName
+      .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+      .replace(/\./g, "-")
+      .replace(/_/g, "-")
+      .toLowerCase()
+  );
+}
+
+function checkMounting(projectRoot, roleNames) {
+  const vueFiles = walk(projectRoot, SOURCE_EXT, []);
+  const roleClassRe = /\brole-[a-z0-9]+(?:-[a-z0-9]+)*/g;
+  const usedClasses = new Map();
+  for (const s of vueFiles) {
+    const content = readSafe(s);
+    const hits = content.match(roleClassRe);
+    if (!hits) continue;
+    for (const h of hits) {
+      if (!usedClasses.has(h)) usedClasses.set(h, new Set());
+      usedClasses.get(h).add(rel(projectRoot, s));
+    }
+  }
+
+  const expected = roleNames.map(expectedClassName);
+  const mounted = [];
+  const missing = [];
+  for (let i = 0; i < roleNames.length; i++) {
+    if (usedClasses.has(expected[i])) mounted.push(expected[i]);
+    else missing.push(`${roleNames[i]} → .${expected[i]}`);
+  }
+
+  const layoutClassRe = /\bui-(?:page|region-[a-z0-9]+(?:-[a-z0-9]+)*)\b/g;
+  const layoutClasses = new Set();
+  for (const s of vueFiles) {
+    const content = readSafe(s);
+    const hits = content.match(layoutClassRe);
+    if (hits) for (const h of hits) layoutClasses.add(h);
+  }
+
+  return {
+    scannedFileCount: vueFiles.length,
+    mounted,
+    missing,
+    layoutClasses: [...layoutClasses],
+    hasLayout: layoutClasses.has("ui-page"),
+  };
+}
+
+// ────────────────────────────── 结构校验（契约 §7）
+
+const LIBRARY_DIR = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../../project-ui-design/references/library"
+);
+
+/** 加载角色库名集合：<场景>.json + components.json；目录不可达返回 null（降级 WARN） */
+function loadRoleLibrary(scene) {
+  const merged = new Set();
+  for (const f of [`${scene}.json`, "components.json"]) {
+    const p = path.join(LIBRARY_DIR, f);
+    if (!exists(p)) continue;
+    try {
+      const lib = JSON.parse(readSafe(p));
+      for (const k of Object.keys(lib.roles || {})) merged.add(k);
+    } catch {
+      /* 单个角色库文件损坏时跳过，由调用方按降级处理 */
+    }
+  }
+  return merged.size > 0 ? merged : null;
+}
+
+/** 契约 §7 结构四条中可机判的三条：角色名在库 / regions↔areas 一致 / 绑定区域存在 */
+function checkContractStructure(contract, roleNames, library) {
+  const problems = [];
+
+  if (library) {
+    const unknown = roleNames.filter((n) => !library.has(n));
+    if (unknown.length > 0) {
+      problems.push(`角色不在角色库: ${unknown.join(", ")}`);
+    }
+  }
+
+  const layout = contract.layout || {};
+  const areaNames = (Array.isArray(layout.areas) ? layout.areas : [])
+    .map((a) => a && a.name)
+    .filter(Boolean);
+  const areasSet = new Set(areaNames);
+  const regionKeys = Object.keys(layout.regions || {});
+  const onlyRegions = regionKeys.filter((k) => !areasSet.has(k));
+  const onlyAreas = areaNames.filter((n) => !regionKeys.includes(n));
+  if (onlyRegions.length > 0) {
+    problems.push(`layout.regions 有而 layout.areas 没有: ${onlyRegions.join(", ")}`);
+  }
+  if (onlyAreas.length > 0) {
+    problems.push(`layout.areas 有而 layout.regions 没有: ${onlyAreas.join(", ")}`);
+  }
+
+  const pages = contract.pages || {};
+  for (const [pt, page] of Object.entries(pages)) {
+    const p = page || {};
+    for (const b of Array.isArray(p.regions) ? p.regions : []) {
+      if (b && b.region && !areasSet.has(b.region)) {
+        problems.push(`pages.${pt}.regions 绑定了不存在的区域: ${b.region}`);
+      }
+    }
+    for (const nd of Array.isArray(p.nodes) ? p.nodes : []) {
+      if (nd && nd.in && !areasSet.has(nd.in)) {
+        problems.push(`pages.${pt}.nodes 绑定了不存在的区域: ${nd.in}`);
+      }
+    }
+  }
+  return { problems };
+}
+
+// ────────────────────────────── CSS 规则完整性
+
+/** 逐条核对：ui-roles 含每个角色类、ui-layout 含每个区域类、ui-tokens 含每个令牌变量 */
+function checkCssRules(cssPathOf, contract, roleNames) {
+  const missing = [];
+
+  const rolesCss = readSafe(cssPathOf["ui-roles.css"] || "");
+  if (rolesCss) {
+    for (const rn of roleNames) {
+      const cls = "." + expectedClassName(rn);
+      if (!rolesCss.includes(cls)) missing.push(`ui-roles.css 缺 ${cls}`);
+    }
+  } else {
+    missing.push("ui-roles.css 无法读取");
+  }
+
+  const layoutCss = readSafe(cssPathOf["ui-layout.css"] || "");
+  if (layoutCss) {
+    const areas = Array.isArray(contract.layout && contract.layout.areas)
+      ? contract.layout.areas
+      : [];
+    for (const a of areas) {
+      if (!a || !a.name) continue;
+      const cls = `.ui-region-${a.name}`;
+      if (!layoutCss.includes(cls)) missing.push(`ui-layout.css 缺 ${cls}`);
+    }
+  } else {
+    missing.push("ui-layout.css 无法读取");
+  }
+
+  const tokensCss = readSafe(cssPathOf["ui-tokens.css"] || "");
+  if (tokensCss) {
+    const tokens = contract.tokens || {};
+    for (const [family, names] of Object.entries(tokens)) {
+      if (!names || typeof names !== "object") continue;
+      for (const n of Object.keys(names)) {
+        const v = `--${family}-${String(n).replace(/\./g, "-")}`;
+        const alt = `--${family}-${String(n).replace(/\./g, "_")}`;
+        if (!tokensCss.includes(v) && !tokensCss.includes(alt)) {
+          missing.push(`ui-tokens.css 缺 ${v}`);
+        }
+      }
+    }
+  } else {
+    missing.push("ui-tokens.css 无法读取");
+  }
+
+  return missing;
+}
+
+// ────────────────────────────── 主流程
+
+function run(projectRoot) {
+  const checks = [];
+  const add = (id, title, status, detail, fix) =>
+    checks.push({ id, title, status, detail, fix });
+
+  if (!exists(projectRoot)) {
+    console.error(`项目根目录不存在: ${projectRoot}`);
+    process.exit(EXIT_FAIL);
+  }
+
+  // 1. 契约存在
+  const cf = findContract(projectRoot);
+  if (!cf.file) {
+    add("contract-found", "契约文件存在", "FAIL", cf.reason,
+      "设计侧没有落盘契约。检查是否在项目根目录运行、是否完成了第 6 步「出契约」。");
+    return { checks, ok: false, projectRoot };
+  }
+  add("contract-found", "契约文件存在", "PASS", `.design/${cf.name}`, null);
+
+  // 2. 契约完整
+  let contract = null;
+  let parsed = null;
+  try {
+    contract = JSON.parse(readSafe(cf.file));
+  } catch (e) {
+    add("contract-valid", "契约内容完整", "FAIL", `JSON 解析失败: ${e.message}`,
+      "契约是手工编辑过的吗？重新用设计侧生成一份。");
+    return { checks, ok: false, projectRoot };
+  }
+  parsed = inspectContract(contract);
+  add(
+    "contract-valid",
+    "契约内容完整",
+    parsed.ok ? "PASS" : "FAIL",
+    `场景=${parsed.info.scene} 页型=${parsed.info.pageTypes} 角色=${parsed.info.roleCount} 区域=${parsed.info.areaCount}`,
+    parsed.problems.length ? parsed.problems.join("；") : null
+  );
+  for (const w of parsed.warns || []) {
+    add(`contract-warn-${checks.length}`, "契约告警", "WARN", w, null);
+  }
+  if (!parsed.ok) {
+    return { checks, ok: false, projectRoot, contractInfo: parsed.info };
+  }
+
+  // 3. 契约结构（角色名在库 / regions↔areas 一致 / 页面绑定不悬空）
+  const library = loadRoleLibrary(parsed.info.scene);
+  const struct = checkContractStructure(contract, parsed.roleNames, library);
+  const structStatus =
+    struct.problems.length > 0 ? "FAIL" : library ? "PASS" : "WARN";
+  add(
+    "contract-structure",
+    "契约结构符合角色库与布局约束",
+    structStatus,
+    structStatus === "PASS"
+      ? `${parsed.roleNames.length} 个角色全部在角色库；regions 与 areas 一致（${parsed.info.areaCount} 个区域）；页面绑定无悬空引用`
+      : structStatus === "WARN"
+        ? "角色库目录不可达，跳过「角色名在库」校验（regions↔areas 与页面绑定校验已通过）"
+        : struct.problems.join("；"),
+    structStatus === "FAIL"
+      ? "设计侧结构违规 —— 回设计侧修正契约（角色名须在库、layout.regions 与 layout.areas 一致、绑定的区域名必须存在），重新出契约。"
+      : structStatus === "WARN"
+        ? "确认技能包完整（project-ui-design/references/library 存在）后重跑。"
+        : null
+  );
+  if (structStatus === "FAIL") {
+    return { checks, ok: false, projectRoot, contractInfo: parsed.info };
+  }
+
+  // 4. 三份 CSS 生成
+  const css = findGeneratedCss(projectRoot);
+  const missingCss = CSS_FILES.filter((n) => !css.pathOf[n]);
+  add(
+    "css-generated",
+    "三份 CSS 已生成",
+    missingCss.length === 0 ? "PASS" : "FAIL",
+    missingCss.length === 0
+      ? CSS_FILES.map((n) => rel(projectRoot, css.pathOf[n])).join("  ")
+      : `缺: ${missingCss.join(", ")}`,
+    missingCss.length
+      ? "项目侧未完成第 3/4/5 步。按 design-apply.md 的翻译规则生成这三份文件。"
+      : null
+  );
+  if (missingCss.length === 0) {
+    // 5. CSS 被引入
+    const unimported = [];
+    const importDetail = [];
+    for (const n of CSS_FILES) {
+      const r = checkImported(projectRoot, css.pathOf[n]);
+      if (!r.imported) unimported.push(n);
+      importDetail.push(`${n}:${r.imported ? "已引入 " + (r.refs[0] || r.styleRefs[0]) : "未引入"}`);
+    }
+    add(
+      "css-imported",
+      "三份 CSS 被入口引入",
+      unimported.length === 0 ? "PASS" : "FAIL",
+      importDetail.join("  |  "),
+      unimported.length
+        ? `${unimported.join(", ")} 生成了但没被任何文件 import —— 浏览器不会加载它们。在样式入口 import 一次。`
+        : null
+    );
+  }
+
+  // 6. 角色类挂载
+  const mount = checkMounting(projectRoot, parsed.roleNames);
+  const mountRatio = parsed.roleNames.length
+    ? mount.mounted.length / parsed.roleNames.length
+    : 0;
+  add(
+    "roles-mounted",
+    "角色类挂到模板上",
+    mount.mounted.length === parsed.roleNames.length ? "PASS"
+      : mount.mounted.length === 0 ? "FAIL" : "WARN",
+    `契约 ${parsed.roleNames.length} 个角色，模板挂载 ${mount.mounted.length} 个（覆盖率 ${(mountRatio * 100).toFixed(0)}%）；扫描 ${mount.scannedFileCount} 个源文件`,
+    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 ? " …" : ""}`
+        : null
+  );
+
+  // 7. 布局类挂载
+  add(
+    "layout-mounted",
+    "布局类挂到容器上",
+    mount.hasLayout ? "PASS" : "FAIL",
+    mount.hasLayout
+      ? `布局类: ${mount.layoutClasses.join(", ")}`
+      : "没有任何 .vue 文件出现 .ui-page —— 布局层未接入，骨架仍是项目原有结构",
+    mount.hasLayout ? null : "布局组件需加 .ui-page 与 .ui-region-* 类，见 adapter 的「布局占位容器」。"
+  );
+
+  // 8. CSS 规则完整性（模板挂了类但 CSS 没规则 = 生成不完整或被手改）
+  if (missingCss.length === 0) {
+    const missingRules = checkCssRules(css.pathOf, contract, parsed.roleNames);
+    add(
+      "css-rules",
+      "CSS 规则覆盖契约全部声明",
+      missingRules.length === 0 ? "PASS" : "FAIL",
+      missingRules.length === 0
+        ? `ui-tokens / ui-roles / ui-layout 已覆盖契约全部令牌、${parsed.info.roleCount} 个角色与 ${parsed.info.areaCount} 个区域`
+        : `缺 ${missingRules.length} 条: ${missingRules.slice(0, 8).join(" | ")}${missingRules.length > 8 ? " …" : ""}`,
+      missingRules.length
+        ? "模板挂了类但 CSS 里没有对应规则 —— 生成不完整或生成后被手工改动。回第 3/4/5 步重新生成，禁止手补 CSS。"
+        : null
+    );
+  }
+
+  const ok = checks.every((c) => c.status === "PASS");
+  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" };
+  for (const c of result.checks) {
+    L.push(`[${mark[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 项，落地链路未全覆盖。");
+  }
+  L.push("");
+  process.stdout.write(L.join("\n") + "\n");
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const result = run(args.project);
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printHuman(result);
+  }
+  process.exit(result.ok ? EXIT_OK : EXIT_FAIL);
+}
+
+main();