figma-cache-toolchain 2.0.2 → 2.0.4

package/scripts/ui-preflight.js

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { getUiProfileConfig } = require("./ui-profile");
+
+const ROOT = process.cwd();
+const CACHE_DIR_INPUT = process.env.FIGMA_CACHE_DIR || "figma-cache";
+const INDEX_FILE_NAME = process.env.FIGMA_CACHE_INDEX_FILE || "index.json";
+const DEFAULT_CONTRACT_PATH = "figma-cache/adapters/ui-adapter.contract.json";
+const DEFAULT_REPORT_PATH = "figma-cache/reports/ui-preflight-report.json";
+const BLOCKING_EXIT_CODE = 2;
+
+function normalizeSlash(input) {
+  return String(input || "").replace(/\\/g, "/");
+}
+
+function resolveMaybeAbsolutePath(input) {
+  if (!input) {
+    return "";
+  }
+  return path.isAbsolute(input) ? path.normalize(input) : path.join(ROOT, input);
+}
+
+function readJsonOrNull(absPath) {
+  try {
+    return JSON.parse(fs.readFileSync(absPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function readTextOrEmpty(absPath) {
+  try {
+    return fs.readFileSync(absPath, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function fileExists(absPath) {
+  try {
+    return fs.existsSync(absPath);
+  } catch {
+    return false;
+  }
+}
+
+function ensureParentDir(absPath) {
+  fs.mkdirSync(path.dirname(absPath), { recursive: true });
+}
+
+function parseArgs(argv) {
+  const options = {
+    cacheKey: "",
+    contractPath: DEFAULT_CONTRACT_PATH,
+    reportPath: DEFAULT_REPORT_PATH,
+    allowWarn: false,
+    hasUnknownArgs: false,
+    unknownArgs: [],
+  };
+
+  argv.forEach((arg) => {
+    if (arg.startsWith("--cacheKey=")) {
+      options.cacheKey = arg.split("=").slice(1).join("=").trim();
+      return;
+    }
+    if (arg.startsWith("--contract=")) {
+      options.contractPath = arg.split("=").slice(1).join("=").trim() || DEFAULT_CONTRACT_PATH;
+      return;
+    }
+    if (arg.startsWith("--report=")) {
+      options.reportPath = arg.split("=").slice(1).join("=").trim() || DEFAULT_REPORT_PATH;
+      return;
+    }
+    if (arg === "--allow-warn") {
+      options.allowWarn = true;
+      return;
+    }
+    options.hasUnknownArgs = true;
+    options.unknownArgs.push(arg);
+  });
+
+  return options;
+}
+
+function hasTodoPlaceholder(text) {
+  return /(TODO|待补充|待完善|待确认|占位)/i.test(String(text || ""));
+}
+
+function hasMappingEntries(contract, key) {
+  if (!contract || typeof contract !== "object") {
+    return false;
+  }
+  const value = contract[key];
+  if (Array.isArray(value)) {
+    return value.length > 0;
+  }
+  if (value && typeof value === "object") {
+    return Object.keys(value).length > 0;
+  }
+  return false;
+}
+
+function checkCoverageEvidence(item, rawJson) {
+  const completeness = Array.isArray(item.completeness) ? item.completeness : [];
+  const evidence =
+    rawJson &&
+    rawJson.coverageSummary &&
+    rawJson.coverageSummary.evidence &&
+    typeof rawJson.coverageSummary.evidence === "object"
+      ? rawJson.coverageSummary.evidence
+      : null;
+  if (!evidence) {
+    return false;
+  }
+  return completeness.every((dimension) => {
+    const list = evidence[dimension];
+    return Array.isArray(list) && list.length > 0;
+  });
+}
+
+function validateMcpManifest(nodeDir) {
+  const manifestPath = path.join(nodeDir, "mcp-raw", "mcp-raw-manifest.json");
+  const manifest = readJsonOrNull(manifestPath);
+  if (!manifest || typeof manifest !== "object") {
+    return { ok: false, reason: "mcp-raw manifest missing or invalid" };
+  }
+  if (!manifest.files || typeof manifest.files !== "object") {
+    return { ok: false, reason: "mcp-raw manifest.files missing" };
+  }
+  return { ok: true };
+}
+
+function buildItemReport(cacheKey, item, contractReady) {
+  const blocking = [];
+  const warnings = [];
+  const checks = {
+    cacheItemExists: !!item,
+    entryFilesExist: false,
+    coverageEvidenceReady: false,
+    contractExists: contractReady.exists,
+    tokenMappingReady: contractReady.tokenMappingsReady,
+    stateMappingReady: contractReady.stateMappingsReady,
+    mcpRawReady: true,
+  };
+
+  if (!item) {
+    blocking.push("cache item not found");
+    return {
+      cacheKey,
+      source: "unknown",
+      blocking,
+      warnings,
+      checks,
+    };
+  }
+
+  const paths = item.paths && typeof item.paths === "object" ? item.paths : {};
+  const absMeta = paths.meta ? resolveMaybeAbsolutePath(paths.meta) : "";
+  const absSpec = paths.spec ? resolveMaybeAbsolutePath(paths.spec) : "";
+  const absStateMap = paths.stateMap ? resolveMaybeAbsolutePath(paths.stateMap) : "";
+  const absRaw = paths.raw ? resolveMaybeAbsolutePath(paths.raw) : "";
+
+  const requiredFiles = [absMeta, absSpec, absStateMap, absRaw];
+  checks.entryFilesExist = requiredFiles.every((absPath) => !!absPath && fileExists(absPath));
+  if (!checks.entryFilesExist) {
+    blocking.push("entry file path missing or file not found (meta/spec/state-map/raw)");
+  }
+
+  const rawJson = absRaw ? readJsonOrNull(absRaw) : null;
+  checks.coverageEvidenceReady = checkCoverageEvidence(item, rawJson);
+  if (!checks.coverageEvidenceReady) {
+    blocking.push("raw.coverageSummary.evidence missing or incomplete");
+  }
+
+  if (!checks.contractExists) {
+    blocking.push("adapter contract missing or invalid JSON");
+  }
+  if (!checks.tokenMappingReady) {
+    blocking.push("contract tokenMappings is empty");
+  }
+  if (!checks.stateMappingReady) {
+    blocking.push("contract stateMappings is empty");
+  }
+
+  const specText = absSpec ? readTextOrEmpty(absSpec) : "";
+  const stateMapText = absStateMap ? readTextOrEmpty(absStateMap) : "";
+  if (hasTodoPlaceholder(specText)) {
+    warnings.push("spec.md contains TODO placeholder");
+  }
+  if (hasTodoPlaceholder(stateMapText)) {
+    warnings.push("state-map.md contains TODO placeholder");
+  }
+
+  if (item.source === "figma-mcp") {
+    const nodeDir = absMeta ? path.dirname(absMeta) : "";
+    const manifestStatus = validateMcpManifest(nodeDir);
+    checks.mcpRawReady = manifestStatus.ok;
+    if (!manifestStatus.ok) {
+      blocking.push(manifestStatus.reason);
+    }
+  }
+
+  return {
+    cacheKey,
+    source: item.source || "manual",
+    blocking,
+    warnings,
+    checks,
+  };
+}
+
+function run() {
+  const options = parseArgs(process.argv.slice(2));
+  const profileConfig = getUiProfileConfig();
+  if (options.hasUnknownArgs) {
+    console.error(`Unknown args: ${options.unknownArgs.join(", ")}`);
+    process.exit(BLOCKING_EXIT_CODE);
+  }
+
+  const cacheDir = resolveMaybeAbsolutePath(CACHE_DIR_INPUT);
+  const indexPath = path.isAbsolute(INDEX_FILE_NAME)
+    ? INDEX_FILE_NAME
+    : path.join(cacheDir, INDEX_FILE_NAME);
+  const contractPath = resolveMaybeAbsolutePath(options.contractPath);
+  const reportPath = resolveMaybeAbsolutePath(options.reportPath);
+
+  const index = readJsonOrNull(indexPath);
+  const contract = readJsonOrNull(contractPath);
+  const contractReady = {
+    exists: !!contract && typeof contract === "object",
+    tokenMappingsReady: hasMappingEntries(contract, "tokenMappings"),
+    stateMappingsReady: hasMappingEntries(contract, "stateMappings"),
+  };
+
+  const items = index && index.items && typeof index.items === "object" ? index.items : {};
+  const targetCacheKeys = options.cacheKey ? [options.cacheKey] : Object.keys(items);
+
+  const reportItems = targetCacheKeys.map((cacheKey) =>
+    buildItemReport(cacheKey, items[cacheKey], contractReady)
+  );
+
+  const blockingCount = reportItems.reduce((acc, item) => acc + item.blocking.length, 0);
+  const warningCount = reportItems.reduce((acc, item) => acc + item.warnings.length, 0);
+  const warningBlockingCount = profileConfig.preflightTreatWarningsAsBlocking ? warningCount : 0;
+  const hasBlocking = blockingCount + warningBlockingCount > 0;
+
+  const report = {
+    ok: !hasBlocking,
+    generatedAt: new Date().toISOString(),
+    summary: {
+      checkedItems: reportItems.length,
+      blockingCount,
+      warningCount,
+      warningBlockingCount,
+      allowWarn: options.allowWarn,
+      profile: profileConfig.profile,
+    },
+    options: {
+      cacheKey: options.cacheKey || null,
+      contractPath: normalizeSlash(contractPath),
+      reportPath: normalizeSlash(reportPath),
+    },
+    items: reportItems,
+  };
+
+  ensureParentDir(reportPath);
+  fs.writeFileSync(reportPath, `${JSON.stringify(report, null, 2)}\n`, "utf8");
+
+  if (report.ok || (options.allowWarn && blockingCount === 0 && warningBlockingCount === 0)) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  console.error("ui-preflight failed:");
+  reportItems.forEach((item) => {
+    if (!item.blocking.length) {
+      return;
+    }
+    console.error(`- ${item.cacheKey}`);
+    item.blocking.forEach((err) => console.error(`  * ${err}`));
+  });
+  process.exit(BLOCKING_EXIT_CODE);
+}
+
+run();

package/scripts/ui-profile.js

@@ -0,0 +1,46 @@
+"use strict";
+
+const DEFAULT_UI_PROFILE = "standard";
+
+const PROFILE_CONFIG = Object.freeze({
+  fast: Object.freeze({
+    preflightTreatWarningsAsBlocking: false,
+    auditDefaultMinScore: 70,
+    auditRequireTargetPath: false,
+  }),
+  standard: Object.freeze({
+    preflightTreatWarningsAsBlocking: false,
+    auditDefaultMinScore: 85,
+    auditRequireTargetPath: false,
+  }),
+  strict: Object.freeze({
+    preflightTreatWarningsAsBlocking: true,
+    auditDefaultMinScore: 92,
+    auditRequireTargetPath: true,
+  }),
+});
+
+function resolveUiProfile(input) {
+  const raw = String(input || process.env.FIGMA_UI_PROFILE || DEFAULT_UI_PROFILE)
+    .trim()
+    .toLowerCase();
+  if (raw && PROFILE_CONFIG[raw]) {
+    return raw;
+  }
+  return DEFAULT_UI_PROFILE;
+}
+
+function getUiProfileConfig(input) {
+  const profile = resolveUiProfile(input);
+  return {
+    profile,
+    ...PROFILE_CONFIG[profile],
+  };
+}
+
+module.exports = {
+  DEFAULT_UI_PROFILE,
+  PROFILE_CONFIG,
+  resolveUiProfile,
+  getUiProfileConfig,
+};

package/scripts/ui-report-aggregate.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { getUiProfileConfig } = require("./ui-profile");
+
+const ROOT = process.cwd();
+const CACHE_DIR_INPUT = process.env.FIGMA_CACHE_DIR || "figma-cache";
+const DEFAULT_OUTPUT_PATH = "figma-cache/reports/ui-quality-summary.json";
+
+function resolveMaybeAbsolutePath(input) {
+  if (!input) {
+    return "";
+  }
+  return path.isAbsolute(input) ? path.normalize(input) : path.join(ROOT, input);
+}
+
+function readJsonOrNull(absPath) {
+  try {
+    return JSON.parse(fs.readFileSync(absPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function parseArgs(argv) {
+  const options = {
+    preflightReport: "",
+    auditReport: "",
+    output: DEFAULT_OUTPUT_PATH,
+  };
+  argv.forEach((arg) => {
+    if (arg.startsWith("--preflight-report=")) {
+      options.preflightReport = arg.split("=").slice(1).join("=").trim();
+      return;
+    }
+    if (arg.startsWith("--audit-report=")) {
+      options.auditReport = arg.split("=").slice(1).join("=").trim();
+      return;
+    }
+    if (arg.startsWith("--output=")) {
+      options.output = arg.split("=").slice(1).join("=").trim() || DEFAULT_OUTPUT_PATH;
+    }
+  });
+  return options;
+}
+
+function ensureParentDir(absPath) {
+  fs.mkdirSync(path.dirname(absPath), { recursive: true });
+}
+
+function ratio(numerator, denominator) {
+  if (!denominator) {
+    return 0;
+  }
+  return Number((numerator / denominator).toFixed(4));
+}
+
+function run() {
+  const options = parseArgs(process.argv.slice(2));
+  const cacheDir = resolveMaybeAbsolutePath(CACHE_DIR_INPUT);
+  const preflightPath = resolveMaybeAbsolutePath(
+    options.preflightReport || path.join(cacheDir, "reports", "ui-preflight-report.json")
+  );
+  const auditPath = resolveMaybeAbsolutePath(
+    options.auditReport || path.join(cacheDir, "reports", "ui-1to1-report.json")
+  );
+  const outputPath = resolveMaybeAbsolutePath(options.output);
+  const profileConfig = getUiProfileConfig();
+
+  const preflight = readJsonOrNull(preflightPath) || {};
+  const audit = readJsonOrNull(auditPath) || {};
+  const preflightItems = Array.isArray(preflight.items) ? preflight.items : [];
+  const auditItems = Array.isArray(audit.items) ? audit.items : [];
+
+  const preflightBlockingItems = preflightItems.filter(
+    (item) => Array.isArray(item.blocking) && item.blocking.length > 0
+  ).length;
+  const auditPassItems = auditItems.filter(
+    (item) => item && item.score && Number(item.score.total || 0) >= Number(audit.summary && audit.summary.minScore || 0)
+  ).length;
+
+  const summary = {
+    generatedAt: new Date().toISOString(),
+    profile: profileConfig.profile,
+    inputs: {
+      preflightReport: preflightPath,
+      auditReport: auditPath,
+    },
+    metrics: {
+      checkedItems: preflightItems.length || auditItems.length,
+      preflightBlockingRate: ratio(preflightBlockingItems, preflightItems.length),
+      auditPassRate: ratio(auditPassItems, auditItems.length),
+      firstPassAcceptedRate: ratio(auditPassItems, auditItems.length),
+      averageAuditScore: Number(
+        (
+          auditItems.reduce((acc, item) => acc + Number(item && item.score && item.score.total || 0), 0) /
+          Math.max(1, auditItems.length)
+        ).toFixed(2)
+      ),
+      reworkRoundsEstimate: Number(
+        (1 - ratio(auditPassItems, Math.max(1, auditItems.length))).toFixed(2)
+      ),
+    },
+    trend: {
+      status:
+        preflightBlockingItems === 0 && auditPassItems === auditItems.length
+          ? "healthy"
+          : "needs-attention",
+      notes: [
+        "Use this file as weekly baseline input for team QA review.",
+        "Track blockingRate and averageAuditScore trend in CI artifacts.",
+      ],
+    },
+  };
+
+  ensureParentDir(outputPath);
+  fs.writeFileSync(outputPath, `${JSON.stringify(summary, null, 2)}\n`, "utf8");
+  console.log(JSON.stringify(summary, null, 2));
+}
+
+run();

package/cursor-bootstrap/skills/ui-baseline-governance/SKILL.md

@@ -1,51 +0,0 @@
----
-name: ui-baseline-governance
-description: 为新项目或老项目建立可执行的全局样式基线，并把约束固化到组件生成行为。
----
-
-# UI Baseline Governance Skill
-
-本 Skill 用于“要不要上全局 reset / 如何在老项目安全落地 / 如何约束后续组件生成”三类问题。
-若与规则冲突，以 `.cursor/rules/04-ui-baseline-governance.mdc` 为准。
-
-## 触发场景
-
-- 用户询问：全局 `border-box`、reset、默认样式基线。
-- 用户反馈：组件反复出现超高/超宽/对齐漂移/图标不可见。
-- 用户要求：把经验沉淀为长期规范，约束后续 Agent 生成行为。
-
-## 执行步骤（按序）
-
-1. 判断项目类型：`新项目` 或 `老项目`（**必须**按 `.cursor/rules/04-ui-baseline-governance.mdc` §1.0 机械启发式执行，输出结论 + 命中证据；不确定则按老项目）。
-2. 输出一份“基线实施决策”：
-   - 新项目：一次性全局基线
-   - 老项目：分层分批迁移
-3. 给出最小基线清单（不与栈强耦合）：
-   - `border-box`
-   - margin/padding reset
-   - 媒体元素 display 规则
-   - 字体基线
-   - focus-visible
-4. 同步“生成约束”到执行口径：
-   - 默认 `box-border`
-   - 文本溢出显式处理
-   - 弹层锚定触发器
-   - 图标优先项目库，兜底 `inline svg`
-   - 状态覆盖完整
-5. 给出验证与回滚方案：
-   - lint + 视觉检查
-   - 影响范围
-   - 回滚点
-
-## 用户可见输出模板（精简）
-
-1. 当前项目类型与推荐策略（全局 or 分层）
-2. 本轮要落的基线条目（最多 5 条）
-3. 对后续组件生成的强约束（最多 5 条）
-4. 验证与回滚
-
-## 禁止事项
-
-- 不得在老项目直接“全局 reset + 大规模重构”同轮执行。
-- 不得把框架私有实现写入 `figma-cache/files/**` 的通用缓存文档。
-- 不得在未声明风险的情况下修改大范围全局样式。