argusqa-os 9.5.5 → 9.6.0

package/src/utils/a11y-deep-analyzer.js

@@ -0,0 +1,294 @@
+/**
+ * ARGUS Deep Accessibility Analyzer (Sprint 4 — A12)
+ *
+ * Extends Argus accessibility coverage via two mechanisms:
+ *
+ * 1. axe-core injection — runs the full axe-core ruleset (80+ rules) against
+ *    the live page, covering WCAG 2.x Level A/AA violations not caught by the
+ *    existing snapshot-analyzer or keyboard-analyzer.
+ *
+ * 2. Color blind simulation — transforms page element colors using protanopia
+ *    and deuteranopia CVD matrices, then checks WCAG AA contrast ratios under
+ *    each simulated palette. Flags elements that look fine to full-color vision
+ *    but fail for users with red-green color deficiencies.
+ *
+ * Findings emitted:
+ *   a11y_axe_violation      — axe-core violation; severity mapped from impact
+ *                             (critical→critical, serious/moderate→warning, minor→info)
+ *   a11y_colorblind_risk    — element fails WCAG AA contrast (4.5:1) under
+ *                             protanopia or deuteranopia simulation
+ *   a11y_deep_summary       — info, always emitted with violation counts by impact
+ *
+ * Deduplication: findings already emitted by snapshot-analyzer
+ * (a11y_missing_name, a11y_missing_form_label, heading_level_skip) are
+ * suppressed to avoid double-reporting the same issue.
+ *
+ * Requires axe-core >= 4.12 (npm dependency).
+ */
+
+import fs                    from 'fs';
+import { createRequire }     from 'module';
+import { registerExpensive } from '../registry.js';
+import { unwrapEval }        from './mcp-client.js';
+import { childLogger }       from './logger.js';
+import { thresholds }        from '../config/targets.js';
+
+const logger = childLogger('a11y-deep');
+
+// ── axe-core source (injected into the page at runtime) ───────────────────────
+const _require = createRequire(import.meta.url);
+const AXE_MIN_PATH = _require.resolve('axe-core/axe.min.js');
+const AXE_SOURCE   = fs.readFileSync(AXE_MIN_PATH, 'utf8');
+// Serialize once — used in every evaluate call
+const AXE_SOURCE_JSON = JSON.stringify(AXE_SOURCE);
+
+// ── Thresholds ─────────────────────────────────────────────────────────────────
+const CONTRAST_AA        = thresholds.a11y?.contrastAA        ?? 4.5;   // WCAG AA normal text
+const MAX_AXE_VIOLATIONS = thresholds.a11y?.maxAxeViolations  ?? 50;    // cap per run
+
+// ── Axe impact → Argus severity ───────────────────────────────────────────────
+function axeSeverity(impact) {
+  if (impact === 'critical')                return 'critical';
+  if (impact === 'serious' || impact === 'moderate') return 'warning';
+  return 'info';
+}
+
+// ── Axe-core rule IDs already covered by snapshot/keyboard analyzers ─────────
+// Suppress these to avoid double-reporting.
+const ALREADY_COVERED = new Set([
+  'label',                  // → a11y_missing_form_label
+  'button-name',            // partially → a11y_missing_name (SVG buttons)
+  'heading-order',          // → heading_level_skip
+  'aria-required-children', // → aria_expanded_no_controls
+  'landmark-unique',        // → a11y_duplicate_landmark
+]);
+
+// ── In-browser color-blind simulation script ───────────────────────────────────
+// Returns an array of { selector, colorType, contrastRatio, fg, bg }
+const COLORBLIND_SCRIPT = `() => {
+  // CVD transformation matrices (simplified Machado et al. 2009)
+  var CVD = {
+    protanopia:  [[0.567,0.433,0],[0.558,0.442,0],[0,0.242,0.758]],
+    deuteranopia:[[0.625,0.375,0],[0.7,0.3,0],[0,0.3,0.7]],
+  };
+
+  function parseRgb(str) {
+    var m = (str || '').match(/rgb[a]?\\((\\d+),\\s*(\\d+),\\s*(\\d+)/);
+    return m ? [+m[1], +m[2], +m[3]] : null;
+  }
+
+  function simulateCvd(rgb, matrix) {
+    var r = rgb[0]/255, g = rgb[1]/255, b = rgb[2]/255;
+    return [
+      Math.round((matrix[0][0]*r + matrix[0][1]*g + matrix[0][2]*b) * 255),
+      Math.round((matrix[1][0]*r + matrix[1][1]*g + matrix[1][2]*b) * 255),
+      Math.round((matrix[2][0]*r + matrix[2][1]*g + matrix[2][2]*b) * 255),
+    ];
+  }
+
+  function luminance(rgb) {
+    return rgb.map(function(c) {
+      var v = c / 255;
+      return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+    }).reduce(function(sum, v, i) { return sum + v * [0.2126,0.7152,0.0722][i]; }, 0);
+  }
+
+  function contrastRatio(a, b) {
+    var la = luminance(a), lb = luminance(b);
+    var lighter = Math.max(la, lb), darker = Math.min(la, lb);
+    return (lighter + 0.05) / (darker + 0.05);
+  }
+
+  var issues = [];
+  var seen = new Set();
+
+  var elements = document.querySelectorAll('p,h1,h2,h3,h4,h5,h6,a,button,label,span,li,td,th');
+  for (var i = 0; i < Math.min(elements.length, 200); i++) {
+    var el = elements[i];
+    var style = window.getComputedStyle(el);
+    var fgRgb = parseRgb(style.color);
+    var bgRgb = parseRgb(style.backgroundColor);
+    if (!fgRgb || !bgRgb) continue;
+    // Skip transparent backgrounds
+    if (bgRgb[0] === 0 && bgRgb[1] === 0 && bgRgb[2] === 0 &&
+        style.backgroundColor.includes('rgba(0, 0, 0, 0')) continue;
+
+    var sel = el.tagName.toLowerCase() +
+              (el.id ? '#' + el.id : '') +
+              (el.className && typeof el.className === 'string' ?
+               '.' + el.className.trim().split(/\\s+/)[0] : '');
+
+    for (var type in CVD) {
+      var key = sel + '|' + type;
+      if (seen.has(key)) continue;
+      var simFg = simulateCvd(fgRgb, CVD[type]);
+      var simBg = simulateCvd(bgRgb, CVD[type]);
+      var cr = contrastRatio(simFg, simBg);
+      if (cr < 4.5) {
+        seen.add(key);
+        issues.push({
+          selector: sel,
+          colorType: type,
+          contrastRatio: Math.round(cr * 100) / 100,
+          fg: 'rgb(' + fgRgb.join(',') + ')',
+          bg: 'rgb(' + bgRgb.join(',') + ')',
+        });
+      }
+    }
+  }
+  return JSON.stringify(issues);
+}`;
+
+// ── Public API ─────────────────────────────────────────────────────────────────
+
+/**
+ * Run axe-core + color blind simulation against a loaded page.
+ *
+ * @param {object} browser - CdpBrowserAdapter
+ * @param {string} url     - Page URL (already loaded by caller or navigate here)
+ * @returns {Promise<object[]>}
+ */
+export async function analyzeA11yDeep(browser, url) {
+  const findings = [];
+
+  // Navigate fresh
+  try {
+    await browser.navigate(url);
+    await browser.waitFor({ state: 'networkidle' }).catch(() => {});
+    await new Promise(r => setTimeout(r, 800));
+  } catch {
+    return findings;
+  }
+
+  // ── 1. Inject axe-core ────────────────────────────────────────────────────
+  try {
+    await browser.evaluate(`() => {
+      if (!window.axe) {
+        const s = document.createElement('script');
+        s.textContent = ${AXE_SOURCE_JSON};
+        document.head.appendChild(s);
+      }
+      return !!window.axe;
+    }`);
+  } catch (err) {
+    logger.warn(`[ARGUS] a11y-deep: axe-core injection failed for ${url}: ${err.message}`);
+    return findings;
+  }
+
+  // ── 2. Run axe-core analysis ──────────────────────────────────────────────
+  let violations = [];
+  try {
+    const raw = await browser.evaluate(`async () => {
+      if (!window.axe) return '{"violations":[]}';
+      try {
+        const results = await window.axe.run(document, {
+          reporter: 'v2',
+          runOnly: { type: 'tag', values: ['wcag2a','wcag2aa','wcag21a','wcag21aa','best-practice'] },
+        });
+        return JSON.stringify({
+          violations: results.violations.map(v => ({
+            id:          v.id,
+            impact:      v.impact,
+            description: v.description,
+            helpUrl:     v.helpUrl,
+            nodes:       v.nodes.slice(0, 3).map(n => ({
+              target:  (n.target || []).join(', ').slice(0, 100),
+              html:    (n.html || '').slice(0, 150),
+              impact:  n.impact,
+            })),
+          })),
+        });
+      } catch (e) { return '{"violations":[]}'; }
+    }`);
+
+    const parsed = (() => {
+      try {
+        const s = unwrapEval(raw);
+        return typeof s === 'object' ? s : JSON.parse(s);
+      } catch { return null; }
+    })();
+
+    violations = parsed?.violations ?? [];
+  } catch (err) {
+    logger.warn(`[ARGUS] a11y-deep: axe.run() failed for ${url}: ${err.message}`);
+  }
+
+  // ── 3. Map violations → findings (with dedup suppression) ────────────────
+  let criticalCount = 0, seriousCount = 0, moderateCount = 0, minorCount = 0;
+
+  for (const v of violations.slice(0, MAX_AXE_VIOLATIONS)) {
+    if (ALREADY_COVERED.has(v.id)) continue;
+
+    const sev = axeSeverity(v.impact);
+    if (v.impact === 'critical') criticalCount++;
+    else if (v.impact === 'serious') seriousCount++;
+    else if (v.impact === 'moderate') moderateCount++;
+    else minorCount++;
+
+    for (const node of (v.nodes || [{ target: '', html: '' }]).slice(0, 2)) {
+      findings.push({
+        type:        'a11y_axe_violation',
+        axeId:       v.id,
+        impact:      v.impact,
+        selector:    node.target || '',
+        html:        node.html || '',
+        description: v.description,
+        helpUrl:     v.helpUrl,
+        message:     `[axe] ${v.impact}: ${v.description} — ${node.target || 'page'}`,
+        severity:    sev,
+        url,
+      });
+    }
+  }
+
+  // ── 4. Color blind simulation ─────────────────────────────────────────────
+  let colorblindIssues = [];
+  try {
+    const raw = await browser.evaluate(COLORBLIND_SCRIPT);
+    const parsed = (() => {
+      try {
+        const s = unwrapEval(raw);
+        return typeof s === 'string' ? JSON.parse(s) : s;
+      } catch { return []; }
+    })();
+    colorblindIssues = Array.isArray(parsed) ? parsed : [];
+  } catch (err) {
+    logger.warn(`[ARGUS] a11y-deep: color blind check failed for ${url}: ${err.message}`);
+  }
+
+  for (const issue of colorblindIssues.slice(0, 20)) {
+    findings.push({
+      type:         'a11y_colorblind_risk',
+      selector:     issue.selector,
+      colorType:    issue.colorType,
+      contrastRatio: issue.contrastRatio,
+      fg:           issue.fg,
+      bg:           issue.bg,
+      message:      `Color blind risk (${issue.colorType}): contrast ${issue.contrastRatio}:1 < ${CONTRAST_AA}:1 on ${issue.selector}`,
+      severity:     'warning',
+      url,
+    });
+  }
+
+  // ── 5. Summary — always emitted ───────────────────────────────────────────
+  findings.push({
+    type:            'a11y_deep_summary',
+    axeViolations:   violations.filter(v => !ALREADY_COVERED.has(v.id)).length,
+    criticalCount,
+    seriousCount,
+    moderateCount,
+    minorCount,
+    colorblindRisks: colorblindIssues.length,
+    message:         `axe-core: ${criticalCount} critical, ${seriousCount} serious, ${moderateCount} moderate, ${minorCount} minor violations; ${colorblindIssues.length} color blind contrast risks`,
+    severity:        'info',
+    url,
+  });
+
+  return findings;
+}
+
+// ── Self-registration ──────────────────────────────────────────────────────────
+registerExpensive({
+  name:    'a11y-deep',
+  analyze: (browser, url) => analyzeA11yDeep(browser, url),
+});

package/src/utils/baseline-manager.js

@@ -110,7 +110,7 @@ export function saveBaseline(baselineFile, report) {
     flows[flowResult.flowName] = (flowResult.findings ?? []).map(findingKey);
   }
   const codebase = (report.codebase ?? []).map(findingKey);
-  const tmpBaseline = baselineFile + '.tmp';
+  const tmpBaseline = `${baselineFile}.${process.pid}.${Date.now()}.tmp`;
   fs.writeFileSync(
     tmpBaseline,
     JSON.stringify({ savedAt: new Date().toISOString(), routes, flows, codebase }, null, 2),
@@ -245,8 +245,8 @@ export function appendTrend(trendsFile, entry) {
     }
     trends.push(entry);
     if (trends.length > 500) trends = trends.slice(-500);
-    const tmpTrends = trendsFile + '.tmp';
-    fs.writeFileSync(tmpTrends, JSON.stringify(trends, null, 2));
+    const tmpTrends = `${trendsFile}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tmpTrends, JSON.stringify(trends, null, 2)); // lgtm[js/network-data-to-file] — intentional: Argus persists crawl trend data to a local baseline file by design
     fs.renameSync(tmpTrends, trendsFile);
   } finally {
     try { fs.closeSync(lockFd); } catch {}

package/src/utils/codebase-analyzer.js

@@ -40,9 +40,9 @@ function collectSourceFiles(sourceDir) {
       if (e.isDirectory()) { walk(full); }
       else if (SOURCE_EXTENSIONS.has(path.extname(e.name))) {
         try {
-          const stat = fs.statSync(full);
-          if (stat.size > 1_000_000) continue; // skip files > 1MB (minified bundles, etc.)
-          files.push({ filePath: full, content: fs.readFileSync(full, 'utf8') });
+          const content = fs.readFileSync(full, 'utf8');
+          if (Buffer.byteLength(content, 'utf8') > 1_000_000) continue; // skip files > 1MB
+          files.push({ filePath: full, content });
         } catch {}
       }
     }

package/src/utils/content-analyzer.js

@@ -97,7 +97,7 @@ export function parseContentAnalysisResult(rawResult, url) {
     // all field lookups (nullMatches, brokenImages, etc.) return undefined — zero findings.
     // JSON.stringify on a circular object throws; catch logs and returns [].
     let raw = rawResult;
-    if (typeof raw === 'object' && !Array.isArray(raw) && raw !== null && raw.result !== undefined) {
+    if (typeof raw === 'object' && !Array.isArray(raw) && raw !== null && raw.result !== undefined) { // lgtm[js/comparison-of-unconvertible-types] — typeof null === 'object', so raw !== null is required after the typeof check
       raw = raw.result;
     }
     const str = typeof raw === 'string' ? raw : JSON.stringify(raw);

package/src/utils/flow-runner.js

@@ -223,7 +223,7 @@ async function runAssert(step, browser, flowName, baseUrl, baselines) {
       const start = Date.now();
       let present = false;
       do {
-        const raw = await browser.evaluate(`() => !!document.querySelector(${JSON.stringify(step.selector)})`);
+        const raw = await browser.evaluate(`() => !!document.querySelector(${JSON.stringify(step.selector)})`); // lgtm[js/code-injection] — selector is JSON.stringify-escaped; derived from developer-configured flow steps, not HTTP input
         present = !!unwrapEval(raw);
         if (present) break;
         await new Promise(r => setTimeout(r, 200));
@@ -244,7 +244,7 @@ async function runAssert(step, browser, flowName, baseUrl, baselines) {
     }
 
     case 'element_not_visible': {
-      const raw = await browser.evaluate(`() => !document.querySelector(${JSON.stringify(step.selector)})`);
+      const raw = await browser.evaluate(`() => !document.querySelector(${JSON.stringify(step.selector)})`); // lgtm[js/code-injection] — selector is JSON.stringify-escaped; derived from developer-configured flow steps, not HTTP input
       const absent = unwrapEval(raw);
       if (!absent) {
         findings.push({
@@ -261,7 +261,7 @@ async function runAssert(step, browser, flowName, baseUrl, baselines) {
     }
 
     case 'url_contains': {
-      const raw = await browser.evaluate(`() => window.location.href.includes(${JSON.stringify(step.value)})`);
+      const raw = await browser.evaluate(`() => window.location.href.includes(${JSON.stringify(step.value)})`); // lgtm[js/code-injection] — value is JSON.stringify-escaped; derived from developer-configured flow steps, not HTTP input
       const matches = unwrapEval(raw);
       if (!matches) {
         findings.push({
@@ -545,7 +545,7 @@ export async function runFlow(flow, baseUrl, browser) {
 export async function waitForSelector(browser, selector, timeoutMs = 10_000) {
   const end = Date.now() + timeoutMs;
   while (Date.now() < end) {
-    const raw = await browser.evaluate(`() => !!document.querySelector(${JSON.stringify(selector)})`).catch(() => null);
+    const raw = await browser.evaluate(`() => !!document.querySelector(${JSON.stringify(selector)})`).catch(() => null); // lgtm[js/code-injection] — selector is JSON.stringify-escaped; derived from developer-configured flow steps, not HTTP input
     const found = unwrapEval(raw);
     if (found === true || String(found) === 'true') return true;
     if (Date.now() < end) await new Promise(r => setTimeout(r, 300));

package/src/utils/font-analyzer.js

@@ -0,0 +1,213 @@
+/**
+ * ARGUS Font Loading Analyzer (Sprint 5c — A10)
+ *
+ * Detects web font performance and reliability issues that cause invisible
+ * text (FOIT), layout shifts (FOUT/CLS), or deliver fonts in suboptimal formats.
+ *
+ * Findings emitted:
+ *   font_foit_risk         — @font-face with no font-display (defaults to auto = FOIT)
+ *   font_fout_risk         — font-display: swap or fallback (layout shift risk)
+ *   font_no_fallback       — font-family with web font but no system font fallback
+ *   font_slow_load         — web font resource took > threshold ms (PerformanceResourceTiming)
+ *   font_suboptimal_format — font served as .ttf or .eot (not .woff2)
+ *   font_summary           — info, always emitted
+ */
+
+import { registerExpensive } from '../registry.js';
+import { unwrapEval }        from './mcp-client.js';
+import { childLogger }       from './logger.js';
+import { thresholds }        from '../config/targets.js';
+
+const logger         = childLogger('font-analyzer');
+const SLOW_FONT_MS   = thresholds.font?.slowLoadMs ?? 1000;
+
+// System font families that serve as valid fallbacks
+const SYSTEM_FONTS = /serif|sans-serif|monospace|cursive|fantasy|system-ui|ui-serif|ui-sans-serif|ui-monospace|arial|helvetica|verdana|georgia|times|courier|trebuchet|impact|comic sans/i;
+
+const FONT_SCRIPT = `() => {
+  var result = {
+    fontFaceRules:    [],
+    fontFamilyUsages: [],
+    slowFonts:        [],
+    suboptimalFonts:  [],
+  };
+
+  // ── Inspect @font-face rules ───────────────────────────────────────────
+  var sheets = Array.from(document.styleSheets);
+  for (var i = 0; i < sheets.length; i++) {
+    var rules;
+    try { rules = Array.from(sheets[i].cssRules || []); } catch { continue; }
+    for (var j = 0; j < rules.length; j++) {
+      var rule = rules[j];
+      if (rule.type !== CSSRule.FONT_FACE_RULE) continue;
+      var style       = rule.style;
+      var family      = (style.getPropertyValue('font-family') || '').replace(/['"]/g, '').trim();
+      var display     = style.getPropertyValue('font-display') || '';
+      var src         = style.getPropertyValue('src') || '';
+
+      result.fontFaceRules.push({
+        family:  family,
+        display: display || 'auto',
+        src:     src.slice(0, 200),
+        hasDisplay: display !== '',
+      });
+
+      // Suboptimal format: .ttf or .eot in src
+      if (/\\.ttf|format\\(('|")truetype('|")\\)|format\\(('|")embedded-opentype('|")\\)/.test(src)) {
+        result.suboptimalFonts.push({ family: family, src: src.slice(0, 100) });
+      }
+    }
+  }
+
+  // ── Inspect font-family declarations for fallback stacks ──────────────
+  for (var si = 0; si < sheets.length; si++) {
+    var rules2;
+    try { rules2 = Array.from(sheets[si].cssRules || []); } catch { continue; }
+    for (var sj = 0; sj < rules2.length; sj++) {
+      var r = rules2[sj];
+      if (r.type !== CSSRule.STYLE_RULE) continue;
+      var ff = r.style && r.style.fontFamily;
+      if (!ff) continue;
+      // Only flag declarations that reference a custom font (quoted name = web font)
+      if (!/'|"/.test(ff)) continue;
+      result.fontFamilyUsages.push({
+        selector: (r.selectorText || '').slice(0, 80),
+        fontFamily: ff.slice(0, 150),
+      });
+    }
+  }
+
+  // ── PerformanceResourceTiming: slow + suboptimal format fonts ─────────
+  var fontEntries = performance.getEntriesByType('resource').filter(function(e) {
+    return /\\.(woff2?|ttf|otf|eot)(\\?.*)?$/i.test(e.name);
+  });
+  for (var fi = 0; fi < fontEntries.length; fi++) {
+    var fe = fontEntries[fi];
+    var duration = Math.round(fe.duration);
+    result.slowFonts.push({
+      url:      fe.name.slice(0, 150),
+      duration: duration,
+      format:   /\\.ttf/.test(fe.name) ? 'ttf' : /\\.eot/.test(fe.name) ? 'eot' :
+                /\\.woff2/.test(fe.name) ? 'woff2' : 'woff',
+    });
+  }
+
+  return JSON.stringify(result);
+}`;
+
+export async function analyzeFont(browser, url) {
+  const findings = [];
+
+  try {
+    await browser.navigate(url);
+    await browser.waitFor({ state: 'networkidle' }).catch(() => {});
+    await new Promise(r => setTimeout(r, 500));
+  } catch {
+    return findings;
+  }
+
+  let data = null;
+  try {
+    const raw = await browser.evaluate(FONT_SCRIPT);
+    const s   = unwrapEval(raw);
+    data = typeof s === 'object' ? s : JSON.parse(s);
+  } catch (err) {
+    logger.warn(`[ARGUS] font-analyzer: failed for ${url}: ${err.message}`);
+    data = { fontFaceRules: [], fontFamilyUsages: [], slowFonts: [], suboptimalFonts: [] };
+  }
+
+  const fontFaceRules    = data.fontFaceRules    ?? [];
+  const fontFamilyUsages = data.fontFamilyUsages ?? [];
+  const slowFonts        = data.slowFonts        ?? [];
+  const suboptimalFonts  = data.suboptimalFonts  ?? [];
+
+  let foitCount = 0, foutCount = 0, noFallbackCount = 0, slowCount = 0, suboptCount = 0;
+
+  // FOIT risk: @font-face without font-display
+  for (const rule of fontFaceRules) {
+    if (!rule.hasDisplay) {
+      foitCount++;
+      findings.push({
+        type:       'font_foit_risk',
+        message:    `@font-face for '${rule.family}' has no font-display — defaults to 'auto' (FOIT risk in Chrome)`,
+        fontFamily: rule.family,
+        severity:   'warning',
+        url,
+      });
+    } else if (rule.display === 'swap' || rule.display === 'fallback') {
+      // FOUT risk: swap/fallback causes layout shift on font load
+      foutCount++;
+      findings.push({
+        type:        'font_fout_risk',
+        message:     `@font-face for '${rule.family}' uses font-display: ${rule.display} — layout shift (CLS) risk if fallback metrics differ`,
+        fontFamily:  rule.family,
+        fontDisplay: rule.display,
+        severity:    'info',
+        url,
+      });
+    }
+  }
+
+  // No system fallback: quoted font-family with no generic fallback
+  for (const usage of fontFamilyUsages) {
+    const hasFallback = SYSTEM_FONTS.test(usage.fontFamily);
+    if (!hasFallback) {
+      noFallbackCount++;
+      findings.push({
+        type:       'font_no_fallback',
+        message:    `font-family '${usage.fontFamily}' on '${usage.selector}' has no system font fallback — invisible text if web font fails to load`,
+        selector:   usage.selector,
+        fontFamily: usage.fontFamily,
+        severity:   'warning',
+        url,
+      });
+    }
+  }
+
+  // Slow font loads (from PerformanceResourceTiming)
+  for (const f of slowFonts) {
+    if (f.duration > SLOW_FONT_MS) {
+      slowCount++;
+      findings.push({
+        type:     'font_slow_load',
+        message:  `Web font took ${f.duration}ms to load (threshold: ${SLOW_FONT_MS}ms): ${f.url}`,
+        fontUrl:  f.url,
+        duration: f.duration,
+        severity: 'warning',
+        url,
+      });
+    }
+  }
+
+  // Suboptimal font format (.ttf/.eot in @font-face src)
+  for (const f of suboptimalFonts) {
+    suboptCount++;
+    findings.push({
+      type:       'font_suboptimal_format',
+      message:    `Font '${f.family}' served in suboptimal format (TTF/EOT) — use WOFF2 for production`,
+      fontFamily: f.family,
+      severity:   'info',
+      url,
+    });
+  }
+
+  // Summary — always emitted
+  findings.push({
+    type:           'font_summary',
+    foitRisks:      foitCount,
+    foutRisks:      foutCount,
+    noFallbacks:    noFallbackCount,
+    slowLoads:      slowCount,
+    suboptimalFmts: suboptCount,
+    message:        `Font: ${foitCount} FOIT, ${foutCount} FOUT, ${noFallbackCount} no-fallback, ${slowCount} slow, ${suboptCount} suboptimal-format`,
+    severity:       'info',
+    url,
+  });
+
+  return findings;
+}
+
+registerExpensive({
+  name:    'font',
+  analyze: (browser, url) => analyzeFont(browser, url),
+});