figma-cache-toolchain 2.0.3 → 2.0.5

package/figma-cache/js/ui-facts-normalizer.js

@@ -0,0 +1,233 @@
+/* eslint-disable no-console */
+"use strict";
+
+function normalizeHexColor(value) {
+  if (typeof value !== "string") {
+    return "";
+  }
+  const raw = value.trim();
+  const match = raw.match(/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/);
+  if (!match) {
+    return "";
+  }
+  const body = match[1].toUpperCase();
+  if (body.length === 3) {
+    return `#${body
+      .split("")
+      .map((ch) => `${ch}${ch}`)
+      .join("")}`;
+  }
+  return `#${body}`;
+}
+
+function dedupeStrings(values) {
+  const seen = new Set();
+  const output = [];
+  values.forEach((input) => {
+    const value = String(input || "").trim();
+    if (!value) {
+      return;
+    }
+    if (seen.has(value)) {
+      return;
+    }
+    seen.add(value);
+    output.push(value);
+  });
+  return output;
+}
+
+function dedupeTokens(tokens) {
+  const seen = new Set();
+  const output = [];
+  tokens.forEach((token) => {
+    const name = String(token.name || "").trim();
+    const value = normalizeHexColor(String(token.value || ""));
+    const key = `${name.toLowerCase()}@@${value}`;
+    if (!name && !value) {
+      return;
+    }
+    if (seen.has(key)) {
+      return;
+    }
+    seen.add(key);
+    output.push({
+      name,
+      value,
+      source: token.source || "unknown",
+    });
+  });
+  return output;
+}
+
+function isPlaceholderText(input) {
+  return /(TODO|待补充|待完善|待确认|占位|TBD|N\/A|none)/i.test(String(input || ""));
+}
+
+function extractSpecFacts(specText) {
+  const textFacts = [];
+  const tokenFacts = [];
+  const tokenRegex = /-\s*([^:\n]+?)\s*:\s*(#[0-9a-fA-F]{3,8})/g;
+  String(specText || "")
+    .split(/\r?\n/)
+    .forEach((line) => {
+      const t = line.trim();
+      if (!t.startsWith("-")) {
+        return;
+      }
+      let hasToken = false;
+      let match = null;
+      while ((match = tokenRegex.exec(t))) {
+        hasToken = true;
+        tokenFacts.push({
+          name: String(match[1] || "").trim(),
+          value: String(match[2] || "").trim(),
+          source: "spec.md",
+        });
+      }
+      if (!hasToken) {
+        const text = t.replace(/^-+\s*/, "").trim();
+        if (text) {
+          textFacts.push(text);
+        }
+      }
+    });
+  return {
+    textFacts: dedupeStrings(textFacts),
+    tokenFacts: dedupeTokens(tokenFacts),
+  };
+}
+
+function collectVariableTokens(value, prefix, out) {
+  if (value == null) {
+    return;
+  }
+  if (typeof value === "string") {
+    const hex = normalizeHexColor(value);
+    if (hex) {
+      out.push({
+        name: prefix,
+        value: hex,
+        source: "mcp-raw-get-variable-defs",
+      });
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => collectVariableTokens(entry, `${prefix}[${index}]`, out));
+    return;
+  }
+  if (typeof value === "object") {
+    Object.entries(value).forEach(([key, entry]) => {
+      const next = prefix ? `${prefix}.${key}` : key;
+      collectVariableTokens(entry, next, out);
+    });
+  }
+}
+
+function extractStateFacts(stateMapText) {
+  const states = new Set();
+  const lines = String(stateMapText || "").split(/\r?\n/);
+  let inStateSection = false;
+  lines.forEach((line) => {
+    const t = line.trim();
+    if (/^##\s+/i.test(t)) {
+      inStateSection = /(states?|state\s*map|状态)/i.test(t);
+      return;
+    }
+    if (!inStateSection || !t.startsWith("|")) {
+      return;
+    }
+    const cells = t
+      .split("|")
+      .slice(1, -1)
+      .map((cell) => cell.trim());
+    if (!cells.length) {
+      return;
+    }
+    const state = String(cells[0] || "").toLowerCase();
+    if (!state || state === "state" || /^-+$/.test(state)) {
+      return;
+    }
+    if (isPlaceholderText(state)) {
+      return;
+    }
+    states.add(state);
+  });
+  return [...states];
+}
+
+function extractInteractionFacts(rawJson) {
+  const interactionFacts = [];
+  const notes = [];
+  const interactions = rawJson && typeof rawJson.interactions === "object" ? rawJson.interactions : {};
+  if (Array.isArray(interactions.events)) {
+    interactions.events.forEach((evt) => interactionFacts.push(String(evt || "").trim()));
+  }
+  if (typeof interactions.notes === "string") {
+    notes.push(interactions.notes);
+  }
+  const states = rawJson && typeof rawJson.states === "object" ? rawJson.states : {};
+  if (typeof states.notes === "string") {
+    notes.push(states.notes);
+  }
+  const accessibility = rawJson && typeof rawJson.accessibility === "object" ? rawJson.accessibility : {};
+  if (typeof accessibility.notes === "string") {
+    notes.push(accessibility.notes);
+  }
+  return {
+    interactionFacts: dedupeStrings(interactionFacts),
+    notes: dedupeStrings(notes),
+  };
+}
+
+function normalizeUiFacts(input) {
+  const payload = input && typeof input === "object" ? input : {};
+  const specText = String(payload.specText || "");
+  const stateMapText = String(payload.stateMapText || "");
+  const rawJson = payload.rawJson && typeof payload.rawJson === "object" ? payload.rawJson : {};
+  const variableDefs =
+    payload.variableDefsJson && typeof payload.variableDefsJson === "object"
+      ? payload.variableDefsJson
+      : null;
+
+  const specFacts = extractSpecFacts(specText);
+  const stateFacts = extractStateFacts(stateMapText);
+  const interactionFacts = extractInteractionFacts(rawJson);
+
+  const variableTokens = [];
+  if (variableDefs) {
+    collectVariableTokens(variableDefs, "", variableTokens);
+  }
+
+  const tokenFacts = dedupeTokens([...specFacts.tokenFacts, ...variableTokens]);
+  const placeholderSources = [
+    specText,
+    stateMapText,
+    ...interactionFacts.notes,
+    JSON.stringify(rawJson || {}),
+  ];
+
+  return {
+    dimensions: {
+      layoutReady: !!(payload.entryReady && payload.evidenceReady),
+      textReady: specFacts.textFacts.length > 0,
+      tokenReady: tokenFacts.length > 0,
+      stateReady: stateFacts.length > 0,
+      interactionReady: interactionFacts.interactionFacts.length > 0 || interactionFacts.notes.length > 0,
+    },
+    facts: {
+      text: specFacts.textFacts,
+      tokens: tokenFacts,
+      states: stateFacts,
+      interactions: interactionFacts.interactionFacts,
+      notes: interactionFacts.notes,
+    },
+    hasPlaceholder: placeholderSources.some((source) => isPlaceholderText(source)),
+  };
+}
+
+module.exports = {
+  normalizeUiFacts,
+  normalizeHexColor,
+};

package/package.json

@@ -1,75 +1,95 @@
 {
-  "name": "figma-cache-toolchain",
-  "version": "2.0.3",
-  "description": "Figma link normalization, local cache index, validation, and Node CLI (framework-agnostic core).",
-  "homepage": "https://github.com/907086379/figma-cache-toolchain#readme",
-  "keywords": [
-    "figma",
-    "cache",
-    "cli",
-    "design-tokens",
-    "mcp"
-  ],
-  "license": "MIT",
-  "engines": {
-    "node": ">=16.20.0"
-  },
-  "bin": {
-    "figma-cache": "bin/figma-cache.js"
-  },
-  "files": [
-    "LICENSE",
-    "bin",
-    "cursor-bootstrap",
-    "figma-cache/figma-cache.js",
-    "figma-cache/js/flow-cli.js",
-    "figma-cache/js/validate-cli.js",
-    "figma-cache/js/budget-cli.js",
-    "figma-cache/js/index-store.js",
-    "figma-cache/js/cursor-bootstrap-cli.js",
-    "figma-cache/js/entry-files.js",
-    "figma-cache/js/backfill-cli.js",
-    "figma-cache/js/project-config.js",
-    "figma-cache/js/upsert-core.js",
-    "figma-cache/docs/*.md"
-  ],
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/"
-  },
-  "scripts": {
-    "test": "npm run cursor:shadow:check && npm run docs:encoding:check && node tests/rules-guard.js && node tests/smoke.js",
-    "prepack": "npm run cursor:shadow:check && npm run docs:encoding:check && node bin/figma-cache.js validate",
-    "figma:cache:normalize": "node bin/figma-cache.js normalize",
-    "figma:cache:get": "node bin/figma-cache.js get",
-    "figma:cache:upsert": "node bin/figma-cache.js upsert",
-    "figma:cache:ensure": "node bin/figma-cache.js ensure",
-    "figma:cache:validate": "node bin/figma-cache.js validate",
-    "figma:cache:stale": "node bin/figma-cache.js stale",
-    "figma:cache:budget": "node bin/figma-cache.js budget --mcp-only",
-    "figma:cache:backfill": "node bin/figma-cache.js backfill",
-    "figma:cache:init": "node bin/figma-cache.js init",
-    "figma:cache:config": "node bin/figma-cache.js config",
-    "figma:cache:flow:init": "node bin/figma-cache.js flow init",
-    "figma:cache:flow:add-node": "node bin/figma-cache.js flow add-node",
-    "figma:cache:flow:link": "node bin/figma-cache.js flow link",
-    "figma:cache:flow:chain": "node bin/figma-cache.js flow chain",
-    "figma:cache:flow:show": "node bin/figma-cache.js flow show",
-    "figma:cache:flow:mermaid": "node bin/figma-cache.js flow mermaid",
-    "figma:cache:cursor:init": "node bin/figma-cache.js cursor init",
-    "cursor:shadow:sync": "node scripts/sync-cursor-shadow.js",
-    "cursor:shadow:check": "node scripts/check-cursor-shadow.js",
-    "docs:encoding:check": "node scripts/check-doc-encoding.js",
-    "figma:cache:mobile:spec": "node scripts/mobile/generate-mobile-spec.js",
-    "figma:ui:gate": "npm run figma:cache:validate && npm run cursor:shadow:check && npm test"
-  },
-  "volta": {
-    "node": "16.20.2"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/907086379/figma-cache-toolchain.git"
-  },
-  "bugs": {
-    "url": "https://github.com/907086379/figma-cache-toolchain/issues"
-  }
+    "name": "figma-cache-toolchain",
+    "version": "2.0.5",
+    "description": "Figma link normalization, local cache index, validation, and Node CLI (framework-agnostic core).",
+    "homepage": "https://github.com/907086379/figma-cache-toolchain#readme",
+    "keywords": [
+        "figma",
+        "cache",
+        "cli",
+        "design-tokens",
+        "mcp"
+    ],
+    "license": "MIT",
+    "engines": {
+        "node": ">=16.20.0"
+    },
+    "bin": {
+        "figma-cache": "bin/figma-cache.js"
+    },
+    "files": [
+        "LICENSE",
+        "bin",
+        "cursor-bootstrap",
+        "figma-cache/figma-cache.js",
+        "figma-cache/js/flow-cli.js",
+        "figma-cache/js/validate-cli.js",
+        "figma-cache/js/budget-cli.js",
+        "figma-cache/js/index-store.js",
+        "figma-cache/js/cursor-bootstrap-cli.js",
+        "figma-cache/js/entry-files.js",
+        "figma-cache/js/backfill-cli.js",
+        "figma-cache/js/project-config.js",
+        "figma-cache/js/contract-check-cli.js",
+        "figma-cache/js/ui-facts-normalizer.js",
+        "figma-cache/js/upsert-core.js",
+        "scripts/ui-profile.js",
+        "scripts/ui-preflight.js",
+        "scripts/ui-1to1-audit.js",
+        "scripts/ui-report-aggregate.js",
+        "scripts/ui-auto-acceptance.js",
+        "scripts/cross-project-e2e.js",
+        "figma-cache/adapters/recipes/*.json",
+        "figma-cache/docs/*.md",
+        "figma-cache/docs/ui-1to1-report.schema.json"
+    ],
+    "publishConfig": {
+        "registry": "https://registry.npmjs.org/"
+    },
+    "scripts": {
+        "test": "npm run cursor:shadow:check && npm run docs:encoding:check && node tests/rules-guard.js && node tests/smoke.js",
+        "prepack": "npm run cursor:shadow:check && npm run docs:encoding:check && node bin/figma-cache.js validate",
+        "figma:cache:normalize": "node bin/figma-cache.js normalize",
+        "figma:cache:get": "node bin/figma-cache.js get",
+        "figma:cache:upsert": "node bin/figma-cache.js upsert",
+        "figma:cache:ensure": "node bin/figma-cache.js ensure",
+        "figma:cache:validate": "node bin/figma-cache.js validate",
+        "figma:cache:stale": "node bin/figma-cache.js stale",
+        "figma:cache:budget": "node bin/figma-cache.js budget --mcp-only",
+        "figma:cache:backfill": "node bin/figma-cache.js backfill",
+        "figma:cache:init": "node bin/figma-cache.js init",
+        "figma:cache:config": "node bin/figma-cache.js config",
+        "figma:cache:flow:init": "node bin/figma-cache.js flow init",
+        "figma:cache:flow:add-node": "node bin/figma-cache.js flow add-node",
+        "figma:cache:flow:link": "node bin/figma-cache.js flow link",
+        "figma:cache:flow:chain": "node bin/figma-cache.js flow chain",
+        "figma:cache:flow:show": "node bin/figma-cache.js flow show",
+        "figma:cache:flow:mermaid": "node bin/figma-cache.js flow mermaid",
+        "figma:cache:cursor:init": "node bin/figma-cache.js cursor init",
+        "cursor:shadow:sync": "node scripts/sync-cursor-shadow.js",
+        "cursor:shadow:check": "node scripts/check-cursor-shadow.js",
+        "docs:encoding:check": "node scripts/check-doc-encoding.js",
+        "figma:cache:mobile:spec": "node scripts/mobile/generate-mobile-spec.js",
+        "figma:ui:preflight": "node scripts/ui-preflight.js",
+        "figma:ui:audit": "node scripts/ui-1to1-audit.js",
+        "figma:ui:report:aggregate": "node scripts/ui-report-aggregate.js",
+        "figma:ui:accept": "node scripts/ui-auto-acceptance.js",
+        "figma:ui:e2e:cross": "node scripts/cross-project-e2e.js",
+        "figma:ui:gate": "npm run figma:ui:preflight && npm run figma:ui:audit -- --min-score=85 && npm run figma:cache:validate && npm run cursor:shadow:check && npm test",
+        "figma:ui:gate:pr": "npm run figma:ui:preflight && npm run figma:cache:validate",
+        "figma:ui:gate:main": "npm run figma:ui:preflight && npm run figma:ui:audit -- --min-score=90 && npm run figma:ui:report:aggregate && npm run figma:cache:validate && npm run cursor:shadow:check && npm test",
+        "figma:cache:contract:check": "node bin/figma-cache.js contract-check",
+        "preflight:shell": "node scripts/preflight-shell.js --warn",
+        "preflight:shell:strict": "node scripts/preflight-shell.js --strict"
+    },
+    "volta": {
+        "node": "16.20.2"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/907086379/figma-cache-toolchain.git"
+    },
+    "bugs": {
+        "url": "https://github.com/907086379/figma-cache-toolchain/issues"
+    }
 }