figma-cache-toolchain 2.0.5 → 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,7 +46,8 @@ 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,
@@ -328,7 +344,7 @@ 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`);
   }
@@ -426,7 +442,7 @@ 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);

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();
+