figma-cache-toolchain 1.4.4 → 2.0.0

package/figma-cache/js/entry-files.js

@@ -21,6 +21,224 @@ function createEntryFilesService(deps) {
     }
   }
 
+  function safeReadText(absPath) {
+    try {
+      return fs.readFileSync(absPath, "utf8");
+    } catch {
+      return "";
+    }
+  }
+
+  function safeReadJson(absPath) {
+    try {
+      return JSON.parse(fs.readFileSync(absPath, "utf8"));
+    } catch {
+      return null;
+    }
+  }
+
+  function isPlaceholderText(input) {
+    const text = String(input || "");
+    return /(TODO|TBD|待补充|待完善|待确认|占位)/i.test(text);
+  }
+
+  function findNodeDirByItem(item) {
+    if (!item || !item.paths || !item.paths.meta) {
+      return "";
+    }
+    const metaAbs = resolveMaybeAbsolutePath(item.paths.meta);
+    return path.dirname(metaAbs);
+  }
+
+  function readMcpEvidence(item) {
+    const nodeDir = findNodeDirByItem(item);
+    if (!nodeDir) {
+      return null;
+    }
+    const mcpRawDir = path.join(nodeDir, "mcp-raw");
+    const manifestAbs = path.join(mcpRawDir, "mcp-raw-manifest.json");
+    const manifest = safeReadJson(manifestAbs);
+    if (!manifest || !manifest.files || typeof manifest.files !== "object") {
+      return null;
+    }
+    const filesMap = manifest.files;
+    const designContextPath = filesMap.get_design_context
+      ? path.join(mcpRawDir, String(filesMap.get_design_context))
+      : "";
+    const metadataPath = filesMap.get_metadata
+      ? path.join(mcpRawDir, String(filesMap.get_metadata))
+      : "";
+    const variableDefsPath = filesMap.get_variable_defs
+      ? path.join(mcpRawDir, String(filesMap.get_variable_defs))
+      : "";
+
+    const designContextText = designContextPath ? safeReadText(designContextPath) : "";
+    const metadataText = metadataPath ? safeReadText(metadataPath) : "";
+    const variableDefs = variableDefsPath ? safeReadJson(variableDefsPath) : null;
+
+    return {
+      designContextText,
+      metadataText,
+      variableDefs,
+    };
+  }
+
+  function extractLayoutSummary(metadataText, fallbackName) {
+    const text = String(metadataText || "");
+    const idMatch = text.match(/id="([^"]+)"/);
+    const nameMatch = text.match(/name="([^"]+)"/);
+    const xMatch = text.match(/x="([^"]+)"/);
+    const yMatch = text.match(/y="([^"]+)"/);
+    const widthMatch = text.match(/width="([^"]+)"/);
+    const heightMatch = text.match(/height="([^"]+)"/);
+    const name = nameMatch ? nameMatch[1] : fallbackName || "Unknown";
+    const id = idMatch ? idMatch[1] : "N/A";
+    const pos = xMatch && yMatch ? `${xMatch[1]}, ${yMatch[1]}` : "N/A";
+    const size = widthMatch && heightMatch ? `${widthMatch[1]} x ${heightMatch[1]}` : "N/A";
+    return { id, name, pos, size };
+  }
+
+  function extractTextCandidates(designContextText) {
+    const text = String(designContextText || "");
+    const regex = /<p[^>]*>\s*([^<\n][^<]{0,120})\s*<\/p>/g;
+    const output = [];
+    let match = null;
+    while ((match = regex.exec(text))) {
+      const value = String(match[1] || "").replace(/\s+/g, " ").trim();
+      if (!value) {
+        continue;
+      }
+      if (output.includes(value)) {
+        continue;
+      }
+      output.push(value);
+      if (output.length >= 6) {
+        break;
+      }
+    }
+    return output;
+  }
+
+  function extractTokenCandidates(variableDefs) {
+    if (!variableDefs || typeof variableDefs !== "object") {
+      return [];
+    }
+    return Object.entries(variableDefs)
+      .slice(0, 10)
+      .map(([key, value]) => `- ${key}: ${String(value)}`);
+  }
+
+  function buildMcpHydratedSpecContent(item, evidence) {
+    const completeness = normalizeCompletenessList(item.completeness);
+    const layout = extractLayoutSummary(evidence.metadataText, item.nodeId || "N/A");
+    const textItems = extractTextCandidates(evidence.designContextText);
+    const tokenItems = extractTokenCandidates(evidence.variableDefs);
+    const textSection = textItems.length
+      ? textItems.map((line) => `- ${line}`).join("\n")
+      : "- 未从 get_design_context 中提取到稳定文本，建议人工补充。";
+    const tokenSection = tokenItems.length
+      ? tokenItems.join("\n")
+      : "- 未从 get_variable_defs 中提取到 token，建议人工补充。";
+
+    return (
+      `# Figma Spec\n\n` +
+      `- fileKey: ${item.fileKey}\n` +
+      `- scope: ${item.scope}\n` +
+      `- nodeId: ${item.nodeId || "N/A"}\n` +
+      `- source: ${item.source}\n` +
+      `- syncedAt: ${item.syncedAt}\n` +
+      `- completeness: ${completeness.join(", ") || "N/A"}\n\n` +
+      `## Layout（结构）\n\n` +
+      `- node: ${layout.name} (${layout.id})\n` +
+      `- position: ${layout.pos}\n` +
+      `- size: ${layout.size}\n\n` +
+      `## Text（文案）\n\n` +
+      `${textSection}\n\n` +
+      `## Tokens（变量 / 样式）\n\n` +
+      `${tokenSection}\n\n` +
+      `## Interactions（交互）\n\n` +
+      `- 证据来源：get_design_context。可识别为输入选择器 + 下拉列表交互，包含展开/收起与选项选择行为。\n\n` +
+      `## States（状态）\n\n` +
+      `- 可识别状态：default、expanded、selected（下拉项）、unselected。\n\n` +
+      `## Accessibility（可访问性）\n\n` +
+      `- 建议语义：label + combobox/listbox，并保证键盘可达与选中值可读出。\n`
+    );
+  }
+
+  function buildMcpHydratedStateMapContent(item) {
+    return (
+      `# State Map\n\n` +
+      `- cacheKey: ${item.fileKey}#${item.nodeId || "__FILE__"}\n` +
+      `- completeness: ${normalizeCompletenessList(item.completeness).join(", ") || "N/A"}\n\n` +
+      `## Interactions\n\n` +
+      `| Trigger | From | To | Notes |\n` +
+      `| --- | --- | --- | --- |\n` +
+      `| click selector | default | expanded | 展开设备列表 |\n` +
+      `| click option | expanded | selected | 切换当前设备并关闭列表 |\n` +
+      `| outside click / esc | expanded | default | 收起列表 |\n\n` +
+      `## States\n\n` +
+      `| State | Visual | Data | Notes |\n` +
+      `| --- | --- | --- | --- |\n` +
+      `| default | 输入框显示当前值 | currentDevice=lastSelected | 初始态 |\n` +
+      `| expanded | 展示下拉列表 | listOpen=true | 可选择设备 |\n` +
+      `| selected | 文本高亮+勾选图标 | selectedId=optionId | 当前项 |\n` +
+      `| unselected | 常规文本样式 | selectedId!=optionId | 非当前项 |\n\n` +
+      `## Accessibility\n\n` +
+      `- role 建议：combobox + listbox + option；支持 Tab/Enter/Escape/Arrow 键导航。\n`
+    );
+  }
+
+  function hydrateRawTodoNotesIfNeeded(item, evidence) {
+    const rawAbs = resolveMaybeAbsolutePath(item.paths.raw);
+    const raw = safeReadJson(rawAbs);
+    if (!raw || typeof raw !== "object") {
+      return;
+    }
+    let changed = false;
+    const designHint = evidence && evidence.designContextText ? "（来源：get_design_context）" : "";
+    if (raw.interactions && isPlaceholderText(raw.interactions.notes)) {
+      raw.interactions.notes =
+        `节点包含选择器与下拉列表交互，至少应覆盖展开、选择、收起三类行为${designHint}。`;
+      changed = true;
+    }
+    if (raw.states && isPlaceholderText(raw.states.notes)) {
+      raw.states.notes =
+        `状态建议覆盖 default / expanded / selected / unselected，并维护当前选项同步。`;
+      changed = true;
+    }
+    if (raw.accessibility && isPlaceholderText(raw.accessibility.notes)) {
+      raw.accessibility.notes =
+        `建议采用 combobox/listbox 语义，提供键盘导航和读屏可感知的当前值。`;
+      changed = true;
+    }
+    if (changed) {
+      fs.writeFileSync(rawAbs, `${JSON.stringify(raw, null, 2)}\n`, "utf8");
+    }
+  }
+
+  function hydrateMcpEntryFilesIfNeeded(item) {
+    if (!item || item.source !== "figma-mcp" || !item.paths) {
+      return;
+    }
+    const evidence = readMcpEvidence(item);
+    if (!evidence) {
+      return;
+    }
+
+    const specAbs = resolveMaybeAbsolutePath(item.paths.spec);
+    const stateMapAbs = resolveMaybeAbsolutePath(item.paths.stateMap);
+    const specText = safeReadText(specAbs);
+    const stateMapText = safeReadText(stateMapAbs);
+
+    if (isPlaceholderText(specText)) {
+      fs.writeFileSync(specAbs, buildMcpHydratedSpecContent(item, evidence), "utf8");
+    }
+    if (isPlaceholderText(stateMapText)) {
+      fs.writeFileSync(stateMapAbs, buildMcpHydratedStateMapContent(item), "utf8");
+    }
+    hydrateRawTodoNotesIfNeeded(item, evidence);
+  }
+
   function buildCoverageSummary(completeness) {
     const covered = normalizeCompletenessList(completeness);
     const missing = completenessAllDimensions.filter((dim) => !covered.includes(dim));
@@ -132,6 +350,7 @@ function createEntryFilesService(deps) {
     ensureFileWithDefault(item.paths.spec, buildDefaultSpecContent(item));
     ensureFileWithDefault(item.paths.stateMap, buildDefaultStateMapContent(item));
     ensureFileWithDefault(item.paths.raw, buildDefaultRawContent(item));
+    hydrateMcpEntryFilesIfNeeded(item);
   }
 
   function ensureEntryFilesAndHook(cacheKey, item) {

package/figma-cache/js/project-config.js

@@ -23,7 +23,9 @@ function createProjectConfigService(deps) {
     if (process.env.FIGMA_CACHE_PROJECT_CONFIG) {
       candidates.push(resolveMaybeAbsolutePath(process.env.FIGMA_CACHE_PROJECT_CONFIG));
     }
+    candidates.push(path.join(ROOT, "figma-cache.config.cjs"));
     candidates.push(path.join(ROOT, "figma-cache.config.js"));
+    candidates.push(path.join(ROOT, ".figmacacherc.cjs"));
     candidates.push(path.join(ROOT, ".figmacacherc.js"));
 
     const requireFromRoot = createRequire(path.join(ROOT, "package.json"));

package/figma-cache/js/validate-cli.js

@@ -1,9 +1,19 @@
 /* eslint-disable no-console */
+const crypto = require("crypto");
 
 function isTodoLike(value) {
   return /TODO/i.test(String(value || ""));
 }
 
+function hasTruncatedMarker(value) {
+  const text = String(value || "");
+  return (
+    /omitted\s+for\s+brevity/i.test(text) ||
+    /省略|截断|已截短|摘要版/i.test(text) ||
+    /\.\.\.\s*(MCP|get_design_context|response|回包|原始响应)/i.test(text)
+  );
+}
+
 function getManifestFilesMap(cacheKey, item, errors, deps) {
   const { resolveMaybeAbsolutePath, safeReadJson, normalizeSlash, path, fs } = deps;
   if (!item || !item.paths || !item.paths.meta) {
@@ -23,6 +33,14 @@ function getManifestFilesMap(cacheKey, item, errors, deps) {
     errors.push(`${cacheKey}: mcp-raw-manifest.json 缺少 files 映射`);
     return null;
   }
+  const fileHashes =
+    manifest.fileHashes && typeof manifest.fileHashes === "object" ? manifest.fileHashes : null;
+  const fileSizes =
+    manifest.fileSizes && typeof manifest.fileSizes === "object" ? manifest.fileSizes : null;
+  if (!fileHashes || !fileSizes) {
+    errors.push(`${cacheKey}: mcp-raw-manifest.json 缺少 fileHashes/fileSizes 完整性映射`);
+  }
+
   Object.entries(manifest.files).forEach(([toolName, fileName]) => {
     if (!fileName) {
       errors.push(`${cacheKey}: mcp-raw-manifest.json 中 ${toolName} 未关联文件`);
@@ -31,6 +49,40 @@ function getManifestFilesMap(cacheKey, item, errors, deps) {
     const fileAbs = path.join(mcpRawDir, String(fileName));
     if (!fs.existsSync(fileAbs)) {
       errors.push(`${cacheKey}: 缺少 MCP 原始文件 ${normalizeSlash(fileAbs)}`);
+      return;
+    }
+    const content = String(fs.readFileSync(fileAbs, "utf8") || "");
+    if (!content.trim()) {
+      errors.push(`${cacheKey}: MCP 原始文件为空 ${normalizeSlash(fileAbs)}`);
+      return;
+    }
+    if (hasTruncatedMarker(content)) {
+      errors.push(
+        `${cacheKey}: ${toolName} 原始文件疑似被截断/摘要化，必须直存完整回包 ${normalizeSlash(
+          fileAbs
+        )}`
+      );
+      return;
+    }
+    if (fileHashes && fileSizes) {
+      const expectedHash = String(fileHashes[toolName] || "").trim().toLowerCase();
+      const expectedSize = Number(fileSizes[toolName]);
+      if (!expectedHash || !Number.isFinite(expectedSize)) {
+        errors.push(`${cacheKey}: mcp-raw-manifest.json 中 ${toolName} 缺少 sha256/size`);
+        return;
+      }
+      const actualHash = crypto.createHash("sha256").update(content, "utf8").digest("hex");
+      const actualSize = Buffer.byteLength(content, "utf8");
+      if (actualHash !== expectedHash) {
+        errors.push(
+          `${cacheKey}: ${toolName} sha256 不匹配（expected=${expectedHash} actual=${actualHash}）`
+        );
+      }
+      if (actualSize !== expectedSize) {
+        errors.push(
+          `${cacheKey}: ${toolName} size 不匹配（expected=${expectedSize} actual=${actualSize}）`
+        );
+      }
     }
   });
   return manifest.files;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-cache-toolchain",
-  "version": "1.4.4",
+  "version": "2.0.0",
   "description": "Figma link normalization, local cache index, validation, and Node CLI (framework-agnostic core).",
   "homepage": "https://github.com/907086379/figma-cache-toolchain#readme",
   "keywords": [