figma-cache-toolchain 2.0.4 → 2.0.7

package/scripts/forbidden-markup-check.cjs

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Toolchain-provided forbidden markup check.
+ * Projects can call this script directly from node_modules to hard-fail on disallowed UI patterns.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const ROOT = process.cwd();
+
+const DEFAULT_CONSTRAINTS_PATH = path.join(ROOT, "ui-hard-constraints.json");
+const DEFAULT_POLICY_PATH = path.join(ROOT, "ui-policy.json");
+const DEFAULT_PLATFORM = "web-vue";
+
+function parseArgs(argv) {
+  const out = {
+    batch: path.join(ROOT, "figma-e2e-batch.json"),
+    files: [],
+    constraints: DEFAULT_CONSTRAINTS_PATH,
+    policy: DEFAULT_POLICY_PATH,
+    platform: DEFAULT_PLATFORM,
+    adapter: "",
+  };
+  argv.slice(2).forEach((arg) => {
+    if (arg.startsWith("--batch=")) {
+      out.batch = arg.split("=").slice(1).join("=").trim();
+      return;
+    }
+    if (arg.startsWith("--file=")) {
+      out.files.push(arg.split("=").slice(1).join("=").trim());
+      return;
+    }
+    if (arg.startsWith("--constraints=")) {
+      out.constraints = arg.split("=").slice(1).join("=").trim();
+      return;
+    }
+    if (arg.startsWith("--policy=")) {
+      out.policy = arg.split("=").slice(1).join("=").trim();
+      return;
+    }
+    if (arg.startsWith("--platform=")) {
+      out.platform = arg.split("=").slice(1).join("=").trim();
+      return;
+    }
+    if (arg.startsWith("--adapter=")) {
+      out.adapter = arg.split("=").slice(1).join("=").trim();
+      return;
+    }
+  });
+  return out;
+}
+
+function readJsonIfExists(absPath) {
+  if (!absPath) return null;
+  if (!fs.existsSync(absPath)) return null;
+  return JSON.parse(fs.readFileSync(absPath, "utf8"));
+}
+
+function resolveAdapterPath(platform, adapterArg) {
+  if (adapterArg) return adapterArg;
+  const file = `ui-adapter.${platform}.json`;
+  return path.join(ROOT, file);
+}
+
+function normalizePrimitiveDetectors(raw) {
+  if (!raw)
+    return { forbiddenTags: [], forbiddenAttrPrefixes: [], forbiddenAttrNames: [], forbiddenPatterns: [] };
+  const forbiddenTags = Array.isArray(raw.forbiddenTags) ? raw.forbiddenTags.map(String) : [];
+  const forbiddenAttrPrefixes = Array.isArray(raw.forbiddenAttrPrefixes)
+    ? raw.forbiddenAttrPrefixes.map(String)
+    : [];
+  const forbiddenAttrNames = Array.isArray(raw.forbiddenAttrNames) ? raw.forbiddenAttrNames.map(String) : [];
+  const forbiddenPatterns = Array.isArray(raw.forbiddenPatterns) ? raw.forbiddenPatterns : [];
+  return { forbiddenTags, forbiddenAttrPrefixes, forbiddenAttrNames, forbiddenPatterns };
+}
+
+function compileConstraintsFromPolicy(policyRaw, adapterRaw) {
+  const policy = policyRaw || {};
+  const forbiddenPrimitives = Array.isArray(policy.forbiddenPrimitives)
+    ? policy.forbiddenPrimitives.map(String)
+    : [];
+  const primitives = (adapterRaw && adapterRaw.primitives) || {};
+
+  const acc = {
+    forbiddenTags: [],
+    forbiddenAttrPrefixes: [],
+    forbiddenAttrNames: [],
+    forbiddenPatterns: [],
+  };
+
+  forbiddenPrimitives.forEach((primitive) => {
+    const detectors = normalizePrimitiveDetectors(primitives[primitive]);
+    acc.forbiddenTags.push(...detectors.forbiddenTags);
+    acc.forbiddenAttrPrefixes.push(...detectors.forbiddenAttrPrefixes);
+    acc.forbiddenAttrNames.push(...detectors.forbiddenAttrNames);
+    acc.forbiddenPatterns.push(...detectors.forbiddenPatterns);
+  });
+
+  acc.forbiddenTags = Array.from(new Set(acc.forbiddenTags));
+  acc.forbiddenAttrPrefixes = Array.from(new Set(acc.forbiddenAttrPrefixes));
+  acc.forbiddenAttrNames = Array.from(new Set(acc.forbiddenAttrNames));
+  acc.forbiddenPatterns = acc.forbiddenPatterns.filter(Boolean);
+
+  return acc;
+}
+
+function normalizeConstraints(raw) {
+  const g = (raw && raw.global) || raw || {};
+  const forbiddenTags = Array.isArray(g.forbiddenTags) ? g.forbiddenTags.map(String) : [];
+  const forbiddenAttrPrefixes = Array.isArray(g.forbiddenAttrPrefixes)
+    ? g.forbiddenAttrPrefixes.map(String)
+    : [];
+  const forbiddenAttrNames = Array.isArray(g.forbiddenAttrNames) ? g.forbiddenAttrNames.map(String) : [];
+  const forbiddenPatterns = Array.isArray(g.forbiddenPatterns) ? g.forbiddenPatterns : [];
+
+  return {
+    forbiddenTags,
+    forbiddenAttrPrefixes,
+    forbiddenAttrNames,
+    forbiddenPatterns: forbiddenPatterns
+      .map((x) => ({
+        id: String(x && x.id ? x.id : "pattern"),
+        re: new RegExp(String(x && x.pattern ? x.pattern : ""), "i"),
+      }))
+      .filter((x) => x.re && String(x.re) !== String(/(?:)/i)),
+  };
+}
+
+function mergeConstraints(base, override) {
+  if (!override) return base;
+  const next = { ...base };
+  if (Array.isArray(override.forbiddenTags)) next.forbiddenTags = override.forbiddenTags.map(String);
+  if (Array.isArray(override.forbiddenAttrPrefixes))
+    next.forbiddenAttrPrefixes = override.forbiddenAttrPrefixes.map(String);
+  if (Array.isArray(override.forbiddenAttrNames)) next.forbiddenAttrNames = override.forbiddenAttrNames.map(String);
+  if (Array.isArray(override.forbiddenPatterns)) {
+    next.forbiddenPatterns = override.forbiddenPatterns
+      .map((x) => ({
+        id: String(x && x.id ? x.id : "pattern"),
+        re: new RegExp(String(x && x.pattern ? x.pattern : ""), "i"),
+      }))
+      .filter((x) => x.re && String(x.re) !== String(/(?:)/i));
+  }
+  return next;
+}
+
+function readBatchTargets(batchPath) {
+  const abs = path.isAbsolute(batchPath) ? batchPath : path.join(ROOT, batchPath);
+  if (!fs.existsSync(abs)) throw new Error(`batch file missing: ${abs}`);
+  const payload = JSON.parse(fs.readFileSync(abs, "utf8"));
+  if (!Array.isArray(payload) || payload.length === 0) {
+    throw new Error("batch file must contain at least one item");
+  }
+  return payload.map((item, idx) => {
+    const target = String(item && item.target ? item.target : "").trim();
+    if (!target) throw new Error(`case[${idx}] missing target`);
+    const absTarget = path.isAbsolute(target) ? path.normalize(target) : path.join(ROOT, target);
+    const constraintsOverride = item && item.constraints ? item.constraints : null;
+    const policyOverride = item && item.policy ? item.policy : null;
+    return { absTarget, constraintsOverride, policyOverride };
+  });
+}
+
+function applyPolicyOverride(basePolicy, policyOverride) {
+  if (!policyOverride) return basePolicy;
+  const next = { ...(basePolicy || {}) };
+  const baseForbidden = Array.isArray(next.forbiddenPrimitives) ? next.forbiddenPrimitives.map(String) : [];
+  const addForbidden = Array.isArray(policyOverride.forbiddenPrimitives)
+    ? policyOverride.forbiddenPrimitives.map(String)
+    : [];
+  const allow = Array.isArray(policyOverride.allowPrimitives) ? policyOverride.allowPrimitives.map(String) : [];
+
+  const merged = Array.from(new Set([...baseForbidden, ...addForbidden]));
+  next.forbiddenPrimitives = merged.filter((x) => !allow.includes(x));
+  return next;
+}
+
+function scanFile(absPath, constraints) {
+  const content = fs.readFileSync(absPath, "utf8");
+  const violations = [];
+
+  constraints.forbiddenTags.forEach((tag) => {
+    const re = new RegExp(`<\\s*${tag}(\\s|>|/)`, "gi");
+    if (re.test(content)) violations.push(`forbidden tag: <${tag}>`);
+  });
+
+  constraints.forbiddenAttrPrefixes.forEach((prefix) => {
+    const re = new RegExp(`\\s${prefix}[a-z0-9_-]+\\s*=`, "gi");
+    if (re.test(content)) violations.push(`forbidden attr prefix: ${prefix}*`);
+  });
+
+  constraints.forbiddenAttrNames.forEach((name) => {
+    const re = new RegExp(`\\s${name}\\s*=`, "gi");
+    if (re.test(content)) violations.push(`forbidden attr: ${name}`);
+  });
+
+  constraints.forbiddenPatterns.forEach((item) => {
+    if (item.re.test(content)) violations.push(`forbidden pattern: ${item.id}`);
+  });
+
+  // Require cursor-pointer on interactive elements (Vue template heuristic).
+  const clickLike =
+    /<([a-zA-Z][\w-]*)([^>]*)(@click|@pointerdown|@mousedown|@mouseup)\s*=\s*["'][^"']+["']([^>]*)>/g;
+  let match = null;
+  while ((match = clickLike.exec(content))) {
+    const tag = String(match[1] || "");
+    const attrs = `${match[2] || ""}${match[4] || ""}`;
+    if (!/cursor-pointer/.test(attrs)) {
+      violations.push(`missing cursor-pointer on interactive <${tag}>`);
+    }
+  }
+
+  // Avoid icon distortion: forbid icon-like img stretching combo.
+  const imgSizeFullIconLike =
+    /<img[^>]*class\s*=\s*["'][^"']*\bmax-w-none\b[^"']*\binset-0\b[^"']*\bsize-full\b[^"']*["'][^>]*>/gi;
+  if (imgSizeFullIconLike.test(content)) {
+    violations.push("forbidden icon img classes: max-w-none + inset-0 + size-full (causes icon stretching)");
+  }
+
+  return violations;
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+
+  const policyPath = path.isAbsolute(args.policy) ? args.policy : path.join(ROOT, args.policy);
+  const adapterPathRaw = resolveAdapterPath(args.platform, args.adapter);
+  const adapterPath = path.isAbsolute(adapterPathRaw) ? adapterPathRaw : path.join(ROOT, adapterPathRaw);
+
+  const policyRaw = readJsonIfExists(policyPath);
+  const adapterRaw = readJsonIfExists(adapterPath);
+  const canUsePolicy = Boolean(policyRaw && adapterRaw);
+
+  const constraintsPath = path.isAbsolute(args.constraints) ? args.constraints : path.join(ROOT, args.constraints);
+  const legacyConstraintsRaw = readJsonIfExists(constraintsPath) || {
+    global: {
+      forbiddenTags: ["button", "p", "ul", "li"],
+      forbiddenAttrPrefixes: ["aria-"],
+      forbiddenAttrNames: ["role", "tabindex"],
+      forbiddenPatterns: [
+        { id: "custom scrollbar wrapper: scrollbar-hint", pattern: "\\bscrollbar-hint\\b" },
+        { id: "custom scrollbar wrapper: hide-native-scrollbar", pattern: "\\bhide-native-scrollbar\\b" },
+      ],
+    },
+  };
+
+  const globalConstraints = canUsePolicy
+    ? normalizeConstraints(compileConstraintsFromPolicy(policyRaw, adapterRaw))
+    : normalizeConstraints(legacyConstraintsRaw);
+
+  const explicitFiles = (args.files || [])
+    .map((p) => (path.isAbsolute(p) ? p : path.join(ROOT, p)))
+    .filter(Boolean);
+
+  const batchItems = explicitFiles.length
+    ? explicitFiles.map((absTarget) => ({ absTarget, constraintsOverride: null, policyOverride: null }))
+    : readBatchTargets(args.batch);
+
+  const missing = batchItems.map((x) => x.absTarget).filter((p) => !fs.existsSync(p));
+  if (missing.length) {
+    console.error("[forbidden-markup-check] missing target files:");
+    missing.forEach((p) => console.error(`- ${p}`));
+    process.exit(2);
+  }
+
+  const allViolations = [];
+  batchItems.forEach((item) => {
+    const compiledForCase = canUsePolicy
+      ? normalizeConstraints(compileConstraintsFromPolicy(applyPolicyOverride(policyRaw, item.policyOverride), adapterRaw))
+      : globalConstraints;
+    const effective = mergeConstraints(compiledForCase, item.constraintsOverride);
+    const violations = scanFile(item.absTarget, effective);
+    if (violations.length) {
+      allViolations.push({ file: item.absTarget, violations });
+    }
+  });
+
+  if (allViolations.length) {
+    console.error("[forbidden-markup-check] FAILED. Found forbidden markup.");
+    console.error("Rules:");
+    console.error(`- tags: ${globalConstraints.forbiddenTags.map((t) => `<${t}>`).join(", ")}`);
+    console.error(
+      `- attrs: ${globalConstraints.forbiddenAttrNames.join(", ")}, ${globalConstraints.forbiddenAttrPrefixes.join("")}*`
+    );
+    console.error("");
+    allViolations.forEach((item) => {
+      console.error(item.file);
+      item.violations.forEach((v) => console.error(`  - ${v}`));
+    });
+    process.exit(2);
+  }
+
+  console.log("[forbidden-markup-check] ok");
+}
+
+main();
+

package/scripts/generate-icon-insets-from-batch.cjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Generate iconInsets.<cacheKey>.generated.ts for each batch item.
+ * Output directory defaults to the target component directory (dirname(target)).
+ *
+ * Usage:
+ *   node scripts/generate-icon-insets-from-batch.cjs --batch=./figma-e2e-batch.json
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+
+const ROOT = process.cwd();
+const DEFAULT_INDEX_ABS = path.join(ROOT, "figma-cache", "index.json");
+
+function normalizeNodeId(input) {
+  const value = String(input || "").trim();
+  if (!value) return "";
+  return value.includes(":") ? value : value.replace(/-/g, ":");
+}
+
+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 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 toRelatedCacheKeys(item) {
+  const raw = item && item.relatedCacheKeys;
+  if (!raw) return [];
+  if (Array.isArray(raw)) return raw.map(normalizeCacheKey).filter(Boolean);
+  if (typeof raw === "string") {
+    return raw
+      .split(",")
+      .map((s) => normalizeCacheKey(s))
+      .filter(Boolean);
+  }
+  return [];
+}
+
+function extractCacheKeyFromFigmaUrl(url) {
+  const input = String(url || "").trim();
+  if (!input) return "";
+  // Matches:
+  // https://www.figma.com/design/<fileKey>/... ?node-id=9277-28552
+  // https://www.figma.com/file/<fileKey>/... ?node-id=9277%3A28552
+  const fileKeyMatch = input.match(/figma\.com\/(?:design|file)\/([^/]+)/i);
+  const nodeIdMatch = input.match(/[?&]node-id=([^&]+)/i);
+  if (!fileKeyMatch || !nodeIdMatch) return "";
+  const fileKey = String(fileKeyMatch[1] || "").trim();
+  const decodedNode = decodeURIComponent(String(nodeIdMatch[1] || "").trim());
+  const nodeId = normalizeNodeId(decodedNode);
+  if (!fileKey || !nodeId) return "";
+  return `${fileKey}#${nodeId}`;
+}
+
+function toRelatedUrls(item) {
+  const raw = item && item.relatedUrls;
+  if (!raw) return [];
+  if (Array.isArray(raw)) return raw.map((u) => String(u || "").trim()).filter(Boolean);
+  if (typeof raw === "string") {
+    return raw
+      .split(",")
+      .map((s) => String(s || "").trim())
+      .filter(Boolean);
+  }
+  return [];
+}
+
+function safeReadJson(absPath) {
+  try {
+    return JSON.parse(fs.readFileSync(absPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function relatedFromFlowIndex(cacheKey) {
+  const enabled = process.env.FIGMA_UI_RELATED_FROM_FLOW !== "0";
+  if (!enabled) return [];
+  const index = safeReadJson(DEFAULT_INDEX_ABS);
+  if (!index || typeof index !== "object" || !index.flows) return [];
+  const flows = index.flows;
+  const related = new Set();
+  Object.keys(flows).forEach((flowId) => {
+    const flow = flows[flowId];
+    const nodes = flow && Array.isArray(flow.nodes) ? flow.nodes : [];
+    if (!nodes.includes(cacheKey)) return;
+    nodes.forEach((k) => {
+      if (k && k !== cacheKey) related.add(normalizeCacheKey(k));
+    });
+  });
+  return Array.from(related).filter(Boolean);
+}
+
+function resolveTargetAbs(rawTarget) {
+  const trimmed = String(rawTarget || "").trim();
+  if (!trimmed) return "";
+  return path.isAbsolute(trimmed) ? path.normalize(trimmed) : path.join(ROOT, trimmed);
+}
+
+function parseArgs(argv) {
+  const out = {
+    batch: path.join(ROOT, "figma-e2e-batch.json"),
+    maxBox: 24,
+    toolchainGenerateScript: path.join(__dirname, "generate-icon-insets.cjs"),
+  };
+  argv.slice(2).forEach((arg) => {
+    if (arg.startsWith("--batch=")) out.batch = arg.split("=").slice(1).join("=").trim();
+    if (arg.startsWith("--max-box=")) out.maxBox = Number(arg.split("=").slice(1).join("=").trim());
+  });
+  return out;
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const batchAbs = path.isAbsolute(args.batch) ? args.batch : path.join(ROOT, args.batch);
+  if (!fs.existsSync(batchAbs)) {
+    console.error(`[generate-icon-insets-from-batch] batch not found: ${batchAbs}`);
+    process.exit(2);
+  }
+  const payload = JSON.parse(fs.readFileSync(batchAbs, "utf8"));
+  if (!Array.isArray(payload) || payload.length === 0) {
+    console.error("[generate-icon-insets-from-batch] batch must be a non-empty array");
+    process.exit(2);
+  }
+
+  const genAbs = args.toolchainGenerateScript;
+  if (!fs.existsSync(genAbs)) {
+    console.error(`[generate-icon-insets-from-batch] missing generator: ${genAbs}`);
+    process.exit(2);
+  }
+
+  const outputs = [];
+  payload.forEach((item, idx) => {
+    const cacheKey = String(item && (item.cacheKey || cacheKeyFromItem(item)) || "").trim();
+    const targetAbs = resolveTargetAbs(item && item.target);
+    const relatedCacheKeysExplicit = toRelatedCacheKeys(item);
+    const relatedCacheKeysFromUrls = toRelatedUrls(item)
+      .map(extractCacheKeyFromFigmaUrl)
+      .map(normalizeCacheKey)
+      .filter(Boolean);
+    const relatedCacheKeysFromFlow = relatedFromFlowIndex(cacheKey);
+    const relatedCacheKeys = Array.from(
+      new Set([...relatedCacheKeysExplicit, ...relatedCacheKeysFromUrls, ...relatedCacheKeysFromFlow])
+    ).filter(Boolean);
+    if (!cacheKey) {
+      console.error(`[generate-icon-insets-from-batch] case[${idx}] missing cacheKey or (fileKey+nodeId)`);
+      process.exit(2);
+    }
+    if (!targetAbs) {
+      console.error(`[generate-icon-insets-from-batch] case[${idx}] missing target`);
+      process.exit(2);
+    }
+    const targetDir = path.dirname(targetAbs);
+    const rawArgs = [cacheKey, ...relatedCacheKeys]
+      .map((ck) => {
+        const [fk, nid] = String(ck).split("#");
+        const safeNodeDir = String(nid || "").replace(/:/g, "-");
+        const rawAbs = path.join(ROOT, "figma-cache", "files", fk, "nodes", safeNodeDir, "raw.json");
+        if (!fs.existsSync(rawAbs)) {
+          console.error(`[generate-icon-insets-from-batch] raw.json not found for ${ck}: ${rawAbs}`);
+          process.exit(2);
+        }
+        return `--raw="${rawAbs}"`;
+      })
+      .join(" ");
+
+    execSync(`node "${genAbs}" ${rawArgs} --out-dir="${targetDir}" --cacheKey="${cacheKey}" --max-box=${args.maxBox}`, {
+      cwd: ROOT,
+      stdio: "pipe",
+    });
+    outputs.push({ cacheKey, outDir: targetDir });
+  });
+
+  console.log(
+    `[generate-icon-insets-from-batch] ok (${outputs.length} cases)`
+  );
+}
+
+main();
+

package/scripts/generate-icon-insets.cjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Toolchain-provided icon inset exporter.
+ * Reads raw.json.iconMetrics and emits a TS mapping file for machine consumption.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+function parseArgs(argv) {
+  const out = {
+    raw: [],
+    out: "",
+    maxBox: 24,
+    cacheKey: "",
+    outDir: "",
+  };
+  argv.slice(2).forEach((arg) => {
+    if (arg.startsWith("--raw=")) out.raw.push(arg.split("=").slice(1).join("=").trim());
+    if (arg.startsWith("--out=")) out.out = arg.split("=").slice(1).join("=").trim();
+    if (arg.startsWith("--out-dir=")) out.outDir = arg.split("=").slice(1).join("=").trim();
+    if (arg.startsWith("--cacheKey=")) out.cacheKey = arg.split("=").slice(1).join("=").trim();
+    if (arg.startsWith("--max-box=")) out.maxBox = Number(arg.split("=").slice(1).join("=").trim());
+  });
+  return out;
+}
+
+function readJson(absPath) {
+  return JSON.parse(fs.readFileSync(absPath, "utf8"));
+}
+
+function formatNumber(n) {
+  const num = Number(n);
+  if (!Number.isFinite(num)) return "0";
+  return String(Number(num.toFixed(4))).replace(/\.0+$/, "");
+}
+
+function buildTs(mapping) {
+  const lines = [];
+  lines.push(`export type InsetsPx = { top: number; right: number; bottom: number; left: number };`);
+  lines.push("");
+  lines.push("/**");
+  lines.push(" * AUTO-GENERATED.");
+  lines.push(" * Source: raw.json.iconMetrics (derived from get_design_context inset percentages)");
+  lines.push(" */");
+  lines.push("export const ICON_INSETS_PX: Record<string, InsetsPx> = {");
+  Object.keys(mapping)
+    .sort()
+    .forEach((key) => {
+      const v = mapping[key];
+      lines.push(
+        `  "${key}": { top: ${formatNumber(v.top)}, right: ${formatNumber(v.right)}, bottom: ${formatNumber(
+          v.bottom
+        )}, left: ${formatNumber(v.left)} },`
+      );
+    });
+  lines.push("};");
+  lines.push("");
+  return `${lines.join("\n")}\n`;
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  if (!args.raw.length || (!args.out && !(args.outDir && args.cacheKey))) {
+    console.error(
+      "Usage: node scripts/generate-icon-insets.cjs --raw=<raw.json> [--raw=<raw2.json> ...] (--out=<out.ts> | --out-dir=<dir> --cacheKey=<cacheKey>) [--max-box=24]"
+    );
+    process.exit(2);
+  }
+  const computedOut = args.out
+    ? args.out
+    : path.join(
+        args.outDir,
+        `iconInsets.${String(args.cacheKey || "")
+          .replace(/[^a-zA-Z0-9._-]+/g, "_")
+          .slice(0, 120)}.generated.ts`
+      );
+  const outAbs = path.isAbsolute(computedOut) ? computedOut : path.join(process.cwd(), computedOut);
+
+  const mapping = {};
+  args.raw.forEach((rawPath) => {
+    const rawAbs = path.isAbsolute(rawPath) ? rawPath : path.join(process.cwd(), rawPath);
+    const data = readJson(rawAbs);
+    const list = Array.isArray(data && data.iconMetrics) ? data.iconMetrics : [];
+    list.forEach((item) => {
+      if (!item || typeof item !== "object") return;
+      const nodeId = String(item.nodeId || "").trim();
+      const boxPx = Number(item.boxPx);
+      const insetPx = item.insetPx;
+      if (!nodeId) return;
+      if (!Number.isFinite(boxPx) || boxPx <= 0 || boxPx > args.maxBox) return;
+      if (!insetPx || typeof insetPx !== "object") return;
+      // First write wins to keep stable precedence: primary cacheKey first, related next.
+      if (mapping[nodeId]) return;
+      mapping[nodeId] = {
+        top: Number(insetPx.top || 0),
+        right: Number(insetPx.right || 0),
+        bottom: Number(insetPx.bottom || 0),
+        left: Number(insetPx.left || 0),
+      };
+    });
+  });
+
+  fs.mkdirSync(path.dirname(outAbs), { recursive: true });
+  fs.writeFileSync(outAbs, buildTs(mapping), "utf8");
+  console.log(`[generate-icon-insets] wrote ${Object.keys(mapping).length} entries -> ${outAbs}`);
+}
+
+main();
+