figma-cache-toolchain 2.0.4 → 2.0.7

package/scripts/auto-link-related-from-batch.cjs

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Auto-link related cacheKeys into figma-cache/index.json flows using
+ * high-confidence heuristics based on raw.json.iconMetrics overlaps.
+ *
+ * Goal: reduce manual relatedCacheKeys maintenance and support "agent only mentions nodeId".
+ *
+ * Usage:
+ *   node scripts/auto-link-related-from-batch.cjs --batch=./figma-e2e-batch.json
+ *
+ * Options:
+ *   --flow=<flowId>                (default: env FIGMA_DEFAULT_FLOW || "auto-related")
+ *   --min-shared=<n>               (default: 3) min shared iconMetrics nodeIds
+ *   --min-shared-instance=<n>      (default: 2) min shared instance-path nodeIds (contain ';')
+ *   --min-jaccard=<ratio>          (default: 0.35)
+ *   --suggest-min-shared=<n>       (default: 1) suggestion threshold (won't auto-link)
+ *   --suggest-min-shared-instance=<n> (default: 1)
+ *   --suggest-min-jaccard=<ratio>  (default: 0.12)
+ *   --suggest-out=<path>           (default: figma-cache/reports/runtime/auto-related-suggestions.json)
+ *   --promote-min-jaccard=<ratio>  (default: 0.55) if met (with shared instance), promote to auto-link
+ *   --promote-min-shared-instance=<n> (default: 2)
+ *   --dry-run                      don't write index.json
+ *
+ * Strict mode:
+ *   FIGMA_UI_AUTOLINK_STRICT=1 will exit(3) if suggestions are present.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const ROOT = process.cwd();
+const INDEX_ABS = path.join(ROOT, "figma-cache", "index.json");
+const DEFAULT_SUGGEST_OUT = path.join(
+  ROOT,
+  "figma-cache",
+  "reports",
+  "runtime",
+  "auto-related-suggestions.json"
+);
+
+function safeReadJson(abs) {
+  try {
+    return JSON.parse(fs.readFileSync(abs, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(abs, value) {
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+function normalizeNodeId(input) {
+  const value = String(input || "").trim();
+  if (!value) return "";
+  return value.includes(":") ? value : value.replace(/-/g, ":");
+}
+
+function normalizeCacheKey(input) {
+  const value = String(input || "").trim();
+  if (!value) return "";
+  const parts = value.split("#");
+  if (parts.length !== 2) return value;
+  return `${parts[0]}#${normalizeNodeId(parts[1])}`;
+}
+
+function cacheKeyFromItem(item) {
+  const fileKey = String(item && item.fileKey ? item.fileKey : "").trim();
+  const nodeId = String(item && item.nodeId ? item.nodeId : "").trim();
+  if (!fileKey || !nodeId) return "";
+  return `${fileKey}#${normalizeNodeId(nodeId)}`;
+}
+
+function parseArgs(argv) {
+  const out = {
+    batch: path.join(ROOT, "figma-e2e-batch.json"),
+    flowId: process.env.FIGMA_DEFAULT_FLOW || "auto-related",
+    minShared: 2,
+    minSharedInstance: 1,
+    minJaccard: 0.2,
+    suggestMinShared: 1,
+    suggestMinSharedInstance: 1,
+    suggestMinJaccard: 0.12,
+    suggestOut: process.env.FIGMA_UI_AUTOLINK_SUGGEST_OUT || DEFAULT_SUGGEST_OUT,
+    promoteMinJaccard: 0.55,
+    promoteMinSharedInstance: 2,
+    dryRun: false,
+  };
+  argv.slice(2).forEach((arg) => {
+    if (arg.startsWith("--batch=")) out.batch = arg.split("=").slice(1).join("=").trim();
+    if (arg.startsWith("--flow=")) out.flowId = arg.split("=").slice(1).join("=").trim();
+    if (arg.startsWith("--min-shared=")) out.minShared = Number(arg.split("=").slice(1).join("=").trim());
+    if (arg.startsWith("--min-shared-instance="))
+      out.minSharedInstance = Number(arg.split("=").slice(1).join("=").trim());
+    if (arg.startsWith("--min-jaccard=")) out.minJaccard = Number(arg.split("=").slice(1).join("=").trim());
+    if (arg.startsWith("--suggest-min-shared="))
+      out.suggestMinShared = Number(arg.split("=").slice(1).join("=").trim());
+    if (arg.startsWith("--suggest-min-shared-instance="))
+      out.suggestMinSharedInstance = Number(arg.split("=").slice(1).join("=").trim());
+    if (arg.startsWith("--suggest-min-jaccard="))
+      out.suggestMinJaccard = Number(arg.split("=").slice(1).join("=").trim());
+    if (arg.startsWith("--suggest-out=")) out.suggestOut = arg.split("=").slice(1).join("=").trim();
+    if (arg.startsWith("--promote-min-jaccard="))
+      out.promoteMinJaccard = Number(arg.split("=").slice(1).join("=").trim());
+    if (arg.startsWith("--promote-min-shared-instance="))
+      out.promoteMinSharedInstance = Number(arg.split("=").slice(1).join("=").trim());
+    if (arg === "--dry-run") out.dryRun = true;
+  });
+  return out;
+}
+
+function setFromIconMetrics(raw) {
+  const list = raw && Array.isArray(raw.iconMetrics) ? raw.iconMetrics : [];
+  const all = new Set();
+  const instance = new Set();
+  list.forEach((m) => {
+    const id = m && m.nodeId ? String(m.nodeId).trim() : "";
+    if (!id) return;
+    all.add(id);
+    if (id.includes(";")) instance.add(id);
+  });
+  return { all, instance };
+}
+
+function intersectionSize(a, b) {
+  let c = 0;
+  a.forEach((x) => {
+    if (b.has(x)) c += 1;
+  });
+  return c;
+}
+
+function jaccard(a, b) {
+  const inter = intersectionSize(a, b);
+  const union = a.size + b.size - inter;
+  return union <= 0 ? 0 : inter / union;
+}
+
+function ensureFlow(index, flowId) {
+  index.flows = index.flows || {};
+  if (!index.flows[flowId]) {
+    index.flows[flowId] = {
+      id: flowId,
+      title: flowId,
+      description: "Auto-linked by iconMetrics overlap heuristics",
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      nodes: [],
+      edges: [],
+      assumptions: [],
+      openQuestions: [],
+    };
+  }
+  return index.flows[flowId];
+}
+
+function addNode(flow, cacheKey) {
+  flow.nodes = flow.nodes || [];
+  if (!flow.nodes.includes(cacheKey)) flow.nodes.push(cacheKey);
+}
+
+function hasEdge(flow, from, to, type) {
+  const edges = Array.isArray(flow.edges) ? flow.edges : [];
+  return edges.some((e) => e && e.from === from && e.to === to && e.type === type);
+}
+
+function addEdge(flow, from, to, type, note) {
+  flow.edges = flow.edges || [];
+  if (hasEdge(flow, from, to, type)) return false;
+  flow.edges.push({
+    id: `${from}->${to}:${type}:${Date.now()}`,
+    from,
+    to,
+    type,
+    note: note || "",
+    createdAt: new Date().toISOString(),
+  });
+  return true;
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const batchAbs = path.isAbsolute(args.batch) ? args.batch : path.join(ROOT, args.batch);
+  const index = safeReadJson(INDEX_ABS);
+  if (!index || !index.items) {
+    console.error(`[auto-link-related-from-batch] missing/invalid index: ${INDEX_ABS}`);
+    process.exit(2);
+  }
+  if (!fs.existsSync(batchAbs)) {
+    console.error(`[auto-link-related-from-batch] batch not found: ${batchAbs}`);
+    process.exit(2);
+  }
+  const batch = JSON.parse(fs.readFileSync(batchAbs, "utf8"));
+  if (!Array.isArray(batch) || batch.length === 0) {
+    console.error("[auto-link-related-from-batch] batch must be a non-empty array");
+    process.exit(2);
+  }
+
+  const flow = ensureFlow(index, args.flowId);
+  let links = 0;
+  const suggestions = [];
+
+  batch.forEach((b) => {
+    const primary = normalizeCacheKey(String(b && (b.cacheKey || cacheKeyFromItem(b)) || ""));
+    if (!primary) return;
+    const primaryItem = index.items[primary];
+    if (!primaryItem || !primaryItem.paths || !primaryItem.paths.raw) return;
+    const primaryRawAbs = path.isAbsolute(primaryItem.paths.raw)
+      ? primaryItem.paths.raw
+      : path.join(ROOT, primaryItem.paths.raw);
+    const primaryRaw = safeReadJson(primaryRawAbs);
+    const primarySet = setFromIconMetrics(primaryRaw);
+    if (primarySet.all.size === 0) return;
+
+    const fileKey = String(primaryItem.fileKey || "").trim();
+    const candidates = Object.keys(index.items)
+      .filter((k) => k !== primary && index.items[k] && index.items[k].fileKey === fileKey)
+      .map((k) => ({ key: k, item: index.items[k] }));
+
+    candidates.forEach((cand) => {
+      const rawPath = cand.item && cand.item.paths ? cand.item.paths.raw : "";
+      if (!rawPath) return;
+      const rawAbs = path.isAbsolute(rawPath) ? rawPath : path.join(ROOT, rawPath);
+      const raw = safeReadJson(rawAbs);
+      const set = setFromIconMetrics(raw);
+      if (set.all.size === 0) return;
+
+      const shared = intersectionSize(primarySet.all, set.all);
+      const sharedInstance = intersectionSize(primarySet.instance, set.instance);
+      const score = jaccard(primarySet.all, set.all);
+
+      const promote =
+        sharedInstance >= args.promoteMinSharedInstance &&
+        score >= args.promoteMinJaccard;
+
+      const ok =
+        promote ||
+        (shared >= args.minShared &&
+          sharedInstance >= args.minSharedInstance &&
+          score >= args.minJaccard);
+      if (!ok) {
+        const suggestOk =
+          shared >= args.suggestMinShared &&
+          sharedInstance >= args.suggestMinSharedInstance &&
+          score >= args.suggestMinJaccard;
+        if (suggestOk) {
+          suggestions.push({
+            from: primary,
+            to: cand.key,
+            fileKey,
+            shared,
+            sharedInstance,
+            jaccard: Number(score.toFixed(4)),
+          });
+        }
+        return;
+      }
+
+      addNode(flow, primary);
+      addNode(flow, cand.key);
+      const note = `auto: shared=${shared}, sharedInstance=${sharedInstance}, jaccard=${Number(
+        score.toFixed(3)
+      )}`;
+      if (addEdge(flow, primary, cand.key, "related_auto", note)) {
+        links += 1;
+      }
+    });
+  });
+
+  flow.updatedAt = new Date().toISOString();
+  index.updatedAt = new Date().toISOString();
+
+  if (!args.dryRun) {
+    writeJson(INDEX_ABS, index);
+  }
+  const suggestOutAbs = path.isAbsolute(args.suggestOut) ? args.suggestOut : path.join(ROOT, args.suggestOut);
+  writeJson(suggestOutAbs, {
+    generatedAt: new Date().toISOString(),
+    flowId: args.flowId,
+    strict: process.env.FIGMA_UI_AUTOLINK_STRICT === "1",
+    thresholds: {
+      auto: { minShared: args.minShared, minSharedInstance: args.minSharedInstance, minJaccard: args.minJaccard },
+      promote: {
+        minSharedInstance: args.promoteMinSharedInstance,
+        minJaccard: args.promoteMinJaccard,
+      },
+      suggest: {
+        minShared: args.suggestMinShared,
+        minSharedInstance: args.suggestMinSharedInstance,
+        minJaccard: args.suggestMinJaccard,
+      },
+    },
+    links,
+    suggestions,
+  });
+
+  console.log(
+    `[auto-link-related-from-batch] ok links=${links} suggestions=${suggestions.length} flow=${args.flowId} dryRun=${args.dryRun ? "1" : "0"} suggestOut=${suggestOutAbs}`
+  );
+
+  if (process.env.FIGMA_UI_AUTOLINK_STRICT === "1" && suggestions.length) {
+    process.exit(3);
+  }
+}
+
+main();
+

package/scripts/cross-project-e2e.js

@@ -16,6 +16,21 @@ function resolveMaybeAbsolutePath(input) {
   return path.isAbsolute(input) ? path.normalize(input) : path.join(ROOT, input);
 }
 
+/** Batch / CLI `target` paths are relative to the target business project root (not toolchain cwd). */
+function resolveTargetInProject(rawTarget, targetProject) {
+  if (!rawTarget) {
+    return "";
+  }
+  const trimmed = String(rawTarget).trim();
+  if (!trimmed) {
+    return "";
+  }
+  if (path.isAbsolute(trimmed)) {
+    return path.normalize(trimmed);
+  }
+  return path.join(targetProject, trimmed);
+}
+
 function parseArgs(argv) {
   const options = {
     targetProject: "",
@@ -31,9 +46,13 @@ function parseArgs(argv) {
     autoBootstrapContract: true,
     autoEnsureOnMiss: false,
     allowSkeletonWithFigmaMcp: false,
-    completeness: "layout,text,tokens,interactions,states,accessibility",
+    // Default to "best effort" evidence to support 1:1 audits out-of-the-box.
+    completeness: "layout,text,tokens,assets,interactions,states,accessibility",
     batchFile: "",
     fixLoop: 0,
+    emitAgentTaskOnFail: false,
+    agentTaskPath: "",
+    allowSkippedCodeLevelComparison: false,
   };
 
   argv.forEach((arg) => {
@@ -103,6 +122,18 @@ function parseArgs(argv) {
     if (arg.startsWith("--fix-loop=")) {
       const n = Number(arg.split("=").slice(1).join("=").trim());
       options.fixLoop = Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
+      return;
+    }
+    if (arg === "--emit-agent-task-on-fail") {
+      options.emitAgentTaskOnFail = true;
+      return;
+    }
+    if (arg.startsWith("--agent-task-path=")) {
+      options.agentTaskPath = arg.split("=").slice(1).join("=").trim();
+      return;
+    }
+    if (arg === "--allow-skipped-code-level-comparison") {
+      options.allowSkippedCodeLevelComparison = true;
     }
   });
 
@@ -164,6 +195,63 @@ function normalizeSlash(input) {
   return String(input || "").replace(/\\/g, "/");
 }
 
+function writeAgentTask(targetProject, options, payload) {
+  const defaultPath = path.join(targetProject, "agent-task.md");
+  const taskPath = options.agentTaskPath
+    ? resolveMaybeAbsolutePath(options.agentTaskPath)
+    : defaultPath;
+  const lines = [];
+  lines.push("# Agent Task: UI E2E Recovery");
+  lines.push("");
+  lines.push("## Goal");
+  lines.push("Fix target project implementation so ui acceptance passes.");
+  lines.push("");
+  lines.push("## Constraints");
+  lines.push("- Must run ui acceptance after code changes.");
+  lines.push("- Do not bypass by lowering thresholds unless explicitly requested.");
+  lines.push("- Prioritize real component/contract/recipe fixes.");
+  lines.push("");
+  lines.push("## Context");
+  lines.push(`- targetProject: ${normalizeSlash(payload.targetProject || "")}`);
+  lines.push(`- mode: ${payload.mode || "single"}`);
+  lines.push(`- profile: ${payload.profile || "standard"}`);
+  lines.push(`- autoEnsureOnMiss: ${payload.autoEnsureOnMiss ? "true" : "false"}`);
+  lines.push(`- fixLoop: ${Number(payload.fixLoop || 0)}`);
+  lines.push("");
+  lines.push("## Cases");
+  (payload.cases || []).forEach((entry, idx) => {
+    lines.push(`### Case ${idx + 1}`);
+    lines.push(`- cacheKey: ${entry.cacheKey || ""}`);
+    lines.push(`- targetPath: ${normalizeSlash(entry.targetPath || "")}`);
+    lines.push(`- reason: ${entry.reason || "unknown"}`);
+    if (entry.attemptLogs && entry.attemptLogs.length) {
+      lines.push("- attemptLogs:");
+      entry.attemptLogs.forEach((log) => {
+        lines.push(
+          `  - attempt ${log.attempt}: ${log.ok ? "ok" : "fail"}${log.reason ? ` (${log.reason})` : ""}`
+        );
+      });
+    }
+    lines.push("");
+  });
+  lines.push("## Required Command");
+  lines.push("Run this command in toolchain repo after fixes:");
+  lines.push("");
+  lines.push("```bash");
+  lines.push(payload.retryCommand || "npm run figma:ui:e2e:cross -- --target-project=<...>");
+  lines.push("```");
+  lines.push("");
+  lines.push("## Completion Criteria");
+  lines.push("- e2e command exits with code 0");
+  lines.push("- summaryStatus is healthy");
+  lines.push("- no unresolved blocking items");
+  lines.push("");
+
+  fs.mkdirSync(path.dirname(taskPath), { recursive: true });
+  fs.writeFileSync(taskPath, `${lines.join("\n")}\n`, "utf8");
+  return taskPath;
+}
+
 function parseCacheKey(cacheKey) {
   const value = String(cacheKey || "").trim();
   const [fileKey, nodeId] = value.split("#");
@@ -256,10 +344,13 @@ function runSingleCase(input, context) {
   if (!cacheKey) {
     throw new Error("batch item missing cacheKey or (fileKey + nodeId)");
   }
-  const targetPath = item.target ? resolveMaybeAbsolutePath(item.target) : "";
+  const targetPath = item.target ? resolveTargetInProject(item.target, targetProject) : "";
   if (!targetPath) {
     throw new Error(`batch item ${cacheKey} missing target path`);
   }
+  if (!fs.existsSync(targetPath)) {
+    throw new Error(`batch item ${cacheKey} target path does not exist: ${targetPath}`);
+  }
 
   const acceptArgs = [
     `--cacheKey=${cacheKey}`,
@@ -301,6 +392,18 @@ function runSingleCase(input, context) {
       try {
         acceptanceJson = JSON.parse(acceptanceOutput);
       } catch {}
+      if (
+        !options.allowSkippedCodeLevelComparison &&
+        acceptanceJson &&
+        Array.isArray(acceptanceJson.warnings) &&
+        acceptanceJson.warnings.some((entry) =>
+          /code-level comparison skipped/i.test(String(entry || ""))
+        )
+      ) {
+        throw new Error(
+          `acceptance produced skipped code-level comparison for ${cacheKey}; target linkage is invalid`
+        );
+      }
       attemptLogs.push({ attempt, ok: true });
       return {
         ok: true,
@@ -339,11 +442,15 @@ function run() {
   }
   const isBatchMode = !!options.batchFile;
   if (!isBatchMode) {
-    const targetPath = options.target ? resolveMaybeAbsolutePath(options.target) : "";
+    const targetPath = options.target ? resolveTargetInProject(options.target, targetProject) : "";
     if (!targetPath) {
       console.error("cross-project-e2e failed: --target is required for real component validation");
       process.exit(FAIL_EXIT_CODE);
     }
+    if (!fs.existsSync(targetPath)) {
+      console.error(`cross-project-e2e failed: --target path does not exist: ${targetPath}`);
+      process.exit(FAIL_EXIT_CODE);
+    }
     const cacheKey = resolveCacheKey(options);
     if (!cacheKey) {
       console.error("cross-project-e2e failed: provide --cacheKey or (--fileKey + --nodeId)");
@@ -352,6 +459,7 @@ function run() {
   }
 
   let tarballPath = "";
+  let taskPayload = null;
   try {
     tarballPath = npmPackAndGetTarball();
     runCommand(`npm i -D "${tarballPath}"`, targetProject);
@@ -404,11 +512,26 @@ function run() {
         caseFailures.push({
           index: indexNo,
           cacheKey: entry && (entry.cacheKey || resolveCacheKey(entry)),
+          targetPath: entry && entry.target,
+          attemptLogs: [],
           reason: error.message,
         });
       }
     });
     if (caseFailures.length) {
+      taskPayload = {
+        targetProject,
+        mode: isBatchMode ? "batch" : "single",
+        profile: options.profile || "standard",
+        autoEnsureOnMiss: options.autoEnsureOnMiss,
+        fixLoop: options.fixLoop,
+        cases: caseFailures,
+        retryCommand: `npm run figma:ui:e2e:cross -- --target-project=${normalizeSlash(
+          targetProject
+        )}${options.batchFile ? ` --batch-file=${normalizeSlash(options.batchFile)}` : ""}${
+          options.autoEnsureOnMiss ? " --auto-ensure-on-miss" : ""
+        }${options.fixLoop ? ` --fix-loop=${options.fixLoop}` : ""}`,
+      };
       throw new Error(`batch cases failed: ${JSON.stringify(caseFailures)}`);
     }
 
@@ -424,9 +547,9 @@ function run() {
       completeness: options.completeness,
       tarballPath,
       reports: {
-        preflight: path.join(reportBase, "ui-preflight-report.json"),
-        audit: path.join(reportBase, "ui-1to1-report.json"),
-        summary: path.join(reportBase, "ui-quality-summary.json"),
+        preflight: path.join(reportBase, "runtime", "ui-preflight-report.json"),
+        audit: path.join(reportBase, "runtime", "ui-1to1-report.json"),
+        summary: path.join(reportBase, "runtime", "ui-quality-summary.json"),
       },
       cases: caseResults,
     };
@@ -438,8 +561,42 @@ function run() {
     }
     console.log(JSON.stringify(output, null, 2));
   } catch (error) {
+    let taskPath = "";
+    if (options.emitAgentTaskOnFail) {
+      try {
+        const payload =
+          taskPayload ||
+          ({
+            targetProject,
+            mode: isBatchMode ? "batch" : "single",
+            profile: options.profile || "standard",
+            autoEnsureOnMiss: options.autoEnsureOnMiss,
+            fixLoop: options.fixLoop,
+            cases: [
+              {
+                cacheKey: resolveCacheKey(options),
+                targetPath: options.target,
+                reason: error.message,
+              },
+            ],
+            retryCommand: `npm run figma:ui:e2e:cross -- --target-project=${normalizeSlash(
+              targetProject
+            )}${options.batchFile ? ` --batch-file=${normalizeSlash(options.batchFile)}` : ""}${
+              options.cacheKey ? ` --cacheKey=${options.cacheKey}` : ""
+            }${options.fileKey ? ` --fileKey=${options.fileKey}` : ""}${
+              options.nodeId ? ` --nodeId=${options.nodeId}` : ""
+            }${options.target ? ` --target=${normalizeSlash(options.target)}` : ""}${
+              options.autoEnsureOnMiss ? " --auto-ensure-on-miss" : ""
+            }${options.fixLoop ? ` --fix-loop=${options.fixLoop}` : ""} --emit-agent-task-on-fail`,
+          });
+        taskPath = writeAgentTask(targetProject, options, payload);
+      } catch {}
+    }
     console.error("cross-project-e2e failed:");
     console.error(`- ${error.message}`);
+    if (taskPath) {
+      console.error(`- agent task emitted: ${normalizeSlash(taskPath)}`);
+    }
     process.exit(FAIL_EXIT_CODE);
   } finally {
     if (tarballPath && !options.keepPackage) {