@bridge-ds/cli 0.3.1 → 0.4.0

package/dist/index.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { existsSync as existsSync5 } from "node:fs";
-import { readFile as readFile5, writeFile as writeFile4 } from "node:fs/promises";
-import { isAbsolute, join as join5, relative as relative4, resolve as resolve3 } from "node:path";
+import { existsSync as existsSync6 } from "node:fs";
+import { readFile as readFile6, writeFile as writeFile5 } from "node:fs/promises";
+import { isAbsolute, join as join6, relative as relative4, resolve as resolve3 } from "node:path";
 
 // ../core/src/audit/types.ts
 var AUDIT_SCHEMA_VERSION = 1;
@@ -602,6 +602,10 @@ var EQUIVALENTS = [
   [/^Badge$/, ["Badge"]],
   [/^(Chip|Tag|ChipField)$/, ["Tag", "Badge"]],
   [/^(Alert|AlertTitle|Callout)$/, ["Alert"]],
+  [/^(Banner|AnnouncementBar|TopBanner)$/, ["Banner", "Alert"]],
+  [/^(CodeBlock|Code|CodeSnippet|Snippet|Prism|SyntaxHighlighter|CopyBlock)$/, ["CodeBlock"]],
+  [/^(RadioCard|RadioCards|RadioTile|ChoiceCard|ChoiceCardGroup)$/, ["ChoiceCard", "RadioGroup"]],
+  [/^(Checklist|ChecklistItem|StepList)$/, ["Checklist"]],
   [/^(Snackbar|Toast|Toaster|Notification)$/, ["Toast"]],
   [/^(CircularProgress|Spinner|Loading|LoadingIndicator)$/, ["Spinner", "Progress"]],
   [/^(LinearProgress|Progress)$/, ["Progress"]],
@@ -1147,6 +1151,26 @@ var THEME_FNS = /^(createTheme|extendTheme|createMuiTheme|responsiveFontSizes|ex
 var CSS_TAGS = /^(styled(\.\w+|\(.*\)(\.attrs\(.*\))?)|css|keyframes|createGlobalStyle|injectGlobal|tw\.\w+)$/s;
 var MUI_SPACING_ATTR = /^([mp][trblxy]?|(margin|padding)(Top|Bottom|Left|Right|X|Y)?|gap|rowGap|columnGap|spacing)$/;
 var THEME_REF_RE = /\btheme\.(palette|spacing|shape|typography|shadows|zIndex|transitions|vars)\b/g;
+var DOM_RENDERER_RE = /^([a-z][A-Za-z0-9]*?)(Html|HTML|HtmlAttributes|Attributes|ClassName)$/;
+function domRendererComponent(fn, components) {
+  const m = DOM_RENDERER_RE.exec(fn);
+  if (!m) return void 0;
+  const pascal2 = m[1][0].toUpperCase() + m[1].slice(1);
+  if (components.has(pascal2)) return pascal2;
+  return [...components].filter((c) => pascal2.startsWith(c)).sort((a, b) => b.length - a.length)[0];
+}
+var LOOKALIKE_CLASSES = { pill: "Badge", badge: "Badge", chip: "Tag", tooltip: "Tooltip", tip: "Tooltip", "has-tip": "Tooltip" };
+var LOOKALIKE_ATTRS = { "data-tip": "Tooltip" };
+var HTML_CLASS_RE = /\bclass(?:Name)?\s*=\s*["']([^"'$]*)/g;
+var HTML_ATTR_RE = /\s(data-tip)\s*=/g;
+function lookalikesInClassList(list2, components) {
+  const out = [];
+  for (const token of list2.split(/\s+/)) {
+    const component = LOOKALIKE_CLASSES[token];
+    if (component && components.has(component) && !out.some((o) => o.component === component)) out.push({ token, component });
+  }
+  return out;
+}
 function kindFor(path) {
   return path.endsWith(".tsx") ? ts.ScriptKind.TSX : path.endsWith(".jsx") ? ts.ScriptKind.JSX : path.endsWith(".ts") || path.endsWith(".mts") || path.endsWith(".cts") ? ts.ScriptKind.TS : ts.ScriptKind.JSX;
 }
@@ -1166,6 +1190,79 @@ function contextForDeclaration(name, typeText) {
   if (/^(styles?|sx|classes)$|Styles?$|Sx$/.test(name)) return /sx$/i.test(name) ? "sx" : "styled";
   return null;
 }
+function importsOf(path, text) {
+  const sf = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, false, kindFor(path));
+  const imports = /* @__PURE__ */ new Map();
+  for (const node of sf.statements) {
+    if (!ts.isImportDeclaration(node) || !ts.isStringLiteral(node.moduleSpecifier)) continue;
+    const mod = node.moduleSpecifier.text;
+    const c = node.importClause;
+    if (c?.name) imports.set(c.name.text, { module: mod, imported: "default" });
+    if (c?.namedBindings && ts.isNamespaceImport(c.namedBindings)) imports.set(c.namedBindings.name.text, { module: mod, imported: "*" });
+    if (c?.namedBindings && ts.isNamedImports(c.namedBindings)) for (const el of c.namedBindings.elements) imports.set(el.name.text, { module: mod, imported: (el.propertyName ?? el.name).text });
+  }
+  return imports;
+}
+function classifyTag(t, imports, ds) {
+  const { name } = t;
+  const at = { line: t.line, column: t.column };
+  if (/^[a-z][\w-]*$/.test(name)) {
+    if (!ds.nativeElements.includes(name)) return {};
+    if (name === "input" && t.type === "hidden") return {};
+    if (name === "a" && !t.hasHref) return {};
+    if (t.inRenderProp) return {};
+    const suggestion = nativeEquivalent(name, t.type, ds.components);
+    if (!suggestion) return {};
+    return { component: { ...at, name, kind: "native", library: "native", suggestion } };
+  }
+  const root = name.split(".")[0];
+  const imp = imports.get(root);
+  const ns = imp?.imported === "*";
+  const shown = imp && !ns && imp.imported !== "default" ? [imp.imported, ...name.split(".").slice(1)].join(".") : name;
+  const leaf = ns && name.includes(".") ? name.split(".").slice(1).join(".") : shown;
+  if (imp) {
+    const kind = classifyModule(imp.module, ds.packages, ds.foreignLibraries);
+    if (isNonVisual(leaf.split(".").pop())) return {};
+    if (kind === "ds") return { ds: leaf };
+    if (kind === "charts") return { component: { ...at, name: shown, kind: "foreign", library: libraryLabel(imp.module, kind) } };
+    if (kind === "other" && isRouterLink(imp.module, imp.imported === "default" ? "default" : leaf)) {
+      if (t.inRenderProp) return {};
+      const suggestion = ds.components.has("Link") ? "Link" : void 0;
+      return { component: { ...at, name: shown, kind: "foreign", library: libraryLabel(imp.module, kind), ...suggestion ? { suggestion } : {} } };
+    }
+    if (kind === "foreign" || kind === "shadcn") {
+      const suggestion = (ns ? dsEquivalent(root, ds.components) : void 0) ?? dsEquivalent(leaf, ds.components);
+      return { component: { ...at, name: shown, kind: "foreign", library: libraryLabel(imp.module, kind), ...suggestion ? { suggestion } : {} } };
+    }
+    if (kind === "local" && ds.components.has(leaf.split(".")[0])) return { component: { ...at, name: leaf, kind: "recreated", library: "local", suggestion: leaf.split(".")[0] } };
+    return {};
+  }
+  if (ds.components.has(root)) return { localCandidate: { ...at, name, kind: "recreated", library: "local", suggestion: root } };
+  return {};
+}
+function tailwindFindings(hits, offset, pos, ds) {
+  const findings = [];
+  let themeRefs = 0;
+  for (const h of hits) {
+    if (h.kind === "scale") {
+      themeRefs++;
+      continue;
+    }
+    if (h.kind === "token") continue;
+    let cat = h.category;
+    const v = h.value;
+    const isColor = Boolean(parseCssColor(v));
+    if (cat === "color-or-size") cat = isColor ? "color" : "font-size";
+    else if (cat === "color-or-width") cat = isColor ? "color" : "border-width";
+    else if (cat === "color-or-shadow") cat = isColor ? "color" : "shadow";
+    else if (cat === "font") cat = /^\d{3}$/.test(v) ? "font-weight" : "font-family";
+    if (cat === "color" && !isColor) continue;
+    const suggestion = ds.suggest(cat, v);
+    const cap = h.kind === "palette" && suggestion && suggestion.confidence > 0.6 ? { ...suggestion, confidence: 0.6, level: "medium" } : suggestion;
+    findings.push({ ...pos(offset + h.index), category: cat, value: h.cls, source: "tailwind", ...cap ? { suggestion: cap } : {} });
+  }
+  return { findings, themeRefs };
+}
 function scanCode(path, text, ds) {
   const sf = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, kindFor(path));
   const out = { findings: [], tokenUsages: 0, themeRefs: 0, ds: {}, components: [], definitions: [] };
@@ -1180,24 +1277,9 @@ function scanCode(path, text, ds) {
     out.findings.push({ ...pos(offset), category: h.category, ...property ? { property } : {}, value: h.text, source, ...suggestion ? { suggestion } : {} });
   };
   const addTailwind = (hits, offset) => {
-    for (const h of hits) {
-      if (h.kind === "scale") {
-        out.themeRefs++;
-        continue;
-      }
-      if (h.kind === "token") continue;
-      let cat = h.category;
-      const v = h.value;
-      const isColor = Boolean(parseCssColor(v));
-      if (cat === "color-or-size") cat = isColor ? "color" : "font-size";
-      else if (cat === "color-or-width") cat = isColor ? "color" : "border-width";
-      else if (cat === "color-or-shadow") cat = isColor ? "color" : "shadow";
-      else if (cat === "font") cat = /^\d{3}$/.test(v) ? "font-weight" : "font-family";
-      if (cat === "color" && !isColor) continue;
-      const suggestion = ds.suggest(cat, v);
-      const cap = h.kind === "palette" && suggestion && suggestion.confidence > 0.6 ? { ...suggestion, confidence: 0.6, level: "medium" } : suggestion;
-      out.findings.push({ ...pos(offset + h.index), category: cat, value: h.cls, source: "tailwind", ...cap ? { suggestion: cap } : {} });
-    }
+    const r = tailwindFindings(hits, offset, pos, ds);
+    out.themeRefs += r.themeRefs;
+    out.findings.push(...r.findings);
   };
   const styleValue = (key, node, ctx) => {
     const source = ctx === "sx" ? "sx" : ctx === "style" ? "style" : ctx === "theme" ? "theme" : "styled";
@@ -1258,13 +1340,18 @@ function scanCode(path, text, ds) {
     }
     for (const a of scan.applies) addTailwind(a.hits, start + a.start);
   };
+  const lookalike = (list2, offset) => {
+    for (const l of lookalikesInClassList(list2, ds.components)) out.components.push({ ...pos(offset), name: `.${l.token}`, kind: "recreated", library: "local", suggestion: l.component });
+  };
   const classLiteral = (node) => {
     if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
       handled.add(node);
+      lookalike(node.text, node.getStart(sf) + 1);
       addTailwind(scanClassString(node.text), node.getStart(sf) + 1);
     } else if (ts.isTemplateExpression(node)) {
       for (const p of [node.head, ...node.templateSpans.map((s) => s.literal)]) {
         handled.add(p);
+        lookalike(p.text, p.getStart(sf) + 1);
         addTailwind(scanClassString(p.text), p.getStart(sf) + 1);
       }
       node.templateSpans.forEach((s) => visit(s.expression, null, true));
@@ -1273,49 +1360,13 @@ function scanCode(path, text, ds) {
   const jsxName = (n) => n.getText(sf);
   const element = (node) => {
     const name = jsxName(node.tagName);
-    const at = pos(node.getStart(sf));
-    if (/^[a-z][\w-]*$/.test(name)) {
-      if (!ds.nativeElements.includes(name)) return;
-      const typeAttr = node.attributes.properties.find((p) => ts.isJsxAttribute(p) && p.name.getText(sf) === "type");
-      const type = typeAttr?.initializer && ts.isStringLiteral(typeAttr.initializer) ? typeAttr.initializer.text : void 0;
-      if (name === "input" && type === "hidden") return;
-      if (name === "a" && !node.attributes.properties.some((p) => ts.isJsxAttribute(p) && p.name.getText(sf) === "href")) return;
-      if (isRenderElement(node)) return;
-      const suggestion = nativeEquivalent(name, type, ds.components);
-      out.components.push({ ...at, name, kind: "native", library: "native", ...suggestion ? { suggestion } : {} });
-      return;
-    }
-    const root = name.split(".")[0];
-    const imp = imports.get(root);
-    const ns = imp?.imported === "*";
-    const shown = imp && !ns && imp.imported !== "default" ? [imp.imported, ...name.split(".").slice(1)].join(".") : name;
-    const leaf = ns && name.includes(".") ? name.split(".").slice(1).join(".") : shown;
-    if (imp) {
-      const kind = classifyModule(imp.module, ds.packages, ds.foreignLibraries);
-      if (isNonVisual(leaf.split(".").pop())) return;
-      if (kind === "ds") {
-        out.ds[leaf] = (out.ds[leaf] ?? 0) + 1;
-        return;
-      }
-      if (kind === "charts") {
-        out.components.push({ ...at, name: shown, kind: "foreign", library: libraryLabel(imp.module, kind) });
-        return;
-      }
-      if (kind === "other" && isRouterLink(imp.module, imp.imported === "default" ? "default" : leaf)) {
-        if (isRenderElement(node)) return;
-        const suggestion = ds.components.has("Link") ? "Link" : void 0;
-        out.components.push({ ...at, name: shown, kind: "foreign", library: libraryLabel(imp.module, kind), ...suggestion ? { suggestion } : {} });
-        return;
-      }
-      if (kind === "foreign" || kind === "shadcn") {
-        const suggestion = (ns ? dsEquivalent(root, ds.components) : void 0) ?? dsEquivalent(leaf, ds.components);
-        out.components.push({ ...at, name: shown, kind: "foreign", library: libraryLabel(imp.module, kind), ...suggestion ? { suggestion } : {} });
-        return;
-      }
-      if (kind === "local" && ds.components.has(leaf.split(".")[0])) out.components.push({ ...at, name: leaf, kind: "recreated", library: "local", suggestion: leaf.split(".")[0] });
-      return;
-    }
-    if (ds.components.has(root)) pendingLocal.push({ ...at, name, kind: "recreated", library: "local", suggestion: root });
+    const typeAttr = node.attributes.properties.find((p) => ts.isJsxAttribute(p) && p.name.getText(sf) === "type");
+    const type = typeAttr?.initializer && ts.isStringLiteral(typeAttr.initializer) ? typeAttr.initializer.text : void 0;
+    const hasHref = node.attributes.properties.some((p) => ts.isJsxAttribute(p) && p.name.getText(sf) === "href");
+    const r = classifyTag({ name, ...pos(node.getStart(sf)), ...type !== void 0 ? { type } : {}, hasHref, inRenderProp: isRenderElement(node) }, imports, ds);
+    if (r.ds) out.ds[r.ds] = (out.ds[r.ds] ?? 0) + 1;
+    if (r.component) out.components.push(r.component);
+    if (r.localCandidate) pendingLocal.push(r.localCandidate);
   };
   const pendingLocal = [];
   function visit(node, ctx, classCtx) {
@@ -1375,6 +1426,17 @@ function scanCode(path, text, ds) {
       cssTemplate(node.template);
       return;
     }
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+      const imp = imports.get(node.expression.text);
+      if (imp && imp.imported !== "*" && classifyModule(imp.module, ds.packages, ds.foreignLibraries) === "ds") {
+        const comp = domRendererComponent(imp.imported === "default" ? node.expression.text : imp.imported, ds.components);
+        if (comp) out.ds[comp] = (out.ds[comp] ?? 0) + 1;
+      }
+    }
+    if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken && ts.isPropertyAccessExpression(node.left) && node.left.name.text === "className") {
+      visit(node.left, ctx, classCtx);
+      return classLiteral(node.right);
+    }
     if (ts.isCallExpression(node)) {
       const callee = node.expression.getText(sf);
       if (CLASS_FNS.test(callee)) {
@@ -1419,6 +1481,14 @@ function scanCode(path, text, ds) {
   const literal = (node) => {
     if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node) || ts.isTemplateHead(node) || ts.isTemplateMiddle(node) || ts.isTemplateTail(node)) {
       const t = node.text;
+      if (!handled.has(node) && (t.includes("<") || ts.isTemplateMiddle(node) || ts.isTemplateTail(node))) {
+        const base = node.getStart(sf) + 1;
+        for (const m of t.matchAll(HTML_CLASS_RE)) for (const l of lookalikesInClassList(m[1], ds.components)) out.components.push({ ...pos(base + m.index), name: `.${l.token}`, kind: "recreated", library: "local", suggestion: l.component });
+        for (const m of t.matchAll(HTML_ATTR_RE)) {
+          const component = LOOKALIKE_ATTRS[m[1]];
+          if (component && ds.components.has(component)) out.components.push({ ...pos(base + m.index + 1), name: `[${m[1]}]`, kind: "recreated", library: "local", suggestion: component });
+        }
+      }
       for (const m of t.matchAll(/var\(\s*(--[\w-]+)/g)) {
         if (ds.isDsVar(m[1])) out.tokenUsages++;
         else out.themeRefs++;
@@ -1438,25 +1508,85 @@ function scanCode(path, text, ds) {
   return out;
 }
 
-// ../core/src/audit/report.ts
-var AUDIT_EXTENSIONS = [".css", ".scss", ".sass", ".less", ".tsx", ".jsx", ".ts", ".js", ".mjs", ".cjs", ".mts", ".cts"];
-var AUDIT_IGNORE_DIRS = ["node_modules", "dist", "build", "out", "coverage", ".git", ".next", ".nuxt", ".astro", ".turbo", ".cache", ".vercel", "storybook-static", "vendor", "public"];
-var IGNORE_FILE = /\.d\.[cm]?ts$|\.(test|spec|stories|story)\.[cm]?[jt]sx?$|\.min\.(css|js)$|(^|\/)(vite|vitest|jest|webpack|rollup|eslint|postcss|tailwind|babel|next|astro|prettier|stylelint|tsup)\.config\.[cm]?[jt]s$/;
-function isAuditable(path) {
-  if (!AUDIT_EXTENSIONS.some((e) => path.endsWith(e))) return false;
-  if (IGNORE_FILE.test(path)) return false;
-  return !path.split("/").some((seg) => AUDIT_IGNORE_DIRS.includes(seg));
+// ../core/src/audit/ignore.ts
+var IGNORE_DIRECTIVE = "bridge-audit-ignore-next-line";
+function ignoreDirectives(text) {
+  const at = lineCol(text);
+  const out = [];
+  for (const m of text.matchAll(new RegExp(`${IGNORE_DIRECTIVE}\\b`, "g"))) {
+    const start = m.index;
+    const opener = /(<!--|\/\*|\/\/)(\s*)$/.exec(text.slice(Math.max(0, start - 200), start));
+    const open = opener?.[1];
+    if (!open || open === "//" && opener[2].includes("\n")) continue;
+    const from = start + m[0].length;
+    let end;
+    if (open === "//") {
+      end = text.indexOf("\n", from);
+      if (end < 0) end = text.length;
+    } else {
+      end = text.indexOf(open === "<!--" ? "-->" : "*/", from);
+      if (end < 0) continue;
+    }
+    const reason = text.slice(from, end).replace(/^\s*:?/, "").replace(/\s+/g, " ").trim();
+    out.push({ line: at(start).line, target: at(end).line + 1, reason });
+  }
+  return out;
 }
-var langOf = (path) => {
-  const ext = path.slice(path.lastIndexOf(".") + 1);
-  if (ext === "css") return "css";
-  if (ext === "scss" || ext === "sass") return "scss";
-  if (ext === "less") return "less";
-  if (ext === "tsx") return "tsx";
-  if (ext === "jsx") return "jsx";
-  if (/^[cm]?ts$/.test(ext)) return "ts";
-  return "js";
-};
+var item = (x, reason, via) => "category" in x ? { line: x.line, column: x.column, kind: "value", what: x.value, reason, via } : { line: x.line, column: x.column, kind: "component", what: x.name, reason, via };
+function applyIgnoreComments(text, findings, components) {
+  const errors = [];
+  const reasons = /* @__PURE__ */ new Map();
+  for (const d of ignoreDirectives(text)) {
+    if (!d.reason) {
+      errors.push({ line: d.line, message: `${IGNORE_DIRECTIVE} needs a reason after a colon (${IGNORE_DIRECTIVE}: why this one stays); nothing was ignored` });
+      continue;
+    }
+    if (!findings.some((f) => f.line === d.target) && !components.some((c) => c.line === d.target)) {
+      errors.push({ line: d.line, message: `${IGNORE_DIRECTIVE} ignores nothing: line ${d.target} has no finding; remove the comment` });
+      continue;
+    }
+    reasons.set(d.target, d.reason);
+  }
+  const ignored = [];
+  const keep = (xs) => xs.filter((x) => {
+    const r = reasons.get(x.line);
+    if (r === void 0) return true;
+    ignored.push(item(x, r, "comment"));
+    return false;
+  });
+  return { findings: keep(findings), components: keep(components), ignored, errors };
+}
+function applyAllowlist(entries, findings, components) {
+  const used = /* @__PURE__ */ new Set();
+  const ignored = [];
+  const keep = (xs) => xs.filter((x) => {
+    const what = "category" in x ? x.value : x.name;
+    const fits = (e) => e.line === x.line && (e.what === void 0 || e.what === what);
+    let i = entries.findIndex((e, k) => fits(e) && !used.has(k));
+    if (i < 0) i = entries.findIndex(fits);
+    if (i < 0) return true;
+    used.add(i);
+    ignored.push(item(x, entries[i].reason, "allowlist"));
+    return false;
+  });
+  return { findings: keep(findings), components: keep(components), ignored, used };
+}
+function parseAllowlist(json) {
+  const fail = (msg) => {
+    throw new Error(`allowlist: ${msg}`);
+  };
+  if (!json || typeof json !== "object" || !Array.isArray(json.entries)) fail('expected { "entries": [...] }');
+  return json.entries.map((e, i) => {
+    const x = e;
+    if (typeof x.file !== "string" || !x.file) fail(`entry ${i} needs "file"`);
+    if (typeof x.line !== "number" || !Number.isInteger(x.line) || x.line < 1) fail(`entry ${i} (${x.file}) needs a "line" number`);
+    if (typeof x.reason !== "string" || !x.reason.trim()) fail(`entry ${i} (${x.file}:${x.line}) needs a "reason"`);
+    if (x.what !== void 0 && typeof x.what !== "string") fail(`entry ${i} (${x.file}:${x.line}): "what" must be a string`);
+    return { file: x.file, line: x.line, ...x.what !== void 0 ? { what: x.what } : {}, reason: x.reason.trim() };
+  });
+}
+
+// ../core/src/audit/style.ts
 function isSafeFix(h, s) {
   if (!s || s.level !== "exact") return false;
   switch (h.category) {
@@ -1481,49 +1611,342 @@ function isSafeFix(h, s) {
       return false;
   }
 }
-function auditFile(path, text, ds) {
-  const lang = langOf(path);
-  if (lang === "css" || lang === "scss" || lang === "less") {
-    const at = lineCol(text);
-    const scan = scanCssText(text, lang);
-    const findings = [];
-    let tokenUsages = 0;
-    let themeRefs = 0;
-    for (const d of scan.decls) {
-      for (const v of d.scan.vars) ds.isDsVar(v) ? tokenUsages++ : themeRefs++;
-      if (d.scan.themeRef) themeRefs++;
-      else if (lang !== "css" && !d.property.startsWith("$")) themeRefs += (d.value.match(/\$[\w-]+/g) ?? []).length;
-      const property = d.property.toLowerCase();
-      for (const h of d.scan.hits) {
-        const suggestion = ds.suggest(h.category, h.text, property);
-        const p = at(d.valueStart + h.index);
-        findings.push({ ...p, category: h.category, property, value: h.text, source: "css", ...suggestion ? { suggestion } : {}, ...isSafeFix(h, suggestion) ? { autofix: true } : {} });
+function auditCssText(text, lang, ds, opts) {
+  const base = opts.offset ?? 0;
+  const source = opts.source ?? "css";
+  const at = (o) => opts.pos(base + o);
+  const scan = scanCssText(text, lang);
+  const findings = [];
+  let tokenUsages = 0;
+  let themeRefs = 0;
+  for (const d of scan.decls) {
+    for (const v of d.scan.vars) ds.isDsVar(v) ? tokenUsages++ : themeRefs++;
+    if (d.scan.themeRef) themeRefs++;
+    else if (lang !== "css" && !d.property.startsWith("$")) themeRefs += (d.value.match(/\$[\w-]+/g) ?? []).length;
+    const property = d.property.toLowerCase();
+    for (const h of d.scan.hits) {
+      const suggestion = ds.suggest(h.category, h.text, property);
+      const autofix = source === "css" && isSafeFix(h, suggestion);
+      findings.push({ ...at(d.valueStart + h.index), category: h.category, property, value: h.text, source, ...suggestion ? { suggestion } : {}, ...autofix ? { autofix: true } : {} });
+    }
+  }
+  for (const a of scan.applies) {
+    for (const h of a.hits) {
+      if (h.kind === "scale") themeRefs++;
+      else if (h.kind !== "token" && h.value) {
+        const cat = parseCssColor(h.value) ? "color" : h.category === "color-or-size" ? "font-size" : h.category === "color-or-width" ? "border-width" : h.category === "color-or-shadow" ? "shadow" : h.category === "font" ? "font-family" : h.category;
+        const suggestion = ds.suggest(cat, h.value);
+        findings.push({ ...at(a.start + h.index), category: cat, value: h.cls, source: "tailwind", ...suggestion ? { suggestion } : {} });
+      } else if (h.kind === "token" && h.value) {
+        const v = /var\(\s*(--[\w-]+)/.exec(h.value)?.[1];
+        if (v && ds.isDsVar(v)) tokenUsages++;
+        else themeRefs++;
       }
     }
-    for (const a of scan.applies) {
-      for (const h of a.hits) {
-        if (h.kind === "scale") themeRefs++;
-        else if (h.kind !== "token" && h.value) {
-          const cat = parseCssColor(h.value) ? "color" : h.category === "color-or-size" ? "font-size" : h.category === "color-or-width" ? "border-width" : h.category === "color-or-shadow" ? "shadow" : h.category === "font" ? "font-family" : h.category;
-          const suggestion = ds.suggest(cat, h.value);
-          findings.push({ ...at(a.start + h.index), category: cat, value: h.cls, source: "tailwind", ...suggestion ? { suggestion } : {} });
-        } else if (h.kind === "token" && h.value) {
-          const v = /var\(\s*(--[\w-]+)/.exec(h.value)?.[1];
-          if (v && ds.isDsVar(v)) tokenUsages++;
-          else themeRefs++;
-        }
+  }
+  findings.sort((x, y) => x.line - y.line || x.column - y.column);
+  return { findings, tokenUsages, themeRefs };
+}
+
+// ../core/src/audit/markup.ts
+var MARKUP_EXTENSIONS = [".astro", ".vue", ".svelte"];
+function mask2(text, ranges, keepInside) {
+  const inside = new Uint8Array(text.length);
+  for (const r of ranges) inside.fill(1, r.start, r.end);
+  let out = "";
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    out += c === "\n" || Boolean(inside[i]) === keepInside ? c : " ";
+  }
+  return out;
+}
+var attrOf = (attrs, name) => new RegExp(`(?:^|\\s)${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, "i").exec(attrs)?.slice(1).find((v) => v !== void 0);
+var isCodeScript = (attrs) => {
+  const type = attrOf(attrs, "type")?.toLowerCase();
+  return !type || ["module", "text/javascript", "application/javascript", "text/typescript", "ts", "text/babel"].includes(type);
+};
+function markupBlocks(text, lang) {
+  const nonTemplate = [];
+  let frontmatter;
+  let from = 0;
+  if (lang === "astro") {
+    const open = /^\s*---[^\S\n]*\n/.exec(text);
+    if (open) {
+      const close = /\n---[^\S\n]*(\n|$)/g;
+      close.lastIndex = open[0].length - 1;
+      const m = close.exec(text);
+      if (m) {
+        frontmatter = { start: open[0].length, end: m.index + 1 };
+        from = m.index + m[0].length;
+        nonTemplate.push({ start: 0, end: from });
+      }
+    }
+  }
+  const scripts = [];
+  const styles = [];
+  const re = /<(script|style)\b((?:[^>"']|"[^"]*"|'[^']*')*)>([\s\S]*?)<\/\1\s*>/gi;
+  re.lastIndex = from;
+  for (let m; m = re.exec(text); ) {
+    const contentStart = m.index + m[0].indexOf(">", m[1].length + 1 + m[2].length) + 1;
+    const block = { start: contentStart, end: contentStart + m[3].length, attrs: m[2] };
+    (m[1].toLowerCase() === "script" ? scripts : styles).push(block);
+    nonTemplate.push({ start: m.index, end: m.index + m[0].length });
+  }
+  for (const m of text.slice(from).matchAll(/<!--[\s\S]*?-->/g)) nonTemplate.push({ start: from + m.index, end: from + m.index + m[0].length });
+  return { ...frontmatter ? { frontmatter } : {}, scripts, styles, nonTemplate };
+}
+function closeBrace(s, i) {
+  let depth = 0;
+  for (let k = i; k < s.length; k++) {
+    const c = s[k];
+    if (c === "{") depth++;
+    else if (c === "}") {
+      if (--depth === 0) return k + 1;
+    } else if (c === '"' || c === "'") {
+      const e = s.indexOf(c, k + 1);
+      if (e < 0) return s.length;
+      k = e;
+    } else if (c === "`") {
+      for (k++; k < s.length && s[k] !== "`"; k++) {
+        if (s[k] === "\\") k++;
+        else if (s[k] === "$" && s[k + 1] === "{") k = closeBrace(s, k + 1) - 1;
+      }
+    }
+  }
+  return s.length;
+}
+function readTag(s, i, lang) {
+  const attrs = [];
+  let k = i;
+  while (k < s.length) {
+    while (k < s.length && /\s/.test(s[k])) k++;
+    const c = s[k];
+    if (c === void 0) break;
+    if (c === ">") return { attrs, end: k + 1, selfClosing: false };
+    if (c === "/" && s[k + 1] === ">") return { attrs, end: k + 2, selfClosing: true };
+    if (c === "{") {
+      const e = closeBrace(s, k);
+      const inner = s.slice(k + 1, e - 1).trim();
+      attrs.push(inner.startsWith("...") ? { name: "", kind: "spread", value: inner, valueStart: k + 1 } : { name: inner, kind: "expr", value: inner, valueStart: k + 1 });
+      k = e;
+      continue;
+    }
+    const nm = /^[^\s=>/"'{]+/.exec(s.slice(k, k + 200));
+    if (!nm) {
+      k++;
+      continue;
+    }
+    const name = nm[0];
+    k += name.length;
+    let j = k;
+    while (j < s.length && /\s/.test(s[j])) j++;
+    if (s[j] !== "=") {
+      attrs.push({ name, kind: "bare", value: "", valueStart: k });
+      continue;
+    }
+    j++;
+    while (j < s.length && /\s/.test(s[j])) j++;
+    const q = s[j];
+    const bound = lang === "vue" && /^(:|v-bind:|v-on:|@|v-)/.test(name);
+    if (q === '"' || q === "'") {
+      const e = s.indexOf(q, j + 1);
+      const end = e < 0 ? s.length : e;
+      attrs.push({ name, kind: bound ? "expr" : "static", value: s.slice(j + 1, end), valueStart: j + 1 });
+      k = end + 1;
+    } else if (q === "{") {
+      const e = closeBrace(s, j);
+      attrs.push({ name, kind: "expr", value: s.slice(j + 1, e - 1), valueStart: j + 1 });
+      k = e;
+    } else {
+      const m = /^[^\s>]+/.exec(s.slice(j));
+      const v = m?.[0].replace(/\/$/, "") ?? "";
+      attrs.push({ name, kind: "static", value: v, valueStart: j });
+      k = j + v.length;
+    }
+  }
+  return { attrs, end: s.length, selfClosing: false };
+}
+var attrName = (n) => n.replace(/^(v-bind:|:|bind:)/, "");
+var pascal = (kebab) => kebab.replace(/(^|-)([a-z0-9])/g, (_m, _d, c) => c.toUpperCase());
+var NO_COLOR_ATTR_TAGS = /* @__PURE__ */ new Set(["meta", "link"]);
+function scanMarkup(path, text, lang, ds) {
+  const out = { findings: [], tokenUsages: 0, themeRefs: 0, ds: {}, components: [], definitions: [] };
+  const pos = lineCol(text);
+  const blocks = markupBlocks(text, lang);
+  const imports = /* @__PURE__ */ new Map();
+  const merge = (c) => {
+    out.findings.push(...c.findings);
+    out.tokenUsages += c.tokenUsages;
+    out.themeRefs += c.themeRefs;
+    for (const [n, k] of Object.entries(c.ds)) out.ds[n] = (out.ds[n] ?? 0) + k;
+    out.components.push(...c.components);
+    out.definitions.push(...c.definitions);
+  };
+  const codeRanges = [...blocks.frontmatter ? [{ ...blocks.frontmatter, attrs: "" }] : [], ...blocks.scripts.filter((b) => isCodeScript(b.attrs))];
+  for (const r of codeRanges) {
+    const jsx = /^(tsx|jsx)$/i.test(attrOf(r.attrs, "lang") ?? "");
+    const code = mask2(text, [r], true);
+    const file = `${path}.${jsx ? "tsx" : "ts"}`;
+    merge(scanCode(file, code, ds));
+    for (const [k, v] of importsOf(file, code)) imports.set(k, v);
+  }
+  for (const b of blocks.styles) {
+    const l = (attrOf(b.attrs, "lang") ?? "css").toLowerCase();
+    const r = auditCssText(text.slice(b.start, b.end), l === "scss" || l === "sass" ? "scss" : l === "less" ? "less" : "css", ds, { pos, offset: b.start });
+    out.findings.push(...r.findings);
+    out.tokenUsages += r.tokenUsages;
+    out.themeRefs += r.themeRefs;
+  }
+  const scanExpr = (prefix, expr, offset, suffix, keepLookalikes = false) => {
+    const { line, column } = pos(offset);
+    const src = line >= 2 ? `${"\n".repeat(line - 2)}${prefix}
+${" ".repeat(column - 1)}${expr}${suffix}` : `${prefix}${expr}${suffix}`;
+    const c = scanCode(`${path}.tsx`, src, ds);
+    merge({ ...c, components: keepLookalikes ? c.components.filter((x) => x.kind === "recreated" && x.name.startsWith(".")) : [], definitions: [], ds: {} });
+  };
+  const styleAttr = (a) => {
+    if (a.kind === "static") {
+      const css = lang === "svelte" ? a.value.replace(/\{[^}]*\}/g, (m) => " ".repeat(m.length)) : a.value;
+      const r = auditCssText(css, "css", ds, { pos, offset: a.valueStart, source: "style" });
+      out.findings.push(...r.findings);
+      out.tokenUsages += r.tokenUsages;
+      out.themeRefs += r.themeRefs;
+      return;
+    }
+    const str = /^(\s*)([`'"])([\s\S]*)\2\s*$/.exec(a.value);
+    if (str) {
+      const body = str[3].replace(/\$\{[^}]*\}/g, (m) => " ".repeat(m.length));
+      const r = auditCssText(body, "css", ds, { pos, offset: a.valueStart + str[1].length + 1, source: "style" });
+      out.findings.push(...r.findings);
+      out.tokenUsages += r.tokenUsages;
+      out.themeRefs += r.themeRefs;
+      return;
+    }
+    scanExpr("const style: CSSProperties =", a.value, a.valueStart, ";");
+  };
+  const tpl = mask2(text, blocks.nonTemplate, false);
+  const pending = [];
+  let noscript = 0;
+  const TAG = /<(\/?)([A-Za-z][\w.:-]*)/g;
+  for (let m; m = TAG.exec(tpl); ) {
+    const raw = m[2];
+    if (m[1]) {
+      if (raw.toLowerCase() === "noscript") noscript = Math.max(0, noscript - 1);
+      continue;
+    }
+    const tag = readTag(tpl, m.index + m[0].length, lang);
+    TAG.lastIndex = tag.end;
+    const lower = raw.toLowerCase();
+    if (lower === "noscript" && !tag.selfClosing) {
+      noscript++;
+      continue;
+    }
+    const attrs = tag.attrs;
+    const get = (n) => attrs.find((a) => attrName(a.name) === n);
+    for (const a of attrs) {
+      const n = attrName(a.name);
+      if (n === "style") styleAttr(a);
+      else if (lang === "svelte" && a.name.startsWith("style:") && a.kind === "static") {
+        const prop = a.name.slice(6).split("|")[0];
+        const r2 = auditCssText(`${prop}:${a.value}`, "css", ds, { pos, offset: a.valueStart - prop.length - 1, source: "style" });
+        out.findings.push(...r2.findings);
+        out.tokenUsages += r2.tokenUsages;
+        out.themeRefs += r2.themeRefs;
+      } else if (/^(class|className|class:list)$/.test(n)) {
+        if (a.kind === "static") {
+          for (const l of lookalikesInClassList(a.value, ds.components)) out.components.push({ ...pos(a.valueStart), name: `.${l.token}`, kind: "recreated", library: "local", suggestion: l.component });
+          const r2 = tailwindFindings(scanClassString(a.value), a.valueStart, pos, ds);
+          out.findings.push(...r2.findings);
+          out.themeRefs += r2.themeRefs;
+        } else if (a.kind === "expr") scanExpr("cn(", a.value, a.valueStart, ")", true);
+      } else if (LOOKALIKE_ATTRS[n] && ds.components.has(LOOKALIKE_ATTRS[n])) {
+        out.components.push({ ...pos(a.valueStart - a.name.length - 1), name: `[${n}]`, kind: "recreated", library: "local", suggestion: LOOKALIKE_ATTRS[n] });
+      } else if (a.kind === "static" && !NO_COLOR_ATTR_TAGS.has(lower) && isColorLiteral(a.value)) {
+        const suggestion = ds.suggest("color", a.value.trim(), n);
+        out.findings.push({ ...pos(a.valueStart), category: "color", property: n, value: a.value.trim(), source: "jsx-attr", ...suggestion ? { suggestion } : {} });
       }
     }
-    findings.sort((x, y) => x.line - y.line || x.column - y.column);
-    return { path, lang, tokenUsages, themeRefs, hardcoded: findings.length, dsComponents: 0, otherComponents: 0, findings, components: [], definitions: [], dsByName: {} };
+    let name = raw;
+    if (raw.includes(":")) continue;
+    if (raw.includes("-")) {
+      if (!imports.has(pascal(raw))) continue;
+      name = pascal(raw);
+    }
+    const isNative = /^[a-z]/.test(name) && !name.includes(".");
+    if (isNative && noscript > 0) continue;
+    const type = get("type");
+    const r = classifyTag({ name, ...pos(m.index), ...type?.kind === "static" ? { type: type.value } : {}, hasHref: Boolean(get("href")) }, imports, ds);
+    if (r.ds) out.ds[r.ds] = (out.ds[r.ds] ?? 0) + 1;
+    if (r.component) out.components.push(r.component);
+    if (r.localCandidate) pending.push(r.localCandidate);
+  }
+  const base = /([^/]+)\.(astro|vue|svelte)$/.exec(path)?.[1];
+  if (base && /^[A-Z][A-Za-z0-9]*$/.test(base)) out.definitions.push({ name: base, line: 1 });
+  const defined = new Set(out.definitions.map((d) => d.name));
+  out.components.push(...pending.filter((f) => defined.has(f.suggestion)));
+  out.findings.sort((a, b) => a.line - b.line || a.column - b.column);
+  out.components.sort((a, b) => a.line - b.line || a.column - b.column);
+  return out;
+}
+
+// ../core/src/audit/report.ts
+var AUDIT_EXTENSIONS = [".css", ".scss", ".sass", ".less", ".tsx", ".jsx", ".ts", ".js", ".mjs", ".cjs", ".mts", ".cts", ...MARKUP_EXTENSIONS];
+var AUDIT_IGNORE_DIRS = ["node_modules", "dist", "build", "out", "coverage", ".git", ".next", ".nuxt", ".astro", ".turbo", ".cache", ".vercel", "storybook-static", "vendor", "public"];
+var IGNORE_FILE = /\.d\.[cm]?ts$|\.(test|spec|stories|story)\.[cm]?[jt]sx?$|\.min\.(css|js)$|(^|\/)(vite|vitest|jest|webpack|rollup|eslint|postcss|tailwind|babel|next|astro|prettier|stylelint|tsup)\.config\.[cm]?[jt]s$/;
+function isAuditable(path) {
+  if (!AUDIT_EXTENSIONS.some((e) => path.endsWith(e))) return false;
+  if (IGNORE_FILE.test(path)) return false;
+  return !path.split("/").some((seg) => AUDIT_IGNORE_DIRS.includes(seg));
+}
+var langOf = (path) => {
+  const ext = path.slice(path.lastIndexOf(".") + 1);
+  if (ext === "css") return "css";
+  if (ext === "scss" || ext === "sass") return "scss";
+  if (ext === "less") return "less";
+  if (ext === "tsx") return "tsx";
+  if (ext === "jsx") return "jsx";
+  if (/^[cm]?ts$/.test(ext)) return "ts";
+  if (ext === "astro" || ext === "vue" || ext === "svelte") return ext;
+  return "js";
+};
+function auditFile(path, text, ds) {
+  const lang = langOf(path);
+  if (lang === "css" || lang === "scss" || lang === "less") {
+    const r = auditCssText(text, lang, ds, { pos: lineCol(text) });
+    return withIgnores(text, { path, lang, tokenUsages: r.tokenUsages, themeRefs: r.themeRefs, hardcoded: 0, dsComponents: 0, otherComponents: 0, findings: r.findings, components: [], definitions: [], dsByName: {} });
   }
-  const c = scanCode(path, text, ds);
+  const c = lang === "astro" || lang === "vue" || lang === "svelte" ? scanMarkup(path, text, lang, ds) : scanCode(path, text, ds);
   const dsCount = Object.values(c.ds).reduce((a, b) => a + b, 0);
-  return { path, lang, tokenUsages: c.tokenUsages, themeRefs: c.themeRefs, hardcoded: c.findings.length, dsComponents: dsCount, otherComponents: c.components.length, findings: c.findings, components: c.components, definitions: c.definitions, dsByName: c.ds };
+  return withIgnores(text, { path, lang, tokenUsages: c.tokenUsages, themeRefs: c.themeRefs, hardcoded: 0, dsComponents: dsCount, otherComponents: 0, findings: c.findings, components: c.components, definitions: c.definitions, dsByName: c.ds });
+}
+function withIgnores(text, f) {
+  const r = applyIgnoreComments(text, f.findings, f.components);
+  return {
+    ...f,
+    findings: r.findings,
+    components: r.components,
+    hardcoded: r.findings.length,
+    otherComponents: r.components.length,
+    ...r.ignored.length ? { ignored: r.ignored } : {},
+    ...r.errors.length ? { ignoreErrors: r.errors } : {}
+  };
 }
 var pct = (num2, den) => den > 0 ? Math.round(num2 / den * 1e3) / 10 : null;
 function buildAuditReport(input, ds) {
-  const reports = input.files.map((f) => auditFile(f.path, f.text, ds));
+  const allow = input.allowlist ?? [];
+  const usedAllow = /* @__PURE__ */ new Set();
+  const reports = input.files.map((f) => {
+    const r = auditFile(f.path, f.text, ds);
+    const idx = allow.flatMap((e, i) => e.file === f.path ? [i] : []);
+    if (!idx.length) return r;
+    const a = applyAllowlist(idx.map((i) => allow[i]), r.findings, r.components);
+    a.used.forEach((k) => usedAllow.add(idx[k]));
+    if (!a.ignored.length) return r;
+    const ignored = [...r.ignored ?? [], ...a.ignored].sort((x, y) => x.line - y.line || x.column - y.column);
+    return { ...r, findings: a.findings, components: a.components, hardcoded: a.findings.length, otherComponents: a.components.length, ignored };
+  });
+  const ignoredItems = reports.flatMap((r) => (r.ignored ?? []).map((x) => ({ file: r.path, ...x })));
+  const staleAllowlist = allow.filter((_e, i) => !usedAllow.has(i));
   const files = reports.map(({ definitions: _d, dsByName: _n, ...r }) => r);
   const byCategory = {};
   const fixes = /* @__PURE__ */ new Map();
@@ -1583,6 +2006,15 @@ function buildAuditReport(input, ds) {
     topFiles,
     topFixes,
     files: files.sort((a, b) => a.path.localeCompare(b.path)),
+    ...ignoredItems.length || staleAllowlist.length ? {
+      ignored: {
+        total: ignoredItems.length,
+        comment: ignoredItems.filter((x) => x.via === "comment").length,
+        allowlist: ignoredItems.filter((x) => x.via === "allowlist").length,
+        items: ignoredItems,
+        staleAllowlist
+      }
+    } : {},
     history: []
   };
 }
@@ -1686,6 +2118,20 @@ function auditMarkdown(r, opts = {}) {
     for (const f of fixes) lines.push(`| \`${esc(f.value)}\` (${f.category}) | \`var(${f.suggestion.cssVar})\` ${esc(f.suggestion.value)}${f.suggestion.mode ? ` [${f.suggestion.mode}]` : ""} | ${f.suggestion.level} | ${f.count} |`);
     lines.push("");
   }
+  const ig = r.ignored;
+  if (ig && (ig.total || ig.staleAllowlist.length)) {
+    lines.push("### Ignored on purpose", "", `${ig.total} item(s) left out of the counts: ${ig.comment} by \`bridge-audit-ignore-next-line\` comments, ${ig.allowlist} by the allowlist.`, "");
+    const shown = ig.items.slice(0, opts.ignored ?? 50);
+    if (shown.length) {
+      lines.push("| Where | What | Reason |", "| --- | --- | --- |");
+      for (const x of shown) lines.push(`| \`${esc(x.file)}:${x.line}\` | \`${esc(x.what)}\` | ${esc(x.reason)} (${x.via}) |`);
+      if (ig.items.length > shown.length) lines.push(`| ... | ${ig.items.length - shown.length} more | |`);
+      lines.push("");
+    }
+    if (ig.staleAllowlist.length) {
+      lines.push(`Allowlist entries that match nothing any more (remove them): ${ig.staleAllowlist.map((e) => `\`${esc(e.file)}:${e.line}${e.what ? ` ${esc(e.what)}` : ""}\``).join(", ")}.`, "");
+    }
+  }
   if (b) {
     lines.push(`### Progress since ${b.label ?? b.generatedAt}`, "");
     lines.push(`- ${b.improved.length} files improved, ${b.regressed.length} regressed, ${b.newFiles.length} new, ${b.removedFiles.length} removed.`);
@@ -2425,13 +2871,16 @@ function collectAuditFiles(target, exclude = []) {
   }
   return { root: abs, files, skipped };
 }
+function loadAllowlist(path) {
+  return parseAllowlist(JSON.parse(readFileSync(path, "utf8")));
+}
 function runAudit(target, opts = {}) {
   const dsRoot = opts.ds ?? findDesignSystemRoot(process.cwd());
   if (!dsRoot) throw new Error("No design system found: run from a repo with bridge.config.json or pass --ds <dir>.");
   const ds = loadDesignSystem(dsRoot);
   const { files, skipped } = collectAuditFiles(target, [...ds.config.audit?.exclude ?? [], ...opts.exclude ?? []]);
   const report = buildAuditReport(
-    { files, skipped, target: opts.displayPath ?? (toPosix(relative(process.cwd(), resolve(target))) || "."), ...opts.label ? { label: opts.label } : {}, ...opts.version ? { version: opts.version } : {} },
+    { files, skipped, target: opts.displayPath ?? (toPosix(relative(process.cwd(), resolve(target))) || "."), ...opts.label ? { label: opts.label } : {}, ...opts.version ? { version: opts.version } : {}, ...opts.allowlist ? { allowlist: opts.allowlist } : {} },
     ds.index
   );
   return opts.baseline ? compareWithBaseline(report, opts.baseline) : report;
@@ -2450,6 +2899,22 @@ function fixCss(target, ds, write) {
   return out;
 }
 
+// ../core/src/component-spec.ts
+var COMPONENT_SPECS_VERSION = 1;
+var variantKeyOf = (props) => Object.keys(props).sort().map((k) => `${k}=${props[k]}`).join(", ") || "Default";
+function parseComponentSpecs(text) {
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    throw new Error("component-specs.json is not valid JSON.");
+  }
+  const f = data;
+  if (!f || typeof f !== "object" || !Array.isArray(f.components)) throw new Error('component-specs.json has no "components" list.');
+  if (f.version !== COMPONENT_SPECS_VERSION) throw new Error(`component-specs.json is version ${String(f.version)}; this tool reads version ${COMPONENT_SPECS_VERSION}.`);
+  return f;
+}
+
 // src/index.ts
 import { fileURLToPath } from "node:url";
 
@@ -2600,6 +3065,12 @@ function classifyAuth(status, detail, opts = {}) {
   }
   return {};
 }
+function rateLimitMessage(x) {
+  const when = x.resetsAt ? ` It resets at ${x.resetsAt.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })}.` : "";
+  if (x.withToken) return `GitHub's hourly request limit for this token is used up.${when} Try again after that.`;
+  const hint = x.tokenHint ?? "add a GitHub token";
+  return `GitHub's hourly limit for requests without a token (60 an hour) is used up.${when} To keep going now, ${hint}: a token gets 5,000 requests an hour.`;
+}
 var DEFAULT_RETRY = { attempts: 3, baseDelayMs: 600, sleep: (ms) => new Promise((r) => setTimeout(r, ms)) };
 var isTransient = (status, detail) => status === 0 || status >= 500 || status === 429 || status === 403 && /secondary rate limit/i.test(detail);
 var API = "https://api.github.com";
@@ -2703,12 +3174,8 @@ var GitHubClient = class _GitHubClient {
       const remaining = res.headers?.get("x-ratelimit-remaining");
       const reset = res.headers?.get("x-ratelimit-reset");
       if ((res.status === 403 || res.status === 429) && remaining === "0") {
-        const when = reset ? new Date(Number(reset) * 1e3) : void 0;
-        throw new GitHubError(
-          429,
-          `GitHub's hourly request limit for this token is used up.${when ? ` It resets at ${when.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })}.` : ""} Try again after that.`,
-          detail
-        );
+        const resetsAt = reset ? new Date(Number(reset) * 1e3) : void 0;
+        throw new GitHubError(429, rateLimitMessage({ withToken: Boolean(this.token), resetsAt, tokenHint: this.options.tokenHint }), detail);
       }
       const info = classifyAuth(res.status, detail, {
         path,
@@ -3472,6 +3939,132 @@ function jiraIssueFields(r, jira, issueUrl) {
   };
 }
 
+// ../core/src/fidelity-references.ts
+var FIGMA_REFERENCES_DIR = "figma-references";
+var FIGMA_REFERENCES_MANIFEST = `${FIGMA_REFERENCES_DIR}/manifest.json`;
+var FIGMA_REFERENCE_STORY = "internal-figma-reference--variant";
+var FIGMA_FILL_WIDTH_TOKEN = "size.80";
+var STATE_PSEUDO = {
+  default: "rest",
+  rest: "rest",
+  enabled: "rest",
+  hover: "hover",
+  hovered: "hover",
+  pressed: "active",
+  active: "active",
+  focus: "focus-visible",
+  focused: "focus-visible",
+  "focus visible": "focus-visible",
+  disabled: "disabled"
+};
+var iconName = (component) => component.replace(/^Icon\//, "");
+var exportName = (name) => name.replace(/[^A-Za-z0-9]+/g, "");
+function planReference(spec, variant, file) {
+  if (spec.view === "popup") return { ok: false, reason: "drawn open in Figma; the code image shows it closed" };
+  const props = { ...spec.fixed ?? {} };
+  let pseudo;
+  for (const axis of spec.axes) {
+    const value = variant.props[axis.name];
+    if (value === void 0) return { ok: false, reason: `the variant has no ${axis.name} value` };
+    if (axis.prop) {
+      props[axis.prop] = value === "true" ? true : value === "false" ? false : value;
+      continue;
+    }
+    if (axis.name === "Checked") {
+      props.checked = value === "true";
+      if (value === "mixed") props.indeterminate = true;
+      continue;
+    }
+    if (axis.name.toLowerCase() !== "state") return { ok: false, reason: `${axis.name} has no matching option in code` };
+    const s = STATE_PSEUDO[value.toLowerCase()];
+    if (!s) return { ok: false, reason: `the ${value} state has no code equivalent to render` };
+    if (s === "disabled") props.disabled = true;
+    else if (s !== "rest") pseudo = s;
+  }
+  const root = spec.parts.find((p) => !p.parent);
+  if (!root) return { ok: false, reason: "the spec has no root layer" };
+  const children = (id) => spec.parts.filter((p) => p.parent === id);
+  const textOf = (part) => {
+    const swapTo = variant.slots?.[part.id] ?? part.swap?.default;
+    if (part.swap && swapTo) {
+      const slot = file?.slots?.find((s) => s.name === swapTo);
+      if (!slot) return { reason: `${swapTo} is not in the specs` };
+      if (slot.kind !== "text" || !slot.text) return { reason: `Figma shows a placeholder (${swapTo}) that code has no example of` };
+      return slot.text.default;
+    }
+    const prop = spec.properties.find((p) => p.name === part.text && p.type === "TEXT");
+    return typeof prop?.default === "string" ? prop.default : part.name;
+  };
+  let text;
+  const icons = {};
+  for (const prop of spec.properties) {
+    if (prop.type === "TEXT") {
+      const hidden = spec.properties.some((b) => b.type === "BOOLEAN" && b.prop === prop.prop && b.default === false);
+      if (hidden && prop.prop) continue;
+      if (prop.prop === "children") text = String(prop.default);
+      else if (prop.prop) props[prop.prop] = String(prop.default);
+      continue;
+    }
+    const iconPart = spec.parts.find((p) => p.kind === "icon" && p.visible === prop.name);
+    if (prop.default === true && !iconPart && prop.prop && props[prop.prop] === void 0 && spec.example?.p?.[prop.prop] === void 0) props[prop.prop] = true;
+  }
+  for (const part of spec.parts) {
+    if (part.kind !== "icon" || !part.swap) continue;
+    const shown = part.visible ? spec.properties.find((p) => p.name === part.visible)?.default === true : true;
+    if (!shown) continue;
+    if (!part.swap.prop) return { ok: false, reason: `the ${part.name} icon has no matching option in code` };
+    icons[part.swap.prop] = iconName(variant.slots?.[part.id] ?? part.swap.default);
+  }
+  let parts;
+  const loose = spec.properties.filter((p) => p.type === "TEXT" && !p.prop);
+  const frames = children(root.id).filter((p) => p.kind === "frame");
+  const compound = text === void 0 && frames.length > 0 && frames.every((f) => spec.parts.some((p) => p.parent === f.id && p.kind === "text" && (p.swap || p.text === f.name)));
+  if (compound) {
+    parts = [];
+    for (const f of frames) {
+      const t = spec.parts.find((p) => p.parent === f.id && p.kind === "text");
+      const value = textOf(t);
+      if (typeof value !== "string") return { ok: false, reason: value.reason };
+      parts.push({ component: `${exportName(spec.name)}${exportName(f.name)}`, text: value });
+    }
+  }
+  for (const p of loose) {
+    if (p.name === "Value") continue;
+    const part = spec.parts.find((x) => x.text === p.name);
+    if (compound && part && part.parent !== root.id) continue;
+    if (part && /placeholder$/.test(part.id)) {
+      props.placeholder = String(p.default);
+      continue;
+    }
+    return { ok: false, reason: `the ${p.name} text has no matching option in code` };
+  }
+  const example = spec.example;
+  const exampleChildren = example?.children?.length ? example.children : void 0;
+  return {
+    ok: true,
+    render: {
+      component: exportName(spec.view || spec.fixed || example ? example?.c ?? spec.component ?? spec.name : spec.name),
+      props: { ...example?.p ?? {}, ...props },
+      ...exampleChildren ? { children: exampleChildren } : {},
+      ...text !== void 0 && !exampleChildren ? { text } : {},
+      ...parts && !exampleChildren ? { parts } : {},
+      ...Object.keys(icons).length ? { icons } : {},
+      ...pseudo ? { pseudo } : {},
+      ...root.fill ? { width: FIGMA_FILL_WIDTH_TOKEN } : {}
+    }
+  };
+}
+function referenceImagePath(component, key) {
+  const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+  const file = key.split(",").map((kv) => slug(kv)).filter(Boolean).join("__");
+  return `${slug(component)}/${file || "default"}.png`;
+}
+function planReferences(file) {
+  return file.components.flatMap(
+    (spec) => spec.variants.map((v) => ({ component: spec.name, specHash: spec.hash, key: variantKeyOf(v.props), plan: planReference(spec, v, file) }))
+  );
+}
+
 // ../visual/src/capture.ts
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname as dirname2 } from "node:path";
@@ -3495,8 +4088,8 @@ async function launch(o = {}) {
     args: ["--lang=en-US", "--disable-gpu", "--font-render-hinting=none", "--disable-lcd-text", "--force-color-profile=srgb", "--hide-scrollbars", "--disable-skia-runtime-opts", "--disable-renderer-backgrounding"]
   });
 }
-async function newContext(browser, viewport) {
-  const ctx = await browser.newContext({ viewport, deviceScaleFactor: 1, reducedMotion: "reduce", colorScheme: "light", locale: "en-US", timezoneId: "UTC", serviceWorkers: "block" });
+async function newContext(browser, viewport, deviceScaleFactor = 1) {
+  const ctx = await browser.newContext({ viewport, deviceScaleFactor, reducedMotion: "reduce", colorScheme: "light", locale: "en-US", timezoneId: "UTC", serviceWorkers: "block" });
   await ctx.addInitScript(INIT_SCRIPT);
   await ctx.route(
     /^https?:\/\/(?!127\.0\.0\.1[:/]|localhost[:/])/,
@@ -3929,9 +4522,9 @@ function selectImpact(input) {
     app
   };
 }
-function storyId(title, exportName) {
+function storyId(title, exportName2) {
   const sanitize = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-+/, "").replace(/-+$/, "");
-  const startCase = exportName.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z])([A-Z][a-z])/g, "$1 $2").replace(/[_-]+/g, " ").trim();
+  const startCase = exportName2.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z])([A-Z][a-z])/g, "$1 $2").replace(/[_-]+/g, " ").trim();
   return `${sanitize(title)}--${sanitize(startCase)}`;
 }
 function storiesFromSource(files) {
@@ -4446,9 +5039,105 @@ async function runImpact(o) {
   return result;
 }
 
+// ../visual/src/references.ts
+import { existsSync as existsSync5 } from "node:fs";
+import { mkdir as mkdir4, readFile as readFile4, writeFile as writeFile4 } from "node:fs/promises";
+import { dirname as dirname4, join as join5 } from "node:path";
+async function captureFigmaReferences(o) {
+  const log = o.log ?? (() => void 0);
+  const scale = o.scale ?? 2;
+  const brand2 = o.brand ?? "bridge";
+  const theme = o.theme ?? "light";
+  if (!existsSync5(join5(o.storybook, "index.json"))) throw new Error(`No built Storybook in ${o.storybook}: run npm run build-storybook first.`);
+  const index = JSON.parse(await readFile4(join5(o.storybook, "index.json"), "utf8"));
+  if (!index.entries[FIGMA_REFERENCE_STORY]) throw new Error(`The Storybook build has no ${FIGMA_REFERENCE_STORY} story (packages/react/src/stories/FigmaReference.stories.tsx).`);
+  const specs = parseComponentSpecs(await readFile4(o.specs, "utf8"));
+  const jobs = planReferences(specs).filter((j) => !o.only?.length || o.only.includes(j.component));
+  const manifest = {
+    version: 1,
+    tool: "@bridge-ds/visual",
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    sha: o.sha,
+    scale,
+    mode: { brand: brand2, theme, density: "comfortable" },
+    storyId: FIGMA_REFERENCE_STORY,
+    components: {}
+  };
+  for (const j of jobs) manifest.components[j.component] ??= { specHash: j.specHash, variants: {} };
+  let captured = 0;
+  let skipped = 0;
+  const served = await serveDir(o.storybook);
+  const browser = await launch();
+  try {
+    const ctx = await newContext(browser, { width: 1200, height: 800 }, scale);
+    const page = await newPage(ctx);
+    await page.goto(storyUrl(served.url, FIGMA_REFERENCE_STORY, brand2, theme), { waitUntil: "load", timeout: 3e4 });
+    await page.waitForSelector("[data-fidelity-root], [data-fidelity-error]", { state: "attached", timeout: 2e4 });
+    await settle(page, { busy: false });
+    log(`Capturing ${jobs.length} variants at ${scale}x (${brand2} ${theme})`);
+    for (const j of jobs) {
+      const variants = manifest.components[j.component].variants;
+      if (!j.plan.ok) {
+        variants[j.key] = { skipped: j.plan.reason };
+        skipped++;
+        continue;
+      }
+      const plan = JSON.stringify(j.plan.render);
+      await page.evaluate(
+        ({ id, plan: plan2 }) => new Promise((resolve4) => {
+          const ch = window.__STORYBOOK_ADDONS_CHANNEL__;
+          const done = () => {
+            clearTimeout(timer);
+            ch.off("storyRendered", done);
+            resolve4();
+          };
+          const timer = setTimeout(done, 1e4);
+          ch.on("storyRendered", done);
+          ch.emit("updateStoryArgs", { storyId: id, updatedArgs: { plan: plan2 } });
+        }),
+        { id: FIGMA_REFERENCE_STORY, plan }
+      );
+      await settle(page, { network: false, quiet: 2, interval: 40, busy: false });
+      const error = await page.locator("[data-fidelity-error]").first().textContent({ timeout: 200 }).catch(() => null);
+      let target = page.locator("[data-fidelity-root] > *").first();
+      if (!error && !await target.count()) {
+        const marked = page.locator("[data-fidelity-target]").first();
+        await marked.waitFor({ state: "visible", timeout: 3e3 }).catch(() => void 0);
+        await settle(page, { network: false, quiet: 2, interval: 40, busy: false });
+        target = marked;
+      }
+      if (error || !await target.count()) {
+        variants[j.key] = { skipped: error ?? "the code example did not render" };
+        skipped++;
+        continue;
+      }
+      const file = referenceImagePath(j.component, j.key);
+      const path = join5(o.out, file);
+      await mkdir4(dirname4(path), { recursive: true });
+      await target.screenshot({ path, omitBackground: true, animations: "disabled", caret: "hide", scale: "device" });
+      const box = await target.boundingBox();
+      variants[j.key] = { file, width: Math.round(box?.width ?? 0), height: Math.round(box?.height ?? 0) };
+      captured++;
+    }
+    await ctx.close();
+  } finally {
+    await browser.close().catch(() => void 0);
+    await served.close();
+  }
+  await mkdir4(o.out, { recursive: true });
+  const manifestPath = join5(o.out, "manifest.json");
+  await writeFile4(manifestPath, `${JSON.stringify(manifest, null, 2)}
+`);
+  log(`${captured} images, ${skipped} variants skipped. ${manifestPath}`);
+  return { manifest, manifestPath, captured, skipped };
+}
+
+// src/index.ts
+import { execFileSync as execFileSync2 } from "node:child_process";
+
 // src/request.ts
 import { execFileSync, spawnSync } from "node:child_process";
-import { readFile as readFile4 } from "node:fs/promises";
+import { readFile as readFile5 } from "node:fs/promises";
 import { BridgeContext as BridgeContext2, requests as requests2 } from "@bridge-ds/mcp";
 
 // src/jira-sync.ts
@@ -4722,7 +5411,7 @@ ${r.issue.body}`);
       let event = {};
       if (eventPath) {
         try {
-          event = JSON.parse(await readFile4(eventPath, "utf8"));
+          event = JSON.parse(await readFile5(eventPath, "utf8"));
         } catch {
           throw new RequestUsageError(`Could not read the GitHub event at ${eventPath}.`);
         }
@@ -4914,15 +5603,26 @@ Usage:
                                       visual impact: build Storybook and the app at both refs, screenshot
                                       what the change touches, pixel-diff, write manifest.json + images.
                                       Exit 0 even with diffs (2 on setup errors). Needs Chrome installed.
+  bridge figma-references [--storybook storybook-static] [--specs packages/react/component-specs.json]
+                 [--out figma-references] [--sha <sha>] [--only Button,Card] [--json]
+                                      code images for the Figma fidelity check: one PNG per generated
+                                      Figma variant from a built Storybook, plus manifest.json.
+                                      Needs Chrome installed
   bridge history [token] [--json] [--limit n] [--author a] [--tier n] [--version v]
                                       token history: versions, merged changes, who, when, why
   bridge revert <pr|commit|id> [--dry-run] [--restore-conflicts] [--use-before path@file] [--json]
                                       undo a merged token change against HEAD: conflicts shown,
                                       new local bridge/* branch (never pushes, never main)
   bridge audit <path> [--json [out.json]] [--md [out.md]] [--fail-under 80] [--baseline prev.json]
-               [--label "..."] [--ds dir] [--no-regress]
+               [--label "..."] [--ds dir] [--no-regress] [--allowlist known.json]
                                       design system adoption in a product folder: token and component
                                       adoption, hardcoded values with the closest token, top files.
+                                      Reads CSS, SCSS, Less, TS/JS, TSX/JSX, and Astro, Vue and Svelte
+                                      (template markup, frontmatter and <script>, <style> blocks).
+                                      Leave one exception out with a comment on the line above:
+                                      <!-- bridge-audit-ignore-next-line: reason --> (or // or /* */);
+                                      --allowlist lists known file:line exceptions, each with a reason.
+                                      Ignored items stay listed in the report.
                                       Exit 0 ok, 1 under --fail-under or regressed, 2 setup error
   bridge audit <path> --fix [--write] safe autofix: CSS values equal to a token become var(--token).
                                       Dry run unless --write
@@ -4974,9 +5674,9 @@ var print = (s) => process.stdout.write(`${s}
 `);
 var modeArg = (s) => s ? Object.fromEntries(s.split(",").map((kv) => kv.split("="))) : void 0;
 async function init(a, root) {
-  const cfgPath = join5(root, CONFIG_FILE2);
+  const cfgPath = join6(root, CONFIG_FILE2);
   let config;
-  if (existsSync5(cfgPath) && !has3(a, "force")) {
+  if (existsSync6(cfgPath) && !has3(a, "force")) {
     print(`${CONFIG_FILE2} exists, keeping it (--force to regenerate).`);
     config = (await (await BridgeContext4.create({ root })).config()).config;
   } else {
@@ -4984,7 +5684,7 @@ async function init(a, root) {
     const files = await src.list("");
     const repo = await originRepo(root);
     config = await detectConfig(files, (p) => src.read(p), repo ? { repo } : {});
-    await writeFile4(cfgPath, `${JSON.stringify(toConfigJson(config, "https://raw.githubusercontent.com/peterbono/ai-design-system-demo/main/packages/core/bridge.config.schema.json"), null, 2)}
+    await writeFile5(cfgPath, `${JSON.stringify(toConfigJson(config, "https://raw.githubusercontent.com/peterbono/ai-design-system-demo/main/packages/core/bridge.config.schema.json"), null, 2)}
 `);
     print(`Wrote ${CONFIG_FILE2}: tokens in ${config.tokens.root}, ${config.tokens.layers.length} layers, modes ${Object.keys(config.axes).join(", ") || "none"}.`);
     print("Check the layers order (lowest first) and the tiers; detection is a starting point.");
@@ -4993,10 +5693,10 @@ async function init(a, root) {
   const relServer = relative4(root, serverJs);
   const inRepo = !relServer.startsWith("..") && !isAbsolute(relServer);
   const server = (dir) => inRepo ? { command: "node", args: [relServer, "--root", dir] } : { command: "npx", args: ["-y", MCP_PACKAGE, "--root", dir] };
-  const mcpPath = join5(root, ".mcp.json");
-  const existing = existsSync5(mcpPath) ? JSON.parse(await readFile5(mcpPath, "utf8")) : {};
+  const mcpPath = join6(root, ".mcp.json");
+  const existing = existsSync6(mcpPath) ? JSON.parse(await readFile6(mcpPath, "utf8")) : {};
   existing.mcpServers = { ...existing.mcpServers ?? {}, bridge: server(".") };
-  await writeFile4(mcpPath, `${JSON.stringify(existing, null, 2)}
+  await writeFile5(mcpPath, `${JSON.stringify(existing, null, 2)}
 `);
   print(`Wrote .mcp.json: Claude Code picks up the "bridge" server next time it starts in ${root}.`);
   const desktop = inRepo ? { command: "node", args: [serverJs, "--root", root] } : server(root);
@@ -5119,7 +5819,7 @@ async function propose(a, root) {
     edits.push({ op: "set", path: s.slice(0, i), value: s.slice(i + 1), ...file ? { file } : {}, ...mode2 ? { mode: mode2 } : {} });
   }
   const editsFile = flag3(a, "edits");
-  if (editsFile) edits.push(...JSON.parse(await readFile5(resolve3(editsFile), "utf8")));
+  if (editsFile) edits.push(...JSON.parse(await readFile6(resolve3(editsFile), "utf8")));
   if (!edits.length) throw new UsageError("Give at least one --set path=value or --edits file.json");
   const ctx = await BridgeContext4.create({ root });
   const summary = flag3(a, "summary");
@@ -5185,6 +5885,27 @@ async function brandCmd(a, root) {
   if (r.hint) print(String(r.hint));
   return r.status === "blocked" ? 1 : 0;
 }
+async function figmaReferences(a, root) {
+  let sha = flag3(a, "sha");
+  if (!sha) {
+    try {
+      sha = execFileSync2("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf8" }).trim();
+    } catch {
+      sha = "unknown";
+    }
+  }
+  const only = (flag3(a, "only") ?? "").split(",").filter(Boolean);
+  const r = await captureFigmaReferences({
+    storybook: resolve3(root, flag3(a, "storybook") ?? "storybook-static"),
+    specs: resolve3(root, flag3(a, "specs") ?? "packages/react/component-specs.json"),
+    out: resolve3(root, flag3(a, "out") ?? "figma-references"),
+    sha,
+    ...only.length ? { only } : {},
+    log: has3(a, "json") ? void 0 : (line) => print(line)
+  });
+  if (has3(a, "json")) print(JSON.stringify({ manifest: r.manifestPath, captured: r.captured, skipped: r.skipped }, null, 2));
+  return 0;
+}
 async function impact(a, root) {
   const only = (flag3(a, "only") ?? "").split(",").filter(Boolean);
   for (const x of only) if (x !== "stories" && x !== "app") throw new UsageError(`--only takes stories or app, got "${x}"`);
@@ -5294,8 +6015,8 @@ ${r.prBody}`);
 async function audit(a, root) {
   const target = a._[1];
   if (!target) throw new UsageError("bridge audit <path>   (a product folder or file that uses the design system)");
-  if (!existsSync5(target)) throw new UsageError(`No such file or folder: ${target}`);
-  const dsRoot = flag3(a, "ds") ? resolve3(flag3(a, "ds")) : existsSync5(join5(root, CONFIG_FILE2)) ? root : findDesignSystemRoot(root);
+  if (!existsSync6(target)) throw new UsageError(`No such file or folder: ${target}`);
+  const dsRoot = flag3(a, "ds") ? resolve3(flag3(a, "ds")) : existsSync6(join6(root, CONFIG_FILE2)) ? root : findDesignSystemRoot(root);
   if (!dsRoot) throw new UsageError(`No ${CONFIG_FILE2} found: run bridge audit from the design system repo or pass --ds <dir>.`);
   const ds = loadDesignSystem(dsRoot);
   if (has3(a, "fix")) {
@@ -5309,17 +6030,25 @@ async function audit(a, root) {
   const baselinePath = flag3(a, "baseline");
   let baseline;
   if (baselinePath) {
-    if (!existsSync5(baselinePath)) throw new UsageError(`Baseline not found: ${baselinePath}`);
-    baseline = JSON.parse(await readFile5(baselinePath, "utf8"));
+    if (!existsSync6(baselinePath)) throw new UsageError(`Baseline not found: ${baselinePath}`);
+    baseline = JSON.parse(await readFile6(baselinePath, "utf8"));
   }
   const label = flag3(a, "label");
-  const report = runAudit(target, { ds: dsRoot, version: VERSION, ...label ? { label } : {}, ...baseline ? { baseline } : {} });
+  const allowlistPath = flag3(a, "allowlist");
+  if (allowlistPath && !existsSync6(allowlistPath)) throw new UsageError(`Allowlist not found: ${allowlistPath}`);
+  let allowlist;
+  try {
+    allowlist = allowlistPath ? loadAllowlist(allowlistPath) : void 0;
+  } catch (e) {
+    throw new UsageError(`${allowlistPath}: ${e.message}`);
+  }
+  const report = runAudit(target, { ds: dsRoot, version: VERSION, ...label ? { label } : {}, ...baseline ? { baseline } : {}, ...allowlist ? { allowlist } : {} });
   const md = auditMarkdown(report);
   const jsonOut = flag3(a, "json");
   const mdOut = flag3(a, "md");
-  if (jsonOut && jsonOut !== "true") await writeFile4(jsonOut, `${JSON.stringify(report, null, 2)}
+  if (jsonOut && jsonOut !== "true") await writeFile5(jsonOut, `${JSON.stringify(report, null, 2)}
 `);
-  if (mdOut && mdOut !== "true") await writeFile4(mdOut, `${md}
+  if (mdOut && mdOut !== "true") await writeFile5(mdOut, `${md}
 `);
   if (jsonOut === "true") print(JSON.stringify(report, null, 2));
   else if (mdOut === "true") print(md);
@@ -5344,9 +6073,17 @@ async function audit(a, root) {
       print("  top fixes:");
       for (const f of fixes) print(`    ${f.value} -> var(${f.suggestion.cssVar})  ${f.suggestion.level}, ${f.count}x`);
     }
+    const ig = report.ignored;
+    if (ig?.total) print(`  ignored on purpose  ${ig.total} (${ig.comment} by comment, ${ig.allowlist} by the allowlist); listed in --json and --md`);
+    if (ig?.staleAllowlist.length) {
+      print(`  allowlist entries that match nothing any more (remove them):`);
+      for (const e of ig.staleAllowlist) print(`    ${e.file}:${e.line}${e.what ? ` ${e.what}` : ""}`);
+    }
     if (jsonOut) print(`Wrote ${jsonOut}`);
     if (mdOut) print(`Wrote ${mdOut}`);
   }
+  for (const f of report.files) for (const e of f.ignoreErrors ?? []) process.stderr.write(`${report.target.path}/${f.path}:${e.line}: ${e.message}
+`);
   let code = 0;
   const failUnder = flag3(a, "fail-under");
   if (failUnder !== void 0) {
@@ -5429,6 +6166,8 @@ async function main() {
       return brandCmd(a, root);
     case "impact":
       return impact(a, root);
+    case "figma-references":
+      return figmaReferences(a, root);
     case "history":
       return historyCmd(a, root);
     case "revert":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge-ds/cli",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "module",
   "description": "bridge CLI: set up Bridge in a design system repo, check tokens in CI, search and diff tokens, propose changes, start the MCP server.",
   "license": "MIT",
@@ -43,8 +43,8 @@
     "build:package": "node ../../scripts/build-packages.mjs cli"
   },
   "dependencies": {
-    "@bridge-ds/mcp": "^0.3.1",
-    "@bridge-ds/visual": "^0.2.2",
+    "@bridge-ds/mcp": "^0.3.3",
+    "@bridge-ds/visual": "^0.3.0",
     "typescript": "5.9.3"
   },
   "devDependencies": {