argusqa-os 9.2.0

package/src/utils/css-analyzer.js

@@ -0,0 +1,407 @@
+/**
+ * ARGUS CSS Analyzer
+ *
+ * Works with React + SCSS projects. SCSS is compiled to CSS before the browser
+ * sees it, so this analyzer works on the live compiled output.
+ *
+ * React-aware features:
+ *   - CSS Modules: detects hashed class names (_button_abc123) and maps them
+ *     back to readable component names from data-* attributes and element context
+ *   - Inline style conflicts: detects React inline style props that override
+ *     stylesheet declarations on the same element
+ *   - SCSS compiled source: reads sourceMappingURL comments to attribute rules
+ *     back to original .scss files where possible
+ *   - CSS-in-JS (styled-components/emotion): inline <style> tags are analyzed
+ *     the same way as external stylesheets
+ *
+ * Injected via evaluate_script into the live page to analyze:
+ *   1. Which CSS rules are actually applied to matched elements
+ *   2. Which properties are overridden (cascade conflicts)
+ *   3. Which styles are leaking from unexpected components/sources
+ *   4. Unused rules — declared but no element matches them
+ *   5. React inline style conflicts with stylesheet declarations
+ *   6. CSS Modules health (hashed class name leakage across components)
+ *
+ * Returns a structured JSON report that Claude Code processes into bug entries.
+ */
+
+import { childLogger } from './logger.js';
+
+const logger = childLogger('css-analyzer');
+
+/**
+ * JavaScript string injected into the page via mcp.evaluate_script.
+ * Runs entirely in the page context — no Node.js APIs available here.
+ */
+export const CSS_ANALYSIS_SCRIPT = `
+() => {
+  const report = {
+    stylesheetSources: [],
+    overriddenProperties: [],
+    unusedRules: [],
+    componentLeaks: [],
+    inlineStyleConflicts: [],
+    cssModulesDetected: false,
+    scssSourceFiles: [],
+    summary: { totalRules: 0, appliedRules: 0, unusedRules: 0, overrides: 0, leaks: 0, inlineConflicts: 0 }
+  };
+
+  // ── 1. Collect all stylesheets and their sources ───────────────────────────
+  const sheets = Array.from(document.styleSheets);
+  for (const sheet of sheets) {
+    try {
+      const source = sheet.href ?? (sheet.ownerNode?.tagName === 'STYLE' ? 'inline' : 'unknown');
+      const ruleCount = sheet.cssRules?.length ?? 0;
+      report.stylesheetSources.push({ source, ruleCount });
+      report.summary.totalRules += ruleCount;
+    } catch {
+      // Cross-origin stylesheet — can't access cssRules
+      report.stylesheetSources.push({ source: sheet.href ?? 'cross-origin', ruleCount: -1, blocked: true });
+    }
+  }
+
+  // ── 2. Flatten all accessible CSS rules ───────────────────────────────────
+  const allRules = [];
+  for (const sheet of sheets) {
+    let rules;
+    try { rules = Array.from(sheet.cssRules ?? []); } catch { continue; }
+    const sheetSource = sheet.href ?? 'inline';
+
+    for (const rule of rules) {
+      if (rule.type === CSSRule.STYLE_RULE) {
+        allRules.push({ selector: rule.selectorText, declarations: rule.style, source: sheetSource, rule });
+      }
+      // Handle @media rules — flatten their contents
+      if (rule.type === CSSRule.MEDIA_RULE) {
+        try {
+          for (const mediaRule of Array.from(rule.cssRules ?? [])) {
+            if (mediaRule.type === CSSRule.STYLE_RULE) {
+              allRules.push({ selector: mediaRule.selectorText, declarations: mediaRule.style, source: sheetSource + ' (@media)', rule: mediaRule });
+            }
+          }
+        } catch {}
+      }
+    }
+  }
+
+  // ── 3. Check each rule: does it match any element? ─────────────────────────
+  for (const { selector, declarations, source, rule } of allRules) {
+    if (!selector) continue;
+    let matched = false;
+    try {
+      matched = document.querySelectorAll(selector).length > 0;
+    } catch {
+      // Invalid selector (e.g. vendor-prefixed pseudo-elements) — skip
+      continue;
+    }
+
+    if (!matched) {
+      report.unusedRules.push({
+        selector,
+        source,
+        propertyCount: declarations.length,
+      });
+      report.summary.unusedRules++;
+    } else {
+      report.summary.appliedRules++;
+    }
+  }
+
+  // ── 4. Detect property overrides (cascade conflicts) ──────────────────────
+  // For each matched element, collect all rules that apply and find properties
+  // declared more than once (the losers are overridden).
+  const keyElements = [
+    ...Array.from(document.querySelectorAll('h1,h2,h3,p,button,a,input,nav,header,footer,main,section,article')).slice(0, 50)
+  ];
+
+  for (const el of keyElements) {
+    const elementRules = []; // { property, value, source, priority, selector }
+
+    for (const { selector, declarations, source } of allRules) {
+      let matches = false;
+      try { matches = el.matches(selector); } catch { continue; }
+      if (!matches) continue;
+
+      for (let i = 0; i < declarations.length; i++) {
+        const prop = declarations.item(i);
+        const value = declarations.getPropertyValue(prop);
+        const priority = declarations.getPropertyPriority(prop);
+        elementRules.push({ property: prop, value, source, priority, selector });
+      }
+    }
+
+    // Group by property — more than one entry = override
+    const byProp = {};
+    for (const entry of elementRules) {
+      if (!byProp[entry.property]) byProp[entry.property] = [];
+      byProp[entry.property].push(entry);
+    }
+
+    for (const [property, entries] of Object.entries(byProp)) {
+      if (entries.length <= 1) continue;
+
+      const tag = el.tagName.toLowerCase();
+      const id = el.id ? '#' + el.id : '';
+      const cls = el.className && typeof el.className === 'string'
+        ? '.' + el.className.trim().split(/\\s+/).slice(0, 2).join('.')
+        : '';
+      const elementDesc = tag + id + cls;
+
+      // Detect !important overrides — higher severity
+      const hasImportant = entries.some(e => e.priority === 'important');
+
+      report.overriddenProperties.push({
+        element: elementDesc,
+        property,
+        declarations: entries.map(e => ({ selector: e.selector, value: e.value, source: e.source, important: e.priority === 'important' })),
+        hasImportant,
+        overrideCount: entries.length,
+      });
+      report.summary.overrides++;
+    }
+  }
+
+  // ── 5. CSS Modules detection ───────────────────────────────────────────────
+  // Detect if the project uses CSS Modules by checking for hashed class names
+  // on DOM elements (pattern: _ComponentName_classname_hash or ComponentName_class_hash)
+  const allClassNames = Array.from(document.querySelectorAll('[class]'))
+    .flatMap(el => Array.from(el.classList));
+  const cssModulePattern = /^_?[A-Za-z][\\w-]*_[A-Za-z][\\w-]*_[A-Za-z0-9]{4,}$/;
+  const hashedClasses = allClassNames.filter(c => cssModulePattern.test(c));
+  report.cssModulesDetected = hashedClasses.length > 0;
+
+  if (report.cssModulesDetected) {
+    // Extract readable component names from the hash pattern
+    // e.g. _Button_primary_abc123 → component = "Button"
+    const moduleComponents = new Set();
+    for (const cls of hashedClasses) {
+      const parts = cls.replace(/^_/, '').split('_');
+      if (parts.length >= 2) moduleComponents.add(parts[0]);
+    }
+    report.cssModulesComponents = Array.from(moduleComponents);
+  }
+
+  // ── 6. Component style leak detection (global SCSS / BEM only) ────────────
+  // Skip for CSS Modules — hashed class names are intentionally scoped.
+  // Only check BEM selectors in non-hashed, non-CSS-Modules stylesheets.
+  const componentPatterns = [
+    /\\.([\\w-]+)__([\\w-]+)/,         // BEM: .block__element
+    /\\.([\\w-]+)--([\\w-]+)/,         // BEM modifier: .block--modifier
+    /\\[data-component="([^"]+)"\\]/,  // data-component attribute selectors
+  ];
+
+  for (const { selector, source } of allRules) {
+    if (!selector) continue;
+    // Skip CSS Modules hashed selectors entirely
+    if (/\\._?[A-Z][\\w]*_[\\w-]+_[A-Za-z0-9]{4,}/.test(selector)) continue;
+    for (const pattern of componentPatterns) {
+      const match = selector.match(pattern);
+      if (!match) continue;
+      const componentName = match[1];
+      const sourceFile = source.split('/').pop() ?? source;
+      if (!sourceFile.toLowerCase().includes(componentName.toLowerCase()) && source !== 'inline') {
+        report.componentLeaks.push({
+          selector,
+          componentHint: componentName,
+          foundInSource: source,
+          description: \`Selector "\${selector}" suggests component "\${componentName}" but was found in "\${sourceFile}"\`,
+        });
+        report.summary.leaks++;
+      }
+      break;
+    }
+  }
+
+  // ── 7. SCSS source file detection ─────────────────────────────────────────
+  // Read sourceMappingURL comments from inline <style> tags to trace compiled
+  // CSS back to original .scss source files where source maps are available.
+  const styleTags = Array.from(document.querySelectorAll('style'));
+  for (const tag of styleTags) {
+    const content = tag.textContent ?? '';
+    const sourceMapMatch = content.match(/\\/\\*#\\s*sourceMappingURL=([^\\s*]+)/);
+    if (sourceMapMatch) {
+      report.scssSourceFiles = report.scssSourceFiles || [];
+      report.scssSourceFiles.push({ sourceMap: sourceMapMatch[1], inline: true });
+    }
+  }
+
+  // ── 8. React inline style conflicts ───────────────────────────────────────
+  // Find React elements with style="" attributes where the inline value
+  // overrides a stylesheet declaration on the same property.
+  // Common source of hard-to-debug style issues in React components.
+  report.inlineStyleConflicts = [];
+  const elementsWithInlineStyles = Array.from(
+    document.querySelectorAll('[style]')
+  ).slice(0, 100);
+
+  for (const el of elementsWithInlineStyles) {
+    const inlineProps = {};
+    for (let i = 0; i < el.style.length; i++) {
+      const prop = el.style.item(i);
+      inlineProps[prop] = el.style.getPropertyValue(prop);
+    }
+
+    for (const { selector, declarations, source } of allRules) {
+      let matches = false;
+      try { matches = el.matches(selector); } catch { continue; }
+      if (!matches) continue;
+
+      for (const prop of Object.keys(inlineProps)) {
+        const sheetValue = declarations.getPropertyValue(prop);
+        if (!sheetValue || sheetValue === inlineProps[prop]) continue;
+
+        const tag = el.tagName.toLowerCase();
+        const id = el.id ? '#' + el.id : '';
+        const cls = el.className && typeof el.className === 'string'
+          ? '.' + el.className.trim().split(/\\s+/).slice(0, 2).join('.')
+          : '';
+        const isReactEl = Object.keys(el).some(k =>
+          k.startsWith('__reactFiber') || k.startsWith('__reactProps')
+        );
+
+        report.inlineStyleConflicts.push({
+          element: tag + id + cls,
+          property: prop,
+          inlineValue: inlineProps[prop],
+          stylesheetValue: sheetValue,
+          stylesheetSource: source.split('/').pop(),
+          selector,
+          isReactComponent: isReactEl,
+          description: \`React inline style overrides stylesheet on <\${tag + id + cls}>: "\${prop}: \${inlineProps[prop]}" (inline) wins over "\${prop}: \${sheetValue}" from \${source.split('/').pop()}\`,
+        });
+        report.summary.inlineConflicts++;
+      }
+    }
+  }
+
+  return JSON.stringify(report);
+}
+`;
+
+/**
+ * Parse the raw JSON string result from CSS_ANALYSIS_SCRIPT into bug entries.
+ *
+ * @param {string} rawResult - JSON string returned by evaluate_script
+ * @param {string} url - URL that was analyzed
+ * @returns {object[]} Array of bug-report-compatible error objects
+ */
+export function parseCssAnalysisResult(rawResult, url) {
+  let data;
+  try {
+    const str = typeof rawResult === 'string' ? rawResult : JSON.stringify(rawResult);
+    data = JSON.parse(str);
+    // Detect double-encoding: if the result is still a string after first parse, unwrap once more
+    if (typeof data === 'string') {
+      logger.warn('[ARGUS] css-analyzer: double-encoded JSON detected — unwrapping');
+      data = JSON.parse(data);
+    }
+  } catch {
+    return [{
+      type: 'css_analysis_error',
+      message: 'CSS analysis script failed to return valid JSON',
+      severity: 'info',
+      url,
+    }];
+  }
+
+  const bugs = [];
+
+  // ── Overridden properties ──────────────────────────────────────────────────
+  for (const override of (data.overriddenProperties ?? [])) {
+    // Only report if there are many overrides or !important is involved
+    if (override.overrideCount < 2) continue;
+
+    const severity = override.hasImportant ? 'warning' : 'info';
+    const sources = [...new Set(override.declarations.map(d => d.source.split('/').pop()))].join(', ');
+    bugs.push({
+      type: 'css_override',
+      element: override.element,
+      property: override.property,
+      overrideCount: override.overrideCount,
+      hasImportant: override.hasImportant,
+      message: `CSS override: "${override.property}" declared ${override.overrideCount}x on <${override.element}>${override.hasImportant ? ' — includes !important' : ''} (sources: ${sources})`,
+      declarations: override.declarations,
+      severity,
+      url,
+    });
+  }
+
+  // ── Unused rules ──────────────────────────────────────────────────────────
+  // Only report if there are a notable number — a few unused rules is normal
+  const unusedCount = (data.unusedRules ?? []).length;
+  if (unusedCount > 10) {
+    bugs.push({
+      type: 'css_unused_rules',
+      count: unusedCount,
+      message: `${unusedCount} CSS rules matched no elements on this page — possible dead styles or wrong component loaded`,
+      examples: (data.unusedRules ?? []).slice(0, 5).map(r => r.selector),
+      severity: unusedCount > 50 ? 'warning' : 'info',
+      url,
+    });
+  }
+
+  // ── Component leaks ───────────────────────────────────────────────────────
+  for (const leak of (data.componentLeaks ?? [])) {
+    bugs.push({
+      type: 'css_component_leak',
+      selector: leak.selector,
+      componentHint: leak.componentHint,
+      source: leak.foundInSource,
+      message: leak.description,
+      severity: 'warning',
+      url,
+    });
+  }
+
+  // ── React inline style conflicts ──────────────────────────────────────────
+  for (const conflict of (data.inlineStyleConflicts ?? [])) {
+    bugs.push({
+      type: 'react_inline_style_conflict',
+      element: conflict.element,
+      property: conflict.property,
+      inlineValue: conflict.inlineValue,
+      stylesheetValue: conflict.stylesheetValue,
+      source: conflict.stylesheetSource,
+      isReactComponent: conflict.isReactComponent,
+      message: conflict.description,
+      severity: 'warning',
+      url,
+    });
+  }
+
+  // ── CSS Modules info ───────────────────────────────────────────────────────
+  if (data.cssModulesDetected) {
+    bugs.push({
+      type: 'css_modules_detected',
+      components: data.cssModulesComponents ?? [],
+      message: `CSS Modules detected — ${(data.cssModulesComponents ?? []).length} scoped component(s): ${(data.cssModulesComponents ?? []).join(', ')}. BEM leak detection skipped for hashed selectors.`,
+      severity: 'info',
+      url,
+    });
+  }
+
+  // ── Summary entry ─────────────────────────────────────────────────────────
+  if (data.summary) {
+    const parts = [
+      `${data.summary.totalRules} total rules`,
+      `${data.summary.appliedRules} applied`,
+      `${data.summary.unusedRules} unused`,
+      `${data.summary.overrides} cascade overrides`,
+      `${data.summary.leaks} component leaks`,
+      `${data.summary.inlineConflicts ?? 0} inline style conflicts`,
+    ];
+    bugs.push({
+      type: 'css_summary',
+      message: `CSS analysis (${data.cssModulesDetected ? 'CSS Modules + ' : ''}${data.scssSourceFiles?.length ? 'SCSS' : 'CSS'}): ${parts.join(', ')}`,
+      severity: 'info',
+      url,
+      summary: data.summary,
+      cssModulesDetected: data.cssModulesDetected,
+      cssModulesComponents: data.cssModulesComponents,
+      scssSourceFiles: data.scssSourceFiles,
+      stylesheetSources: data.stylesheetSources,
+    });
+  }
+
+  return bugs;
+}

package/src/utils/diff.js

@@ -0,0 +1,189 @@
+/**
+ * ARGUS Diff Utilities
+ *
+ * Pixel-level screenshot comparison using pixelmatch + pngjs.
+ * Also provides DOM structural diff utilities.
+ */
+
+import { PNG } from 'pngjs';
+import pixelmatch from 'pixelmatch';
+import fs from 'fs';
+// Import shared URL normalizer so diffNetworkRequests uses the same ID-collapsing
+// strategy as analyzeApiFrequency — previously each module had its own private normalizer,
+// causing the same endpoint to be keyed differently in frequency vs diff analysis.
+import { normalizeApiUrl } from './api-frequency.js';
+import { childLogger } from './logger.js';
+
+const logger = childLogger('diff');
+
+/**
+ * Compare two screenshot files pixel-by-pixel.
+ *
+ * @param {string} pathA - Absolute path to first screenshot (PNG)
+ * @param {string} pathB - Absolute path to second screenshot (PNG)
+ * @param {string} diffOutputPath - Where to write the diff overlay image
+ * @param {number} threshold - Pixel sensitivity 0–1 (default 0.1)
+ * @returns {{ diffPixels: number, diffPercent: number, totalPixels: number }}
+ */
+export async function compareScreenshots(pathA, pathB, diffOutputPath, threshold = 0.1) {
+  // Wrap file I/O in try/catch — readFileSync throws on missing/invalid files,
+  // PNG.sync.read throws on corrupt data; both would crash the entire report pipeline.
+  let imgA, imgB;
+  try {
+    imgA = PNG.sync.read(fs.readFileSync(pathA));
+    imgB = PNG.sync.read(fs.readFileSync(pathB));
+  } catch (err) {
+    throw new Error(`compareScreenshots: failed to read screenshot files — ${err.message} (pathA: ${pathA}, pathB: ${pathB})`);
+  }
+
+  // Ensure same dimensions — use the smaller of the two
+  const width = Math.min(imgA.width, imgB.width);
+  const height = Math.min(imgA.height, imgB.height);
+
+  if (width === 0 || height === 0) {
+    throw new Error(`compareScreenshots: one or both screenshots have zero dimensions (${imgA.width}×${imgA.height} vs ${imgB.width}×${imgB.height}) — screenshot capture likely failed`);
+  }
+
+  // Crop both images to matching dimensions
+  const croppedA = cropPNG(imgA, width, height);
+  const croppedB = cropPNG(imgB, width, height);
+
+  const diff = new PNG({ width, height });
+
+  const diffPixels = pixelmatch(
+    croppedA.data,
+    croppedB.data,
+    diff.data,
+    width,
+    height,
+    { threshold }
+  );
+
+  // Don't let a bad output path crash the report — diff images are optional visuals.
+  try {
+    fs.writeFileSync(diffOutputPath, PNG.sync.write(diff));
+  } catch (err) {
+    logger.warn(`[ARGUS] compareScreenshots: could not write diff image to ${diffOutputPath} — ${err.message}`);
+  }
+
+  const totalPixels = width * height;
+  // Guard against division by zero if both images are 0×0 pixels.
+  const diffPercent = totalPixels > 0 ? (diffPixels / totalPixels) * 100 : 0;
+
+  return { diffPixels, diffPercent, totalPixels, width, height };
+}
+
+/**
+ * Crop a PNG object to the given width/height (top-left origin).
+ * @param {PNG} png
+ * @param {number} width
+ * @param {number} height
+ * @returns {PNG}
+ */
+function cropPNG(png, width, height) {
+  if (png.width === width && png.height === height) return png;
+  const cropped = new PNG({ width, height });
+  PNG.bitblt(png, cropped, 0, 0, width, height, 0, 0);
+  return cropped;
+}
+
+/**
+ * Perform a structural diff on two serialized DOM trees.
+ * Returns an array of difference objects.
+ *
+ * @param {string} domA - Serialized DOM string from take_snapshot (env A)
+ * @param {string} domB - Serialized DOM string from take_snapshot (env B)
+ * @returns {object[]} Array of diff entries
+ */
+export function diffDomSnapshots(domA, domB) {
+  if (typeof domA !== 'string' || typeof domB !== 'string') {
+    logger.warn('[ARGUS] diffDomSnapshots: non-string argument — one or both DOM snapshots may be missing');
+    return [];
+  }
+  const diffs = [];
+
+  // Parse tag/attribute counts as a lightweight structural fingerprint
+  const countTags = (dom) => {
+    const counts = {};
+    const regex = /<([a-zA-Z][a-zA-Z0-9-]*)[^>]*>/g;
+    let m;
+    while ((m = regex.exec(dom)) !== null) {
+      const tag = m[1].toLowerCase();
+      counts[tag] = (counts[tag] ?? 0) + 1;
+    }
+    return counts;
+  };
+
+  const tagsA = countTags(domA);
+  const tagsB = countTags(domB);
+  const allTags = new Set([...Object.keys(tagsA), ...Object.keys(tagsB)]);
+
+  for (const tag of allTags) {
+    const countA = tagsA[tag] ?? 0;
+    const countB = tagsB[tag] ?? 0;
+    if (countA !== countB) {
+      diffs.push({
+        type: 'element_count_change',
+        tag,
+        countA,
+        countB,
+        delta: countB - countA,
+        description: `<${tag}>: ${countA} in dev → ${countB} in staging (delta: ${countB - countA > 0 ? '+' : ''}${countB - countA})`,
+      });
+    }
+  }
+
+  return diffs;
+}
+
+/**
+ * Diff two arrays of network requests by URL + status.
+ * Returns added (in B not in A), removed (in A not in B), and changed (same URL, different status).
+ *
+ * @param {object[]} reqsA - Network requests from env A
+ * @param {object[]} reqsB - Network requests from env B
+ * @returns {{ added: object[], removed: object[], changed: object[] }}
+ */
+export function diffNetworkRequests(reqsA, reqsB) {
+  // Use the shared normalizeApiUrl (from api-frequency.js) which collapses numeric
+  // and UUID path segments to /{id}. The previous private normalizeUrl didn't do this,
+  // so /api/123 and /api/456 were treated as different endpoints in diffs but the same
+  // endpoint in frequency analysis — inconsistent findings across modules.
+  // Object.fromEntries last-write-wins — if two requests normalize to the same key
+  // (e.g. /api/123 and /api/456 → /api/{id}), the first request object is silently dropped.
+  // Use first-entry-wins so the earlier request (usually the most representative) is kept.
+  function buildRequestMap(reqs) {
+    const map = {};
+    for (const r of (reqs ?? [])) {
+      const key = normalizeApiUrl(r.url ?? '');
+      if (!Object.prototype.hasOwnProperty.call(map, key)) map[key] = r;
+    }
+    return map;
+  }
+  const mapA = buildRequestMap(reqsA);
+  const mapB = buildRequestMap(reqsB);
+
+  const urlsA = new Set(Object.keys(mapA));
+  const urlsB = new Set(Object.keys(mapB));
+
+  const added = [...urlsB].filter(u => !urlsA.has(u)).map(u => mapB[u]);
+  const removed = [...urlsA].filter(u => !urlsB.has(u)).map(u => mapA[u]);
+  const changed = [...urlsA]
+    .filter(u => urlsB.has(u) && mapA[u].status !== mapB[u].status)
+    .map(u => ({ url: u, statusA: mapA[u].status, statusB: mapB[u].status }));
+
+  return { added, removed, changed };
+}
+
+/**
+ * Diff console messages: find errors in B (staging) that are not in A (dev).
+ * These are new regressions introduced in staging.
+ *
+ * @param {object[]} msgsA
+ * @param {object[]} msgsB
+ * @returns {object[]} New errors in B not present in A
+ */
+export function diffConsoleMessages(msgsA, msgsB) {
+  const textSetA = new Set((msgsA ?? []).filter(m => m.level === 'error').map(m => m.text ?? m.message));
+  return (msgsB ?? []).filter(m => m.level === 'error' && !textSetA.has(m.text ?? m.message));
+}

package/src/utils/flakiness-detector.js

@@ -0,0 +1,82 @@
+/**
+ * Argus v3 Phase B4 — Flakiness detection
+ *
+ * Each route is crawled twice. Findings present in both runs are "confirmed"
+ * (severity unchanged). Findings that appear in only one run are "flaky" —
+ * severity is downgraded to 'info' and flaky: true is set so the Slack digest
+ * can label them visually. This filters out timing-sensitive false positives
+ * (race conditions, GC-dependent heap readings, one-off network blips).
+ *
+ * Finding key: same scheme as baseline-manager — type::message[:100]::status
+ */
+
+// Exported so baseline-manager.js uses the same normalization (trim + collapse
+// whitespace). Previously each module had its own private findingKey() with different
+// whitespace handling, so the same finding could be new in baselines but confirmed in
+// flakiness, producing inconsistent cross-module annotation.
+export function findingKey(finding) {
+  // Normalize whitespace before truncating — same finding with minor formatting
+  // differences (extra spaces, newlines) between run1 and run2 would produce different
+  // keys and be incorrectly classified as flaky.
+  const msg = (finding.message ?? '').trim().replace(/\s+/g, ' ').slice(0, 100);
+  const status = finding.status != null ? '::' + finding.status : '';
+  return `${finding.type}::${msg}${status}`;
+}
+
+/**
+ * Merge two crawl results for the same route.
+ *
+ * - Findings present in both runs → confirmed (flaky: false, original severity kept)
+ * - Findings present in only one run → flaky (flaky: true, severity → 'info')
+ *
+ * The returned result uses run2's screenshot and responsiveScreenshots (more recent).
+ *
+ * @param {object} run1 - First crawl result from crawlRoute + analysis engines
+ * @param {object} run2 - Second crawl result for the same route
+ * @returns {object} Merged result with confirmed + flaky findings combined
+ */
+export function mergeRunResults(run1, run2) {
+  // Validate inputs — accessing .errors on undefined throws a cryptic TypeError.
+  if (!run1 || !Array.isArray(run1.errors)) {
+    throw new TypeError('mergeRunResults: run1.errors must be an array');
+  }
+  if (!run2 || !Array.isArray(run2.errors)) {
+    throw new TypeError('mergeRunResults: run2.errors must be an array');
+  }
+
+  const keys1 = new Map(run1.errors.map(f => [findingKey(f), f]));
+  const keys2 = new Set(run2.errors.map(findingKey));
+
+  const confirmed = [];
+  const flaky = [];
+
+  for (const f of run1.errors) {
+    if (keys2.has(findingKey(f))) {
+      confirmed.push({ ...f, flaky: false });
+    } else {
+      flaky.push({ ...f, severity: 'info', flaky: true });
+    }
+  }
+
+  // Build O(1) index map to avoid O(n²) findIndex scan on large confirmed arrays
+  const confirmedIndexByKey = new Map(confirmed.map((c, i) => [findingKey(c), i]));
+
+  for (const f of run2.errors) {
+    const key = findingKey(f);
+    if (keys1.has(key)) {
+      // Prefer run2's version of confirmed findings — run2 is more recent and
+      // may have updated metadata. Replace run1's copy in the confirmed array.
+      const idx = confirmedIndexByKey.get(key) ?? -1;
+      if (idx !== -1) confirmed[idx] = { ...f, flaky: false };
+    } else {
+      flaky.push({ ...f, severity: 'info', flaky: true });
+    }
+  }
+
+  return {
+    ...run2,
+    errors: [...confirmed, ...flaky],
+    responsiveScreenshots: run2.responsiveScreenshots ?? run1.responsiveScreenshots,
+    screenshot: run2.screenshot ?? run1.screenshot,
+  };
+}