1import fs from 'node:fs';
2import path from 'node:path';
3 
4import { finding } from './findings.mjs';
5import { GENERIC_FONTS } from './shared/constants.mjs';
6import { parseAnyColor, resolveLengthPx } from './rules/checks.mjs';
7 
8const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
9const FALLBACK_DIRS = ['.agents/context', 'docs'];
10const COLOR_CHANNEL_TOLERANCE = 6;
11const RADIUS_TOLERANCE_PX = 0.5;
12 
13const CSS_COLOR_RE = /#[0-9a-f]{3,8}\b|rgba?\([^)]+\)|oklch\([^)]+\)|hsla?\([^)]+\)/gi;
14const FONT_DECL_RE = /font-family\s*:\s*([^;}\n]+)/gi;
15const FONT_JS_RE = /fontFamily\s*[:=]\s*["'`]([^"'`]+)["'`]/g;
16const GOOGLE_FONT_RE = /fonts\.googleapis\.com\/css2?\?[^"'\s)<>]*/gi;
17const BORDER_RADIUS_RE = /border-radius\s*:\s*([^;}\n]+)/gi;
18const BORDER_RADIUS_JS_RE = /borderRadius\s*[:=]\s*["'`]([^"'`]+)["'`]/g;
19const STATIC_DESIGN_SKIP_TAGS = new Set(['head', 'title', 'meta', 'link', 'style', 'script', 'noscript', 'template', 'source']);
20 
21function firstExisting(dir, names) {
22  for (const name of names) {
23    const abs = path.join(dir, name);
24    if (fs.existsSync(abs)) return abs;
25  }
26  return null;
27}
28 
29function resolveDesignMdPath(cwd = process.cwd()) {
30  const root = firstExisting(cwd, DESIGN_NAMES);
31  if (root) return { path: root, contextDir: cwd };
32 
33  for (const rel of FALLBACK_DIRS) {
34    const dir = path.resolve(cwd, rel);
35    const found = firstExisting(dir, DESIGN_NAMES);
36    if (found) return { path: found, contextDir: dir };
37  }
38 
39  return null;
40}
41 
42function resolveDesignSidecarPath(cwd = process.cwd(), contextDir = cwd) {
43  const candidates = [
44    path.join(cwd, '.impeccable', 'design.json'),
45    path.join(cwd, 'DESIGN.json'),
46    path.join(contextDir, 'DESIGN.json'),
47  ];
48  return candidates.find((candidate, index) =>
49    candidates.indexOf(candidate) === index && fs.existsSync(candidate)
50  ) || null;
51}
52 
53function parseFrontmatter(md) {
54  const lines = String(md || '').split(/\r?\n/);
55  if (lines[0]?.trim() !== '---') return null;
56  let end = -1;
57  for (let i = 1; i < lines.length; i++) {
58    if (lines[i].trim() === '---') { end = i; break; }
59  }
60  if (end === -1) return null;
61  try {
62    return parseYamlSubset(lines.slice(1, end).join('\n'));
63  } catch {
64    return null;
65  }
66}
67 
68function parseYamlSubset(yaml) {
69  const root = {};
70  const stack = [{ indent: -1, obj: root }];
71 
72  for (const raw of String(yaml || '').split(/\r?\n/)) {
73    if (!raw.trim() || /^\s*#/.test(raw)) continue;
74    const indent = raw.match(/^\s*/)[0].length;
75    const content = raw.slice(indent);
76    const colonIdx = findTopLevelColon(content);
77    if (colonIdx === -1) continue;
78 
79    while (stack.length > 1 && stack[stack.length - 1].indent >= indent) stack.pop();
80 
81    const key = unquoteYamlKey(content.slice(0, colonIdx).trim());
82    const rest = stripInlineYamlComment(content.slice(colonIdx + 1).trim());
83    const parent = stack[stack.length - 1].obj;
84 
85    if (rest === '') {
86      const obj = {};
87      parent[key] = obj;
88      stack.push({ indent, obj });
89    } else {
90      parent[key] = parseScalar(rest);
91    }
92  }
93 
94  return root;
95}
96 
97function findTopLevelColon(s) {
98  let inQuote = null;
99  for (let i = 0; i < s.length; i++) {
100    const ch = s[i];
101    if (inQuote) {
102      if (ch === inQuote && s[i - 1] !== '\\') inQuote = null;
103    } else if (ch === '"' || ch === "'") {
104      inQuote = ch;
105    } else if (ch === ':') {
106      return i;
107    }
108  }
109  return -1;
110}
111 
112function unquoteYamlKey(key) {
113  if ((key.startsWith('"') && key.endsWith('"')) || (key.startsWith("'") && key.endsWith("'"))) {
114    return key.slice(1, -1);
115  }
116  return key;
117}
118 
119function stripInlineYamlComment(s) {
120  let inQuote = null;
121  for (let i = 0; i < s.length; i++) {
122    const ch = s[i];
123    if (inQuote) {
124      if (ch === inQuote && s[i - 1] !== '\\') inQuote = null;
125    } else if (ch === '"' || ch === "'") {
126      inQuote = ch;
127    } else if (ch === '#' && i > 0 && /\s/.test(s[i - 1])) {
128      return s.slice(0, i).trimEnd();
129    }
130  }
131  return s;
132}
133 
134function parseScalar(raw) {
135  const s = raw.trim();
136  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
137    return s.slice(1, -1);
138  }
139  if (s === 'true') return true;
140  if (s === 'false') return false;
141  if (s === 'null' || s === '~') return null;
142  if (/^-?\d+$/.test(s)) return Number(s);
143  if (/^-?\d*\.\d+$/.test(s)) return Number(s);
144  return s;
145}
146 
147function safeReadJson(filePath) {
148  if (!filePath) return null;
149  try {
150    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
151  } catch {
152    return null;
153  }
154}
155 
156function normalizeFontName(value) {
157  return String(value || '')
158    .trim()
159    .replace(/\s*!important\s*$/i, '')
160    .trim()
161    .replace(/^["']|["']$/g, '')
162    .replace(/\+/g, ' ')
163    .replace(/\s+/g, ' ')
164    .toLowerCase();
165}
166 
167function splitFontStack(stack) {
168  return String(stack || '')
169    .replace(/\s*!important\s*$/i, '')
170    .split(',')
171    .map(normalizeFontName)
172    .filter(Boolean);
173}
174 
175function primaryFont(stack) {
176  if (!stack || /var\(/i.test(stack) || !isLiteralFontStack(stack)) return '';
177  return splitFontStack(stack).find(font => !GENERIC_FONTS.has(font)) || '';
178}
179 
180function isLiteralFontStack(stack) {
181  const text = String(stack || '');
182  return !/[$`{}]|\s\+\s|\|\|/.test(text);
183}
184 
185function cssColorLabel(raw) {
186  return String(raw || '').trim().replace(/\s+/g, ' ');
187}
188 
189function colorKey(color) {
190  if (!color) return '';
191  return `${color.r},${color.g},${color.b}`;
192}
193 
194function colorsClose(a, b) {
195  if (!a || !b) return false;
196  return Math.max(
197    Math.abs(a.r - b.r),
198    Math.abs(a.g - b.g),
199    Math.abs(a.b - b.b),
200  ) <= COLOR_CHANNEL_TOLERANCE;
201}
202 
203function hslToRgb(H, S, L, alpha = 1) {
204  const h = (((H % 360) + 360) % 360) / 360;
205  const s = Math.max(0, Math.min(1, S));
206  const l = Math.max(0, Math.min(1, L));
207  const hue2rgb = (p, q, t) => {
208    if (t < 0) t += 1;
209    if (t > 1) t -= 1;
210    if (t < 1 / 6) return p + (q - p) * 6 * t;
211    if (t < 1 / 2) return q;
212    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
213    return p;
214  };
215  const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
216  const p = 2 * l - q;
217  return {
218    r: Math.round(hue2rgb(p, q, h + 1 / 3) * 255),
219    g: Math.round(hue2rgb(p, q, h) * 255),
220    b: Math.round(hue2rgb(p, q, h - 1 / 3) * 255),
221    a: alpha,
222  };
223}
224 
225function parseDesignColor(value) {
226  const text = String(value || '').trim();
227  const parsed = parseAnyColor(text);
228  if (parsed) return parsed;
229  const hsl = text.match(/hsla?\(\s*([-\d.]+)(?:deg)?\s*,?\s*([\d.]+)%\s*,?\s*([\d.]+)%(?:\s*[,/]\s*([\d.]+))?\s*\)/i);
230  if (hsl) {
231    return hslToRgb(
232      parseFloat(hsl[1]),
233      parseFloat(hsl[2]) / 100,
234      parseFloat(hsl[3]) / 100,
235      hsl[4] !== undefined ? parseFloat(hsl[4]) : 1,
236    );
237  }
238  return null;
239}
240 
241function addDesignColor(out, value, label) {
242  const parsed = parseDesignColor(value);
243  if (!parsed) return;
244  const key = colorKey(parsed);
245  if (!out.allowedColorKeys.has(key)) {
246    out.allowedColorKeys.set(key, { color: parsed, labels: [] });
247  }
248  out.allowedColorKeys.get(key).labels.push(label || cssColorLabel(value));
249}
250 
251function addColorObject(out, colors, prefix = 'colors') {
252  if (!colors || typeof colors !== 'object') return;
253  for (const [name, value] of Object.entries(colors)) {
254    if (typeof value === 'string') {
255      addDesignColor(out, value, `${prefix}.${name}`);
256    }
257  }
258}
259 
260function addSidecarColors(out, sidecar) {
261  const colorMeta = sidecar?.extensions?.colorMeta;
262  if (!colorMeta || typeof colorMeta !== 'object') return;
263 
264  for (const [name, meta] of Object.entries(colorMeta)) {
265    if (!meta || typeof meta !== 'object') continue;
266    if (typeof meta.canonical === 'string') addDesignColor(out, meta.canonical, `sidecar.${name}`);
267    if (Array.isArray(meta.tonalRamp)) {
268      for (const [index, value] of meta.tonalRamp.entries()) {
269        if (typeof value === 'string') addDesignColor(out, value, `sidecar.${name}.tonalRamp[${index}]`);
270      }
271    }
272  }
273}
274 
275function addTypographyFonts(out, typography) {
276  if (!typography || typeof typography !== 'object') return;
277  for (const role of Object.values(typography)) {
278    if (!role || typeof role !== 'object') continue;
279    if (typeof role.fontFamily !== 'string') continue;
280    for (const font of splitFontStack(role.fontFamily)) {
281      if (!GENERIC_FONTS.has(font)) out.allowedFonts.add(font);
282    }
283  }
284}
285 
286function addRoundedScale(out, rounded) {
287  if (!rounded || typeof rounded !== 'object') return;
288  for (const [rawName, value] of Object.entries(rounded)) {
289    const name = unquoteYamlKey(rawName).toLowerCase();
290    addRoundedToken(out, name, value);
291  }
292}
293 
294function addRoundedToken(out, name, value) {
295  if (typeof value !== 'string' && typeof value !== 'number') return;
296  const raw = String(value).trim();
297  if (!raw || /var\(/i.test(raw) || raw.includes('%')) return;
298  const px = resolveLengthPx(raw, 16);
299  if (px == null || !Number.isFinite(px)) return;
300  out.allowedRadii.push({ name, value: raw, px });
301  if (/(^|\.)(full|pill|round|rounded-full)$/.test(name)) out.hasPillRadius = true;
302}
303 
304function addSidecarRadii(out, sidecar) {
305  const roundedMeta = sidecar?.extensions?.roundedMeta;
306  if (!roundedMeta || typeof roundedMeta !== 'object') return;
307 
308  for (const [rawName, meta] of Object.entries(roundedMeta)) {
309    const name = unquoteYamlKey(rawName).toLowerCase();
310    if (typeof meta === 'string' || typeof meta === 'number') {
311      addRoundedToken(out, `sidecar.${name}`, meta);
312      continue;
313    }
314    if (!meta || typeof meta !== 'object') continue;
315    for (const key of ['canonical', 'value']) {
316      if (typeof meta[key] === 'string' || typeof meta[key] === 'number') {
317        addRoundedToken(out, `sidecar.${name}.${key}`, meta[key]);
318      }
319    }
320    for (const key of ['values', 'aliases']) {
321      if (!Array.isArray(meta[key])) continue;
322      for (const [index, value] of meta[key].entries()) {
323        addRoundedToken(out, `sidecar.${name}.${key}[${index}]`, value);
324      }
325    }
326    if (/^(full|pill|round|rounded-full)$/.test(name) || /^(full|pill|round)$/i.test(String(meta.role || ''))) {
327      out.hasPillRadius = true;
328    }
329  }
330}
331 
332function normalizeDesignSystem(input = {}) {
333  const frontmatter = input.frontmatter || {};
334  const sidecar = input.sidecar || null;
335  const out = {
336    present: true,
337    sourcePath: input.sourcePath || null,
338    sidecarPath: input.sidecarPath || null,
339    mdNewerThanJson: input.mdNewerThanJson === true,
340    allowedFonts: new Set(),
341    allowedColorKeys: new Map(),
342    allowedRadii: [],
343    hasPillRadius: false,
344  };
345 
346  addTypographyFonts(out, frontmatter.typography);
347  addColorObject(out, frontmatter.colors);
348  addSidecarColors(out, sidecar);
349  addRoundedScale(out, frontmatter.rounded);
350  addSidecarRadii(out, sidecar);
351 
352  out.hasFonts = out.allowedFonts.size > 0;
353  out.hasColors = out.allowedColorKeys.size > 0;
354  out.hasRadii = out.allowedRadii.length > 0;
355  return out;
356}
357 
358function loadDesignSystemForCwd(cwd = process.cwd()) {
359  const md = resolveDesignMdPath(cwd);
360  if (!md) return null;
361 
362  let frontmatter = null;
363  let mdStat = null;
364  try {
365    mdStat = fs.statSync(md.path);
366    frontmatter = parseFrontmatter(fs.readFileSync(md.path, 'utf-8'));
367  } catch {
368    return null;
369  }
370  if (!frontmatter || typeof frontmatter !== 'object') return null;
371 
372  const sidecarPath = resolveDesignSidecarPath(cwd, md.contextDir);
373  const sidecar = safeReadJson(sidecarPath);
374  let sidecarStat = null;
375  try {
376    if (sidecarPath) sidecarStat = fs.statSync(sidecarPath);
377  } catch {
378    sidecarStat = null;
379  }
380 
381  return normalizeDesignSystem({
382    frontmatter,
383    sidecar,
384    sourcePath: md.path,
385    sidecarPath,
386    mdNewerThanJson: !!(mdStat && sidecarStat && mdStat.mtimeMs > sidecarStat.mtimeMs + 1000),
387  });
388}
389 
390function isAllowedFont(font, designSystem) {
391  if (!font || GENERIC_FONTS.has(font)) return true;
392  if (!designSystem?.hasFonts) return true;
393  return designSystem.allowedFonts.has(font);
394}
395 
396function isAllowedColorRaw(raw, designSystem) {
397  if (!designSystem?.hasColors) return true;
398  const text = String(raw || '').trim().toLowerCase();
399  if (!text || text === 'transparent' || text === 'currentcolor' || text === 'inherit' || text === 'initial') return true;
400  if (text.includes('var(')) return true;
401  const parsed = parseDesignColor(text);
402  if (!parsed) return true;
403  if ((parsed.a ?? 1) <= 0.05) return true;
404  for (const entry of designSystem.allowedColorKeys.values()) {
405    if (colorsClose(parsed, entry.color)) return true;
406  }
407  return false;
408}
409 
410function isAllowedRadiusRaw(raw, designSystem) {
411  if (!designSystem?.hasRadii) return true;
412  const text = String(raw || '').trim().toLowerCase();
413  if (!text || text === '0' || text === 'none' || text === 'initial' || text === 'inherit') return true;
414  if (text.includes('var(') || text.includes('%')) return true;
415  const px = resolveLengthPx(text, 16);
416  if (px == null || !Number.isFinite(px) || px <= RADIUS_TOLERANCE_PX) return true;
417  if (designSystem.hasPillRadius && px >= 99) return true;
418  return designSystem.allowedRadii.some(entry => Math.abs(entry.px - px) <= RADIUS_TOLERANCE_PX);
419}
420 
421function lineLooksCommented(line) {
422  const trimmed = String(line || '').trim();
423  return trimmed.startsWith('//') || trimmed.startsWith('/*') || trimmed.startsWith('*') || trimmed.startsWith('<!--');
424}
425 
426function isProbablyColorLiteral(line, match) {
427  const raw = match?.[0] || '';
428  const index = match.index ?? -1;
429  if (index < 0) return false;
430  if (isInsideCssAttributeSelector(line, index)) return false;
431 
432  const before = line.slice(0, index);
433  const after = line.slice(index + raw.length);
434 
435  if (raw.startsWith('#')) {
436    if (before.endsWith('&')) return false; // HTML numeric entity, e.g. &#8596;
437 
438    const prevNonSpace = before.match(/\S(?=\s*$)/)?.[0] || '';
439    const nextNonSpace = after.match(/^\s*(\S)/)?.[1] || '';
440    if (prevNonSpace === '>' && nextNonSpace === '<') return false; // plain text, e.g. PR #155
441  }
442 
443  const styleContext = /(?:^|[{\s;"'`(,])(?:color|background(?:-color|-image)?|border(?:-(?:top|right|bottom|left))?(?:-color)?|outline(?:-color)?|box-shadow|text-shadow|fill|stroke)\s*:\s*[^;{}"'`]*/i.test(before);
444  const cssFunctionContext = /(?:linear-gradient|radial-gradient|conic-gradient|color-mix)\([^)]*$/i.test(before);
445  const jsColorKeyContext = /(?:^|[,{]\s*)(?:color|background|backgroundColor|borderColor|outlineColor|fill|stroke|boxShadow|textShadow)\s*[:=]\s*["'`]?[^"'`,}]*/i.test(before);
446 
447  return styleContext || cssFunctionContext || jsColorKeyContext;
448}
449 
450function isInsideCssAttributeSelector(line, index) {
451  if (index < 0) return false;
452  const before = line.slice(0, index);
453  const lastOpen = before.lastIndexOf('[');
454  if (lastOpen === -1) return false;
455  const lastClose = before.lastIndexOf(']');
456  if (lastClose > lastOpen) return false;
457  const after = line.slice(index);
458  const close = after.indexOf(']');
459  const block = after.indexOf('{');
460  return close !== -1 && (block === -1 || close < block);
461}
462 
463function makeDesignFinding(id, filePath, snippet, line = 0, extras = {}) {
464  return { ...finding(id, filePath, snippet, line), ...extras };
465}
466 
467function decodeGoogleFamily(value) {
468  const family = String(value || '').split(':')[0].replace(/\+/g, ' ');
469  try {
470    return decodeURIComponent(family);
471  } catch {
472    return family;
473  }
474}
475 
476function checkFontStack(stack, filePath, line, designSystem, context) {
477  const primary = primaryFont(stack);
478  if (!primary || isAllowedFont(primary, designSystem)) return [];
479  const display = primary.replace(/\b\w/g, ch => ch.toUpperCase());
480  return [makeDesignFinding(
481    'design-system-font',
482    filePath,
483    `${context}: ${display} is not declared in DESIGN.md typography`,
484    line,
485    { ignoreValue: display },
486  )];
487}
488 
489function extractRadiusTokens(value) {
490  return String(value || '')
491    .replace(/\s*\/\s*/g, ' ')
492    .split(/\s+/)
493    .map(token => token.trim())
494    .filter(Boolean);
495}
496 
497function checkRadiusValue(value, filePath, line, designSystem, context) {
498  const findings = [];
499  for (const token of extractRadiusTokens(value)) {
500    if (isAllowedRadiusRaw(token, designSystem)) continue;
501    findings.push(makeDesignFinding(
502      'design-system-radius',
503      filePath,
504      `${context}: ${token} is outside the DESIGN.md rounded scale`,
505      line,
506      { ignoreValue: token },
507    ));
508  }
509  return findings;
510}
511 
512function checkSourceDesignSystem(content, filePath, options = {}) {
513  const designSystem = options.designSystem;
514  if (!designSystem?.present) return [];
515 
516  const findings = [];
517  const lines = String(content || '').split('\n');
518  for (let i = 0; i < lines.length; i++) {
519    const line = lines[i];
520    const lineNum = i + 1;
521    if (lineLooksCommented(line)) continue;
522 
523    if (designSystem.hasFonts) {
524      for (const match of line.matchAll(FONT_DECL_RE)) {
525        findings.push(...checkFontStack(match[1], filePath, lineNum, designSystem, 'font-family'));
526      }
527      for (const match of line.matchAll(FONT_JS_RE)) {
528        findings.push(...checkFontStack(match[1], filePath, lineNum, designSystem, 'fontFamily'));
529      }
530      for (const match of line.matchAll(GOOGLE_FONT_RE)) {
531        const url = match[0];
532        for (const familyMatch of url.matchAll(/[?&]family=([^&]+)/g)) {
533          const font = normalizeFontName(decodeGoogleFamily(familyMatch[1]));
534          if (!font || isAllowedFont(font, designSystem)) continue;
535          const display = decodeGoogleFamily(familyMatch[1]);
536          findings.push(makeDesignFinding(
537            'design-system-font',
538            filePath,
539            `Google Fonts: ${display} is not declared in DESIGN.md typography`,
540            lineNum,
541            { ignoreValue: display },
542          ));
543        }
544      }
545    }
546 
547    if (designSystem.hasColors) {
548      for (const match of line.matchAll(CSS_COLOR_RE)) {
549        if (!isProbablyColorLiteral(line, match)) continue;
550        const raw = cssColorLabel(match[0]);
551        if (isAllowedColorRaw(raw, designSystem)) continue;
552        findings.push(makeDesignFinding(
553          'design-system-color',
554          filePath,
555          `Undocumented color ${raw} is outside DESIGN.md colors`,
556          lineNum,
557          { ignoreValue: raw },
558        ));
559      }
560    }
561 
562    if (designSystem.hasRadii) {
563      for (const match of line.matchAll(BORDER_RADIUS_RE)) {
564        findings.push(...checkRadiusValue(match[1], filePath, lineNum, designSystem, 'border-radius'));
565      }
566      for (const match of line.matchAll(BORDER_RADIUS_JS_RE)) {
567        findings.push(...checkRadiusValue(match[1], filePath, lineNum, designSystem, 'borderRadius'));
568      }
569    }
570  }
571 
572  return dedupeDesignFindings(findings);
573}
574 
575function hasDirectText(el) {
576  return Array.from(el.childNodes || []).some(node => node.nodeType === 3 && node.textContent.trim().length > 0);
577}
578 
579function sampleText(el) {
580  const text = String(el.textContent || '').replace(/\s+/g, ' ').trim();
581  return text ? ` "${text.slice(0, 40)}"` : '';
582}
583 
584function collectStaticDesignSystemFindings(document, window, filePath, designSystem) {
585  if (!designSystem?.present) return [];
586  const findings = [];
587  const seenFonts = new Set();
588  const seenColors = new Set();
589  const seenRadii = new Set();
590 
591  for (const el of document.querySelectorAll('*')) {
592    if (shouldSkipStaticDesignElement(el, window)) continue;
593    const tag = el.tagName?.toLowerCase?.() || 'unknown';
594    const style = window.getComputedStyle(el);
595 
596    if (designSystem.hasFonts && hasDirectText(el)) {
597      const font = primaryFont(style.fontFamily || '');
598      if (font && !seenFonts.has(font) && !isAllowedFont(font, designSystem)) {
599        seenFonts.add(font);
600        findings.push(makeDesignFinding(
601          'design-system-font',
602          filePath,
603          `${tag}${sampleText(el)} uses ${font}; not declared in DESIGN.md typography`,
604          0,
605          { ignoreValue: font },
606        ));
607      }
608    }
609 
610    if (designSystem.hasColors) {
611      const colorChecks = [];
612      if (hasDirectText(el)) colorChecks.push(['text color', style.color]);
613      if (!isTransparentCss(style.backgroundColor)) colorChecks.push(['background', style.backgroundColor]);
614      for (const side of ['Top', 'Right', 'Bottom', 'Left']) {
615        if ((parseFloat(style[`border${side}Width`]) || 0) > 0) {
616          colorChecks.push([`border-${side.toLowerCase()}`, style[`border${side}Color`]]);
617        }
618      }
619      if ((parseFloat(style.outlineWidth) || 0) > 0) colorChecks.push(['outline', style.outlineColor]);
620 
621      for (const [kind, raw] of colorChecks) {
622        const label = cssColorLabel(raw);
623        if (isAllowedColorRaw(label, designSystem)) continue;
624        const key = `${kind}:${label}`;
625        if (seenColors.has(key)) continue;
626        seenColors.add(key);
627        findings.push(makeDesignFinding(
628          'design-system-color',
629          filePath,
630          `${kind} ${label} on ${tag}${sampleText(el)} is outside DESIGN.md colors`,
631          0,
632          { ignoreValue: label },
633        ));
634      }
635    }
636 
637    if (designSystem.hasRadii) {
638      const rawRadius = String(style.borderRadius || '').trim();
639      if (!rawRadius) continue;
640      for (const token of extractRadiusTokens(rawRadius)) {
641        if (isAllowedRadiusRaw(token, designSystem)) continue;
642        if (seenRadii.has(token)) continue;
643        seenRadii.add(token);
644        findings.push(makeDesignFinding(
645          'design-system-radius',
646          filePath,
647          `border-radius ${token} on ${tag}${sampleText(el)} is outside the DESIGN.md rounded scale`,
648          0,
649          { ignoreValue: token },
650        ));
651      }
652    }
653  }
654 
655  return findings;
656}
657 
658function shouldSkipStaticDesignElement(el, window) {
659  const tag = el.tagName?.toLowerCase?.() || '';
660  if (STATIC_DESIGN_SKIP_TAGS.has(tag)) return true;
661 
662  let current = el;
663  while (current) {
664    if (current.getAttribute?.('hidden') !== null || current.getAttribute?.('aria-hidden') === 'true') return true;
665    const style = window.getComputedStyle(current);
666    const display = String(style.display || '').toLowerCase();
667    const visibility = String(style.visibility || '').toLowerCase();
668    if (display === 'none' || visibility === 'hidden' || visibility === 'collapse') return true;
669    current = current.parentElement;
670  }
671  return false;
672}
673 
674function isTransparentCss(value) {
675  const text = String(value || '').trim().toLowerCase();
676  if (!text || text === 'transparent') return true;
677  const parsed = parseDesignColor(text);
678  return parsed ? (parsed.a ?? 1) <= 0.05 : false;
679}
680 
681function canonicalDesignFindingKey(item) {
682  if (!item?.antipattern?.startsWith?.('design-system-')) return null;
683  const value = item.ignoreValue || item.value || '';
684  if (item.antipattern === 'design-system-font') {
685    const context = /google fonts/i.test(item.snippet || '') ? 'google-font' : 'font';
686    const font = normalizeFontName(value);
687    return font ? `${item.antipattern}:${context}:${font}` : null;
688  }
689  if (item.antipattern === 'design-system-color') {
690    const parsed = parseDesignColor(value);
691    if (parsed) return `${item.antipattern}:color:${colorKey(parsed)}`;
692    const label = cssColorLabel(value).toLowerCase();
693    return label ? `${item.antipattern}:color:${label}` : null;
694  }
695  if (item.antipattern === 'design-system-radius') {
696    const px = resolveLengthPx(String(value || '').trim(), 16);
697    if (px != null && Number.isFinite(px)) return `${item.antipattern}:radius:${Math.round(px * 100) / 100}`;
698    const label = String(value || '').trim().toLowerCase();
699    return label ? `${item.antipattern}:radius:${label}` : null;
700  }
701  return null;
702}
703 
704function mergeDesignSystemFindings(...groups) {
705  const out = [];
706  const seen = new Map();
707  for (const group of groups) {
708    for (const item of group || []) {
709      const key = canonicalDesignFindingKey(item);
710      if (key) {
711        if (seen.has(key)) {
712          const existing = out[seen.get(key)];
713          if ((existing.line || 0) <= 0 && (item.line || 0) > 0) existing.line = item.line;
714          continue;
715        }
716        seen.set(key, out.length);
717      }
718      out.push(item);
719    }
720  }
721  return out;
722}
723 
724function dedupeDesignFindings(findings) {
725  const out = [];
726  const seen = new Set();
727  for (const item of findings) {
728    const key = [
729      item.antipattern,
730      item.line || 0,
731      normalizeFontName(item.ignoreValue || item.snippet || ''),
732    ].join('\0');
733    if (seen.has(key)) continue;
734    seen.add(key);
735    out.push(item);
736  }
737  return out;
738}
739 
740export {
741  parseFrontmatter,
742  normalizeDesignSystem,
743  loadDesignSystemForCwd,
744  isAllowedFont,
745  isAllowedColorRaw,
746  isAllowedRadiusRaw,
747  checkSourceDesignSystem,
748  collectStaticDesignSystemFindings,
749  mergeDesignSystemFindings,
750};
751