argusqa-os 9.6.5 → 9.7.3

package/src/mcp-server.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Argus MCP Server (v9.6.5)
+ * Argus MCP Server (v9.6.6)
  *
  * Exposes Argus as an MCP server so Claude (or any MCP client) can call
  * argus_audit, argus_audit_full, argus_compare, argus_last_report, and
@@ -33,7 +33,7 @@ import { CdpBrowserAdapter }                  from './adapters/browser.js';
 import { getFigmaFrame }                      from './adapters/figma.js';
 import { analyzeDesignFidelity }             from './utils/design-fidelity-analyzer.js';
 import { analyzeVisualRegression }           from './utils/visual-diff-analyzer.js';
-import { parsePrUrl, fetchPrFiles, mapFilesToRoutes } from './utils/pr-diff-analyzer.js';
+import { fetchPrFiles, mapFilesToRoutes } from './utils/pr-diff-analyzer.js';
 
 const REPORTS_DIR = path.resolve(process.cwd(), 'reports');
 
@@ -447,7 +447,7 @@ async function handleLastReport() {
 // ── Server bootstrap ──────────────────────────────────────────────────────────
 
 const server = new Server(
-  { name: 'argus', version: '9.6.5' },
+  { name: 'argus', version: '9.6.6' },
   { capabilities: { tools: {} } },
 );
 

package/src/orchestration/orchestrator.js

@@ -20,10 +20,11 @@ import { SECURITY_ANALYSIS_SCRIPT, parseSecurityAnalysisResult, analyzeSecurityC
 import { CONTENT_ANALYSIS_SCRIPT, parseContentAnalysisResult }          from '../utils/content-analyzer.js';
 import { runLoginFlow, saveSession, restoreSession, hasSession, refreshSession } from '../utils/session-manager.js';
 import { mergeRunResults }                                               from '../utils/flakiness-detector.js';
-import { runAllFlows, normalizeArray, waitForSelector }                  from '../utils/flow-runner.js';
+import { runAllFlows, waitForSelector }                                  from '../utils/flow-runner.js';
 import { analyzeApiFrequency }                                           from '../utils/api-frequency.js';
 import { slugify }                                                       from '../utils/slug.js';
 import { unwrapEval, createMcpClient }                                   from '../utils/mcp-client.js';
+import { parseConsoleMsgResponse }                                       from '../utils/mcp-parsers.js';
 import { CdpBrowserAdapter }                                             from '../adapters/browser.js';
 import { getFigmaFrame }                                                 from '../adapters/figma.js';
 import { chunkArray }                                                    from '../utils/parallel-crawler.js';
@@ -435,9 +436,9 @@ export async function crawlRouteCheap(route, baseUrl, mcp) {
   const consoleBaseline = (await browser.listConsole().catch(() => [])).length;
   const baselineNetList = await browser.listNetwork().catch(() => []);
   const networkMaxReqId = baselineNetList.reduce((max, r) => Math.max(max, r._reqid ?? 0), 0);
-  // listConsoleRaw returns raw MCP response — normalizeArray required before .length
+  // listConsoleRaw returns markdown text ("msgid=N [issue] text") — parse like console messages
   const issuesBaselineRaw = await browser.listConsoleRaw({ types: ['issue'] }).catch(() => null);
-  const issuesBaseline    = normalizeArray(issuesBaselineRaw).length;
+  const issuesBaseline    = parseConsoleMsgResponse(issuesBaselineRaw).length;
 
   // 1. Navigate
   await browser.navigate(url);
@@ -710,11 +711,12 @@ export async function crawlRouteCheap(route, baseUrl, mcp) {
     logger.warn(`[ARGUS] Content analysis skipped for ${url}: ${err.message}`);
   }
 
-  // 9e. Chrome DevTools Issues panel
+  // 9e. Chrome DevTools Issues panel — same reset-per-navigation guard as console (D5)
   try {
-    const issueRaw = await browser.listConsoleRaw({ types: ['issue'] });
-    const issues   = normalizeArray(issueRaw).slice(issuesBaseline);
-    result.errors.push(...parseIssues(issues, url, route.critical));
+    const issueRaw  = await browser.listConsoleRaw({ types: ['issue'] });
+    const allIssues = parseConsoleMsgResponse(issueRaw);
+    const issuesSliceAt = allIssues.length > issuesBaseline ? issuesBaseline : 0;
+    result.errors.push(...parseIssues(allIssues.slice(issuesSliceAt), url, route.critical));
   } catch (err) {
     logger.warn(`[ARGUS] Issues analysis skipped for ${url}: ${err.message}`);
   }

package/src/orchestration/report-processor.js

@@ -13,6 +13,8 @@ import path from 'path';
 import { childLogger } from '../utils/logger.js';
 import { applyOverrides }                                                  from '../utils/severity-overrides.js';
 import { loadBaseline, saveBaseline, applyBaseline, appendTrend, getCurrentBranch } from '../utils/baseline-manager.js';
+import { loadRunHistory, recordRunHistory, applyNoiseFilter }              from '../utils/noise-filter.js';
+import { getRecentChanges, linkRootCauses }                                from '../utils/root-cause-linker.js';
 
 const logger = childLogger('report-processor');
 
@@ -104,6 +106,29 @@ export async function processReport(report, { outputDir, severityOverrides }) {
     logger.info('[ARGUS] First run — no baseline to compare; all findings treated as new');
   }
 
+  // 3a. Intelligent baseline filtering — downgrade cross-run flip-flopping findings
+  //     to info. Best-effort; disable with ARGUS_NOISE_FILTER=0.
+  const historyPath = path.join(outputDir, 'baselines', `${safeBranch}-history.json`);
+  if (process.env.ARGUS_NOISE_FILTER !== '0') {
+    try {
+      const history = loadRunHistory(historyPath);
+      const { noisyCount } = applyNoiseFilter(report, history);
+      if (noisyCount > 0) rebuildSummary(report); // downgrades change severity counts
+    } catch (err) {
+      logger.warn(`[ARGUS] Noise filter skipped: ${err.message}`);
+    }
+  }
+
+  // 3b. Root cause linking — annotate new findings with recent git changes that
+  //     map to their route. Best-effort; disable with ARGUS_ROOT_CAUSE=0.
+  if (process.env.ARGUS_ROOT_CAUSE !== '0') {
+    try {
+      linkRootCauses(report, getRecentChanges());
+    } catch (err) {
+      logger.warn(`[ARGUS] Root cause linking skipped: ${err.message}`);
+    }
+  }
+
   // 4. Write JSON report
   const timestamp  = new Date().toISOString().replace(/[:.]/g, '-');
   const reportPath = path.join(outputDir, `error-report-${timestamp}.json`);
@@ -115,8 +140,15 @@ export async function processReport(report, { outputDir, severityOverrides }) {
   }
   logger.info(`[ARGUS] Report written: ${reportPath}`);
 
-  // 5. Persist baseline + append trend entry
+  // 5. Persist baseline + run history + append trend entry
   saveBaseline(baselinePath, report);
+  if (process.env.ARGUS_NOISE_FILTER !== '0') {
+    try {
+      recordRunHistory(historyPath, report);
+    } catch (err) {
+      logger.warn(`[ARGUS] Run history write skipped: ${err.message}`);
+    }
+  }
   appendTrend(trendsPath, {
     runAt:                report.generatedAt,
     baseUrl:              report.baseUrl,

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

@@ -1,5 +1,5 @@
 /**
- * ARGUS Deep Accessibility Analyzer (Sprint 4 — A12)
+ * ARGUS Deep Accessibility Analyzer (A12)
  *
  * Extends Argus accessibility coverage via two mechanisms:
  *

package/src/utils/design-fidelity-analyzer.js

@@ -1,5 +1,5 @@
 /**
- * ARGUS Design Fidelity Analyzer (Sprint 2 — D9: Design Fidelity)
+ * ARGUS Design Fidelity Analyzer (D9: Design Fidelity)
  *
  * Compares a live page's computed CSS against every property extracted by
  * src/adapters/figma.js. Requires pre-fetched figmaData — analysis is skipped

package/src/utils/flow-runner.js

@@ -102,12 +102,26 @@ export async function resolveUidForSelector(browser, selector) {
   const fence = text.match(/```(?:json|text)?\s*([\s\S]*?)\s*```/);
   if (fence) text = fence[1];
 
+  // Pass 1 — exact accessible-name match across ALL identifiers before any
+  // substring matching. Substring matches can hit unrelated nodes whose text
+  // merely mentions the identifier (e.g. a paragraph documenting "#drag-source"
+  // matches the id "drag-source" and wins over the real element's text node).
   for (const identifier of identifiers) {
     const esc = identifier.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    // Current snapshot format: "uid=N_M role "accessible name" [attrs]"
-    // uid precedes the role and accessible name; MCP tools expect just the N_M part (no "uid=" prefix).
     // Prefer interactive element lines (combobox, button, etc.) over StaticText label
     // nodes — both may share the same accessible name (e.g. a <label> and its <select>).
+    const e1 = text.match(new RegExp(`uid=([^\\s]+)\\s+(?!StaticText)[^\\n]*"${esc}"`, 'm'));
+    if (e1) return e1[1];
+    const e1b = text.match(new RegExp(`uid=([^\\s]+)[^\\n]*"${esc}"`, 'm'));
+    if (e1b) return e1b[1];
+  }
+
+  // Pass 2 — substring fallback (accessible names that embed the identifier,
+  // e.g. truncated textContent or label text with surrounding punctuation).
+  for (const identifier of identifiers) {
+    const esc = identifier.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // Current snapshot format: "uid=N_M role "accessible name" [attrs]"
+    // uid precedes the role and accessible name; MCP tools expect just the N_M part (no "uid=" prefix).
     const m1 = text.match(new RegExp(`uid=([^\\s]+)\\s+(?!StaticText)[^\\n]*"[^"]*${esc}`, 'm'));
     if (m1) return m1[1];
     // Fallback: accept StaticText nodes (e.g. draggable divs whose only a11y node is text)

package/src/utils/font-analyzer.js

@@ -1,5 +1,5 @@
 /**
- * ARGUS Font Loading Analyzer (Sprint 5c — A10)
+ * ARGUS Font Loading Analyzer (A10)
  *
  * Detects web font performance and reliability issues that cause invisible
  * text (FOIT), layout shifts (FOUT/CLS), or deliver fonts in suboptimal formats.

package/src/utils/form-analyzer.js

@@ -1,5 +1,5 @@
 /**
- * ARGUS Form Validation Analyzer (Sprint 5d — A11)
+ * ARGUS Form Validation Analyzer (A11)
  *
  * Detects accessibility and security gaps in HTML forms — one of the most
  * commonly broken areas in web apps.

package/src/utils/har-recorder.js

@@ -1,5 +1,5 @@
 /**
- * ARGUS HAR Network Baseline Recorder (Sprint 5 — N1)
+ * ARGUS HAR Network Baseline Recorder (N1)
  *
  * Records all network requests made during a page load as a HAR-style
  * baseline. On first run, saves the baseline. On subsequent runs, diffs

package/src/utils/issues-analyzer.js

@@ -23,7 +23,7 @@
  *   analyzeIssues(browser, url, isCritical) — standalone navigator for direct harness use.
  */
 
-import { normalizeArray } from './flow-runner.js';
+import { parseConsoleMsgResponse } from './mcp-parsers.js';
 
 // ── Issue classifiers ─────────────────────────────────────────────────────────
 
@@ -112,7 +112,8 @@ function classifyIssue(issue, url, isCritical) {
  * Parse a pre-fetched, already-baseline-sliced issues array into findings.
  * Pure function — used by crawlRouteCheap after the D5 baseline-slice.
  *
- * @param {object[]} issues    - Issues from list_console_messages({ types: ['issue'] })
+ * @param {object[]} issues    - Parsed issue objects ({ level, text }) from
+ *                               parseConsoleMsgResponse(list_console_messages({ types: ['issue'] }))
  * @param {string}   url       - Page URL (used as finding context)
  * @param {boolean}  isCritical
  * @returns {object[]}
@@ -127,11 +128,12 @@ export function parseIssues(issues, url, isCritical = false) {
 }
 
 /**
- * Standalone issues analyzer — navigates to a URL, baselines the current
- * Issues count, queries the panel after load, and returns findings.
+ * Standalone issues analyzer — navigates to a URL, queries the Issues
+ * panel after load, and returns findings.
  *
- * Used by the test harness and any standalone caller. Baselines before
- * navigation (D5 pattern) so pre-existing issues from prior pages are excluded.
+ * Used by the test harness and any standalone caller. No baseline slice is
+ * needed: list_console_messages resets per navigation, so the post-navigation
+ * response contains only the current page's issues.
  *
  * @param {object}  browser
  * @param {string}  url
@@ -141,14 +143,6 @@ export function parseIssues(issues, url, isCritical = false) {
 export async function analyzeIssues(browser, url, isCritical = false) {
   const findings = [];
 
-  let baseline = 0;
-  try {
-    const priorRaw = await browser.listConsoleRaw({ types: ['issue'], includePreservedMessages: true });
-    baseline = normalizeArray(priorRaw).length;
-  } catch {
-    // Issues API may not be available — baseline stays 0
-  }
-
   try {
     await browser.navigate(url);
     await new Promise(r => setTimeout(r, 1000));
@@ -157,11 +151,10 @@ export async function analyzeIssues(browser, url, isCritical = false) {
   }
 
   try {
-    const raw    = await browser.listConsoleRaw({
-      types: ['issue'],
-      includePreservedMessages: true,
-    });
-    const issues = normalizeArray(raw).slice(baseline);
+    // Response is markdown text ("msgid=N [issue] text") — same format as
+    // console messages. parseConsoleMsgResponse extracts { level, text }.
+    const raw    = await browser.listConsoleRaw({ types: ['issue'] });
+    const issues = parseConsoleMsgResponse(raw);
     findings.push(...parseIssues(issues, url, isCritical));
   } catch {
     // Issues API not available in this chrome-devtools-mcp build — silent skip

package/src/utils/motion-analyzer.js

@@ -1,5 +1,5 @@
 /**
- * ARGUS Motion & Animation Accessibility Analyzer (Sprint 5b — A9)
+ * ARGUS Motion & Animation Accessibility Analyzer (A9)
  *
  * Detects pages that trigger motion/animation without respecting the user's
  * `prefers-reduced-motion` OS preference — a WCAG 2.1 SC 2.3.3 (AAA) violation

package/src/utils/noise-filter.js

@@ -0,0 +1,159 @@
+/**
+ * Intelligent Baseline Filtering — cross-run noise classifier.
+ *
+ * Pure algorithmic false-positive filter: no external API, no per-run cost.
+ * Tracks which finding keys appeared on which routes across the last N runs
+ * (reports/baselines/<branch>-history.json) and flags findings that flip-flop
+ * between present and absent as "noisy". Noisy findings are downgraded to
+ * severity "info" (never suppressed — visibility is kept) and annotated with
+ * `noisy: true`, `noiseScore`, and `originalSeverity`.
+ *
+ * Distinct from flakiness-detector.js (B4), which compares two crawls WITHIN
+ * one run. This module classifies across run HISTORY, catching findings that
+ * are stable within a run but unstable between runs (timing-dependent ads,
+ * third-party scripts, A/B-tested content).
+ *
+ * Disable with ARGUS_NOISE_FILTER=0.
+ */
+
+import fs   from 'fs';
+import path from 'path';
+import { findingKey }  from './flakiness-detector.js';
+import { childLogger } from './logger.js';
+
+const logger = childLogger('noise-filter');
+
+/** Minimum recorded runs for a route before its findings can be classified noisy. */
+export const NOISE_MIN_RUNS = 4;
+/** Presence-flip ratio (transitions / (runs - 1)) at or above which a finding is noisy. */
+export const NOISE_FLIP_THRESHOLD = 0.4;
+/** Maximum run entries kept in the history file. */
+export const MAX_HISTORY_RUNS = 20;
+
+/**
+ * Load run history from disk. Returns [] when the file is absent or corrupt.
+ *
+ * @param {string} historyFile
+ * @returns {Array<{ runAt: string, routes: Record<string, string[]> }>}
+ */
+export function loadRunHistory(historyFile) {
+  if (!fs.existsSync(historyFile)) return [];
+  try {
+    const parsed = JSON.parse(fs.readFileSync(historyFile, 'utf8'));
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Append the current report's finding keys as one run entry, capped at maxRuns.
+ * Atomic write (tmp + rename) — same pattern as baseline-manager.
+ *
+ * @param {string} historyFile
+ * @param {object} report  - { generatedAt, routes: [{ url, errors }] }
+ * @param {number} [maxRuns]
+ */
+export function recordRunHistory(historyFile, report, maxRuns = MAX_HISTORY_RUNS) {
+  const dir = path.dirname(historyFile);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const entry = { runAt: report.generatedAt ?? new Date().toISOString(), routes: {} };
+  for (const routeResult of (report.routes ?? [])) {
+    entry.routes[routeResult.url] = (routeResult.errors ?? []).map(findingKey);
+  }
+
+  let history = loadRunHistory(historyFile);
+  history.push(entry);
+  if (history.length > maxRuns) history = history.slice(-maxRuns);
+
+  const tmp = `${historyFile}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(history, null, 2)); // lgtm[js/network-data-to-file] — intentional: Argus persists crawl history to a local baseline file by design
+  fs.renameSync(tmp, historyFile);
+}
+
+/**
+ * Compute per-finding noise scores from run history.
+ *
+ * For every route, builds a presence series per finding key across the runs in
+ * which that route was crawled, then scores `transitions / (runs - 1)` — 0 for
+ * a finding that is always present (or always absent), 1 for one that flips on
+ * every consecutive run pair.
+ *
+ * @param {Array<{ routes: Record<string, string[]> }>} history
+ * @returns {Map<string, { score: number, runs: number, transitions: number }>}
+ *          keyed by `${url}::${findingKey}`
+ */
+export function computeNoiseScores(history) {
+  const scores = new Map();
+  if (!Array.isArray(history) || history.length < 2) return scores;
+
+  // url → array of Set(keys), one per run that crawled the url (run order preserved)
+  const routeSeries = new Map();
+  for (const run of history) {
+    for (const [url, keys] of Object.entries(run.routes ?? {})) {
+      if (!routeSeries.has(url)) routeSeries.set(url, []);
+      routeSeries.get(url).push(new Set(keys));
+    }
+  }
+
+  for (const [url, series] of routeSeries) {
+    if (series.length < 2) continue;
+    const allKeys = new Set();
+    for (const runKeys of series) for (const k of runKeys) allKeys.add(k);
+
+    for (const key of allKeys) {
+      let transitions = 0;
+      for (let i = 1; i < series.length; i++) {
+        if (series[i].has(key) !== series[i - 1].has(key)) transitions++;
+      }
+      scores.set(`${url}::${key}`, {
+        score: transitions / (series.length - 1),
+        runs: series.length,
+        transitions,
+      });
+    }
+  }
+  return scores;
+}
+
+/**
+ * Annotate and downgrade noisy findings in the report (mutates in place).
+ *
+ * A finding is noisy when its route has ≥ minRuns of history AND its presence
+ * flip ratio ≥ flipThreshold. Noisy findings get `noisy: true`, `noiseScore`,
+ * `originalSeverity`, and severity downgraded to "info". Caller is responsible
+ * for rebuilding report.summary afterwards.
+ *
+ * @param {object} report
+ * @param {Array}  history  - From loadRunHistory()
+ * @param {object} [opts]
+ * @param {number} [opts.minRuns]
+ * @param {number} [opts.flipThreshold]
+ * @returns {{ noisyCount: number }}
+ */
+export function applyNoiseFilter(report, history, { minRuns = NOISE_MIN_RUNS, flipThreshold = NOISE_FLIP_THRESHOLD } = {}) {
+  const scores = computeNoiseScores(history);
+  let noisyCount = 0;
+  if (scores.size === 0) return { noisyCount };
+
+  for (const routeResult of (report.routes ?? [])) {
+    for (const finding of (routeResult.errors ?? [])) {
+      const entry = scores.get(`${routeResult.url}::${findingKey(finding)}`);
+      if (!entry || entry.runs < minRuns || entry.score < flipThreshold) continue;
+
+      finding.noisy = true;
+      finding.noiseScore = Math.round(entry.score * 100) / 100;
+      if (finding.severity !== 'info') {
+        finding.originalSeverity = finding.severity;
+        finding.severity = 'info';
+      }
+      noisyCount++;
+    }
+  }
+
+  if (noisyCount > 0) {
+    logger.info(`[ARGUS] Noise filter: ${noisyCount} flip-flopping finding(s) downgraded to info`);
+  }
+  return { noisyCount };
+}

package/src/utils/pdf-exporter.js

@@ -0,0 +1,146 @@
+/**
+ * Argus PDF Exporter
+ *
+ * Exports the Argus HTML report as a branded A4 PDF using puppeteer.
+ * puppeteer is an optional peer dependency — install when needed:
+ *   npm install puppeteer
+ *
+ * Usage (programmatic):
+ *   import { exportReportToPdf } from './pdf-exporter.js';
+ *   const pdfPath = await exportReportToPdf('./reports/report.html', './reports/report.pdf');
+ *
+ * Usage (CLI):
+ *   node src/utils/pdf-exporter.js ./reports/report.html ./reports/report.pdf
+ */
+
+import fs   from 'fs';
+import path from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+
+/**
+ * Load puppeteer dynamically so the import failure is a clear runtime error,
+ * not a module load error on startup.
+ *
+ * @returns {Promise<object>} puppeteer default export
+ * @throws {Error} with install instructions if not installed
+ */
+async function loadPuppeteer() {
+  try {
+    return (await import('puppeteer')).default;
+  } catch {
+    throw new Error(
+      'PDF export requires puppeteer:\n' +
+      '  npm install puppeteer\n' +
+      'Then retry.'
+    );
+  }
+}
+
+/**
+ * Export an Argus HTML report to a branded A4 PDF.
+ *
+ * @param {string} htmlPath   - Absolute or relative path to the source HTML report
+ * @param {string} outputPath - Destination PDF file path (written to disk)
+ * @param {{ format?: string, landscape?: boolean, scale?: number }} [options]
+ * @returns {Promise<string>} Resolved outputPath
+ */
+export async function exportReportToPdf(htmlPath, outputPath, options = {}) {
+  const {
+    format    = 'A4',
+    landscape = false,
+    scale     = 1,
+  } = options;
+
+  const resolvedHtml = path.resolve(htmlPath);
+  if (!fs.existsSync(resolvedHtml)) {
+    throw new Error(`HTML report not found: ${resolvedHtml}`);
+  }
+
+  const resolvedOut = path.resolve(outputPath);
+  fs.mkdirSync(path.dirname(resolvedOut), { recursive: true });
+
+  const puppeteer = await loadPuppeteer();
+  const browser   = await puppeteer.launch({ headless: 'new' });
+
+  try {
+    const page = await browser.newPage();
+    await page.setViewport({ width: 1280, height: 900 });
+    await page.goto(pathToFileURL(resolvedHtml).href, { waitUntil: 'networkidle0', timeout: 30_000 });
+
+    await page.pdf({
+      path:            resolvedOut,
+      format,
+      landscape,
+      scale,
+      printBackground: true,
+      margin:          { top: '18mm', right: '14mm', bottom: '18mm', left: '14mm' },
+    });
+  } finally {
+    await browser.close();
+  }
+
+  return resolvedOut;
+}
+
+/**
+ * Navigate to a live URL and export to PDF.
+ *
+ * @param {string} pageUrl    - URL to navigate to before printing
+ * @param {string} outputPath - Destination PDF file path
+ * @param {{ format?: string, landscape?: boolean, scale?: number, waitUntil?: string }} [options]
+ * @returns {Promise<string>}
+ */
+export async function exportPageToPdf(pageUrl, outputPath, options = {}) {
+  const {
+    format    = 'A4',
+    landscape = false,
+    scale     = 1,
+    waitUntil = 'networkidle0',
+  } = options;
+
+  const resolvedOut = path.resolve(outputPath);
+  fs.mkdirSync(path.dirname(resolvedOut), { recursive: true });
+
+  const puppeteer = await loadPuppeteer();
+  const browser   = await puppeteer.launch({ headless: 'new' });
+
+  try {
+    const page = await browser.newPage();
+    await page.setViewport({ width: 1280, height: 900 });
+    await page.goto(pageUrl, { waitUntil, timeout: 30_000 });
+
+    await page.pdf({
+      path:            resolvedOut,
+      format,
+      landscape,
+      scale,
+      printBackground: true,
+      margin:          { top: '18mm', right: '14mm', bottom: '18mm', left: '14mm' },
+    });
+  } finally {
+    await browser.close();
+  }
+
+  return resolvedOut;
+}
+
+// ── CLI entry ─────────────────────────────────────────────────────────────────
+
+if (process.argv[1] === __filename) {
+  const [,, htmlArg, outArg] = process.argv;
+
+  if (!htmlArg || !outArg) {
+    process.stderr.write('Usage: node src/utils/pdf-exporter.js <report.html> <output.pdf>\n');
+    process.exit(1);
+  }
+
+  try {
+    const out = await exportReportToPdf(htmlArg, outArg);
+    process.stdout.write(`✓ PDF written: ${out}\n`);
+  } catch (err) {
+    process.stderr.write(`✗ ${err.message}\n`);
+    process.exit(1);
+  }
+}

package/src/utils/pr-diff-analyzer.js

@@ -81,8 +81,9 @@ const EXCLUDED_PATTERNS = [
 /**
  * Patterns that indicate an infrastructure-level file whose change can affect
  * every route — framework configs, root layouts, global stylesheets, package.json.
+ * Exported for reuse by root-cause-linker.js (MIT).
  */
-const INFRA_PATTERNS = [
+export const INFRA_PATTERNS = [
   /next\.config\./i,
   /vite\.config\./i,
   /tailwind\.config\./i,