@qilitt-mickey/vue3-temp-skill 1.1.34 → 1.1.35

package/scripts/field-schema-audit.mjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+/**
+ * field-schema-audit — 协议字段对账闸门
+ *
+ * 目的：项目技能（design-handoff.md）里每一条「JSON 来源」引用必须与
+ *       设计协议（handoff-output.md）schema 中真实存在的字段一一对应。
+ *       引用了协议未定义的字段 = 幽灵字段（ghost），会让校验闸门对照空气、
+ *       逼 AI 瞎猜，是还原度上不去的底层硬伤。
+ *
+ * 原理（确定性、可复现，不以独立 manifest 为真值源，避免漂移）：
+ *   1. 以「设计协议文档本身」为唯一真值源：解析文档内 ```json 实例块
+ *      （§2 总览 + §6 完整示例），递归收集所有真实点分路径 → definedPaths。
+ *   2. 从项目技能文档提取所有反引号包裹的 `xxx.yyy` 引用路径，并过滤掉
+ *      非 JSON 路径（文件名如 dark.scss / 选择器如 html.dark / CSS 段名），
+ *      只保留「首段 ∈ 协议顶层 key ∪ 已知简写根」的引用 → referencedPaths。
+ *   3. 双向比对：
+ *        - ghost   = 被引用但 definedPaths 中不存在           → 硬失败（exit 1）
+ *        - unused  = 协议定义但项目技能未引用（多为可选/推荐字段）→ 仅告警
+ *
+ * 匹配规则（容忍项目技能里的简写 / 父级引用）：
+ *   引用 R 被视为「已覆盖」当且仅当存在定义路径 D 满足：
+ *     D === R                                  （精确匹配）
+ *     D.startsWith(R + ".")                   （R 是父级，如 interactionSpecs.menuActive → .fullWidth）
+ *     D.endsWith("." + R)                     （R 是简写，如 frameworkShell.header → structureRequirements.frameworkShell.header）
+ *
+ * 用法：
+ *   node scripts/field-schema-audit.mjs
+ *   node scripts/field-schema-audit.mjs <schema.md> <project.md>
+ *   node scripts/field-schema-audit.mjs --json      # 机器可读摘要
+ *
+ * 退出码：发现 ghost → 1（可接入发布闸门）；否则 0。
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SKILL_ROOT = path.resolve(__dirname, "..");
+
+// 默认值：设计协议在兄弟技能 project-ui-design 下；项目技能在本技能 references 下
+const DEFAULT_SCHEMA = path.resolve(SKILL_ROOT, "..", "project-ui-design", "references", "handoff-output.md");
+const DEFAULT_PROJECT = path.resolve(SKILL_ROOT, "references", "design-handoff.md");
+
+// 项目技能中使用的「简写根」→ 协议中的完整前缀
+const SHORTHANDS = {
+  frameworkShell: "structureRequirements.frameworkShell",
+};
+
+function parseArgs(argv) {
+  const opts = { json: false, positional: [] };
+  for (const a of argv) {
+    if (a === "--json") opts.json = true;
+    else if (a === "--help" || a === "-h") opts.help = true;
+    else opts.positional.push(a);
+  }
+  const schema = opts.positional[0] || DEFAULT_SCHEMA;
+  const project = opts.positional[1] || DEFAULT_PROJECT;
+  return { schema, project, json: opts.json, help: opts.help };
+}
+
+/** 递归收集对象的所有点分路径（含中间节点）。数组取首个元素代表。 */
+function walk(prefix, val, out) {
+  if (val && typeof val === "object" && !Array.isArray(val)) {
+    for (const k of Object.keys(val)) {
+      const p = prefix ? `${prefix}.${k}` : k;
+      out.add(p);
+      walk(p, val[k], out);
+    }
+  } else if (Array.isArray(val)) {
+    if (prefix) out.add(prefix); // 数组本身也是一条路径（如 pageStructure.regions）
+    if (val.length) walk(prefix, val[0], out);
+  } else if (prefix) {
+    out.add(prefix);
+  }
+}
+
+/** 从协议文档解析所有 ```json 实例块，汇总真实字段路径集合 + 顶层根集合。 */
+function extractDefinedPaths(md) {
+  const paths = new Set();
+  const re = /```json\s*([\s\S]*?)```/g;
+  let m;
+  let blocks = 0;
+  while ((m = re.exec(md)) !== null) {
+    blocks++;
+    const text = m[1];
+    try {
+      const obj = JSON.parse(text);
+      walk("", obj, paths);
+    } catch {
+      // 单块解析失败时退化为逐行提取裸 key（容错，不阻塞整体）
+      const keyRe = /"([A-Za-z_][\w]*)\s*"/g;
+      let km;
+      while ((km = keyRe.exec(text)) !== null) paths.add(km[1]);
+    }
+  }
+  const roots = new Set();
+  for (const p of paths) roots.add(p.split(".")[0]);
+  return { paths, roots, blocks };
+}
+
+/** 从项目技能文档提取所有反引号包裹的点分路径，过滤非 JSON 路径（文件名/CSS 选择器等）。 */
+function extractReferencedPaths(md, validRoots) {
+  const raw = new Set();
+  const re = /`([A-Za-z][\w]*(?:\.[\w]+)+)`/g;
+  let m;
+  while ((m = re.exec(md)) !== null) raw.add(m[1]);
+
+  const out = new Set();
+  for (const r of raw) {
+    const root = r.split(".")[0];
+    // 只保留「首段是协议顶层 key 或已知简写根」的引用，剔除 dark.scss / html.dark 等
+    if (validRoots.has(root) || Object.prototype.hasOwnProperty.call(SHORTHANDS, root)) {
+      out.add(r);
+    }
+  }
+  return out;
+}
+
+/** 将简写根展开为协议完整前缀（frameworkShell → structureRequirements.frameworkShell）。 */
+function normalize(ref) {
+  const segs = ref.split(".");
+  if (Object.prototype.hasOwnProperty.call(SHORTHANDS, segs[0])) {
+    return SHORTHANDS[segs[0]] + "." + segs.slice(1).join(".");
+  }
+  return ref;
+}
+
+/** R 是否被定义路径集合覆盖（精确 / 父级 / 简写后缀）。入参均已 normalize。 */
+function isCovered(ref, defined) {
+  for (const d of defined) {
+    if (d === ref) return true;
+    if (d.startsWith(ref + ".")) return true;
+    if (d.endsWith("." + ref)) return true;
+  }
+  return false;
+}
+
+/** 为 ghost 字段提供「可能想写的真实字段」建议（末段 / 次段 / 子串命中）。 */
+function suggest(ref, defined) {
+  const segs = ref.split(".");
+  const leaf = segs[segs.length - 1];
+  const parent = segs.length > 1 ? segs[segs.length - 2] : "";
+  const hits = new Set();
+  for (const d of defined) {
+    const ds = d.split(".");
+    if (ds[ds.length - 1] === leaf) hits.add(d);
+    else if (parent && ds.includes(parent)) hits.add(d);
+    else if (ds[ds.length - 1].includes(leaf) && leaf.length >= 4) hits.add(d); // 子串兜底（leaf 足够长避免误命中）
+  }
+  return [...hits].slice(0, 4);
+}
+
+function main() {
+  const { schema, project, json, help } = parseArgs(process.argv.slice(2));
+
+  if (help) {
+    console.log("field-schema-audit — 协议字段对账");
+    console.log("用法: node scripts/field-schema-audit.mjs [schema.md] [project.md] [--json]");
+    process.exit(0);
+  }
+
+  if (!fs.existsSync(schema)) {
+    console.error(`x 设计协议文件不存在: ${schema}`);
+    process.exit(1);
+  }
+  if (!fs.existsSync(project)) {
+    console.error(`x 项目技能文件不存在: ${project}`);
+    process.exit(1);
+  }
+
+  const schemaMd = fs.readFileSync(schema, "utf-8");
+  const projectMd = fs.readFileSync(project, "utf-8");
+
+  const { paths: defined, roots, blocks } = extractDefinedPaths(schemaMd);
+  const validRoots = new Set([...roots, ...Object.keys(SHORTHANDS)]);
+  const referencedRaw = extractReferencedPaths(projectMd, validRoots);
+  const referenced = new Set([...referencedRaw].map(normalize));
+
+  const ghosts = [];
+  const covered = [];
+  for (const r of [...referenced].sort()) {
+    if (isCovered(r, defined)) covered.push(r);
+    else ghosts.push(r);
+  }
+
+  const unused = [...defined].filter((d) => {
+    for (const r of referenced) {
+      if (d === r || d.startsWith(r + ".") || d.endsWith("." + r)) return false;
+    }
+    return true;
+  });
+
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          schemaFile: schema,
+          projectFile: project,
+          jsonBlocksParsed: blocks,
+          definedCount: defined.size,
+          referencedCount: referenced.size,
+          ghosts,
+          ghostCount: ghosts.length,
+          unusedCount: unused.length,
+          ok: ghosts.length === 0,
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    console.log("=".repeat(60));
+    console.log("协议字段对账 — field-schema-audit");
+    console.log("=".repeat(60));
+    console.log(`协议文档   : ${schema}`);
+    console.log(`项目技能   : ${project}`);
+    console.log(`JSON 实例块: ${blocks} 个已解析`);
+    console.log(`协议字段数 : ${defined.size}`);
+    console.log(`引用字段数 : ${referenced.size}`);
+    console.log("");
+
+    if (ghosts.length === 0) {
+      console.log(`OK 幽灵字段: 0 — 项目技能所有 xxx.yyy 引用均在协议中定义`);
+    } else {
+      console.log(`FAIL 幽灵字段: ${ghosts.length} 个（被引用但协议未定义，硬失败）`);
+      console.log("-".repeat(60));
+      for (const g of ghosts) {
+        const sug = suggest(g, defined);
+        const hint = sug.length ? `  -> 可能应为: ${sug.join(" / ")}` : "";
+        console.log(`  x ${g}${hint}`);
+      }
+    }
+
+    console.log("");
+    console.log(`~ 未引用字段（协议定义但项目技能未消费，多为可选/推荐，仅提示）: ${unused.length} 个`);
+    if (unused.length) {
+      console.log("  " + unused.sort().join("\n  "));
+    }
+    console.log("");
+  }
+
+  process.exit(ghosts.length === 0 ? 0 : 1);
+}
+
+main();