argusqa-os 9.6.6 → 9.7.4

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

@@ -7,8 +7,16 @@
  *
  * Pure functions + one async fetch — no Chrome, no MCP, no AI verdict.
  * AI verdict logic ships separately in the private argus-pro repo.
+ *
+ * This module is imported by the MCP server — nothing here may write to
+ * stdout (reserved for JSON-RPC). CI annotations are emitted by the CLI
+ * entry point (src/cli/pr-validate.js), which owns stdout.
  */
 
+import { childLogger } from './logger.js';
+
+const logger = childLogger('pr-diff-analyzer');
+
 /**
  * Parse a GitHub PR URL into its owner/repo/prNumber components.
  *
@@ -59,7 +67,7 @@ export async function fetchPrFiles(prUrl, githubToken) {
   }
 
   if (allFiles.length >= 300) {
-    console.log('::warning::PR has 300+ changed files — Argus analyzed the first 300. Routes affected by later files may be missed.');
+    logger.warn('[ARGUS] PR has 300+ changed files — Argus analyzed the first 300. Routes affected by later files may be missed.');
   }
 
   return allFiles;
@@ -81,8 +89,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,

package/src/utils/root-cause-linker.js

@@ -0,0 +1,175 @@
+/**
+ * Root Cause Linking — recent git changes → suspect files per finding.
+ *
+ * Pure git-diff heuristic: no external API, no AI call. Reads the last N
+ * commits from the local repo (`git log --name-only`), maps changed files to
+ * route paths with the same slug heuristic as pr-diff-analyzer, and annotates
+ * each NEW finding (isNew: true) with the files/commits most likely to have
+ * caused it:
+ *
+ *   finding.rootCause = {
+ *     files:   ['src/pages/checkout/Form.jsx', ...],   // ≤ MAX_FILES
+ *     commits: [{ hash: 'abc1234', subject: '...' }],  // ≤ MAX_COMMITS
+ *     global:  false,  // true when only infra-level files matched
+ *   }
+ *
+ * Only new findings are annotated — a finding that predates the recent commits
+ * cannot have been caused by them. Source repo defaults to ARGUS_SOURCE_DIR or
+ * the current working directory. Disable with ARGUS_ROOT_CAUSE=0.
+ */
+
+import { execSync } from 'child_process';
+import { INFRA_PATTERNS } from './pr-diff-analyzer.js';
+import { childLogger }    from './logger.js';
+
+const logger = childLogger('root-cause-linker');
+
+/** Commits inspected by default. */
+export const DEFAULT_COMMITS = 10;
+/** Max suspect files attached to one finding. */
+const MAX_FILES = 5;
+/** Max commits attached to one finding. */
+const MAX_COMMITS = 3;
+
+/**
+ * Read the last N commits with their changed files from a local git repo.
+ * Returns [] when the directory is not a repo, git is unavailable, or the
+ * command fails — root cause linking is always best-effort.
+ *
+ * @param {string} [repoDir]  - Defaults to ARGUS_SOURCE_DIR, then cwd
+ * @param {object} [opts]
+ * @param {number} [opts.commits]
+ * @returns {Array<{ hash: string, subject: string, files: string[] }>}
+ */
+export function getRecentChanges(repoDir = process.env.ARGUS_SOURCE_DIR || process.cwd(), { commits = DEFAULT_COMMITS } = {}) {
+  let out;
+  try {
+    out = execSync(`git log --name-only --pretty=format:%h%x09%s -n ${Math.max(1, commits | 0)}`, {
+      cwd: repoDir,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 5000,
+    }).toString();
+  } catch {
+    return [];
+  }
+
+  const changes = [];
+  let current = null;
+  for (const line of out.split('\n')) {
+    // Detect commit lines on the RAW line — an empty commit subject leaves a
+    // trailing tab ("abc1234\t") that trimEnd() would strip, misclassifying
+    // the hash as a file path. File lines never contain raw tabs: git quotes
+    // paths with special characters (core.quotePath octal escapes).
+    if (line.includes('\t')) {
+      const [hash, ...subjectParts] = line.trimEnd().split('\t');
+      current = { hash, subject: subjectParts.join('\t'), files: [] };
+      changes.push(current);
+      continue;
+    }
+    const trimmed = line.trimEnd();
+    if (!trimmed) continue;
+    if (current) {
+      // Git emits paths with forward slashes on every platform
+      current.files.push(trimmed);
+    }
+  }
+  return changes;
+}
+
+/**
+ * Match changed file paths against one route path using the slug heuristic
+ * from pr-diff-analyzer: a file matches when any of its path/name slugs equals
+ * a route path segment. Infra-level files (configs, root layouts, global CSS)
+ * match every route and are reported via `global`.
+ *
+ * @param {string[]} files
+ * @param {string}   routePath  - e.g. "/checkout/review"
+ * @returns {{ files: string[], global: boolean }}
+ */
+export function matchFilesToRoutePath(files, routePath) {
+  const segments = String(routePath ?? '')
+    .toLowerCase()
+    .split('/')
+    .map(s => s.replace(/[^a-z0-9]/g, ''))
+    .filter(s => s.length > 1);
+
+  const matched = [];
+  let global = false;
+
+  for (const file of (files ?? [])) {
+    if (INFRA_PATTERNS.some(re => re.test(file))) {
+      global = true;
+      continue;
+    }
+    if (segments.length === 0) continue; // home route "/" — only infra files apply
+    const slugs = file
+      .toLowerCase()
+      .replace(/\.[^./\\]+$/, '')
+      .split(/[/\\._-]+/)
+      .filter(s => s.length > 1);
+    if (segments.some(seg => slugs.includes(seg))) matched.push(file);
+  }
+
+  return { files: matched, global };
+}
+
+/**
+ * Annotate NEW findings in the report with `rootCause` (mutates in place).
+ *
+ * For each route, slug-matches every recent commit's files against the route's
+ * URL pathname. Direct file matches win; when only infra-level files changed,
+ * the annotation carries `global: true` with those files as suspects.
+ *
+ * @param {object} report   - { routes: [{ url, errors }] }; findings need isNew
+ * @param {Array}  changes  - From getRecentChanges()
+ * @returns {{ linkedCount: number }}
+ */
+export function linkRootCauses(report, changes) {
+  let linkedCount = 0;
+  if (!Array.isArray(changes) || changes.length === 0) return { linkedCount };
+
+  for (const routeResult of (report.routes ?? [])) {
+    let routePath;
+    try {
+      routePath = new URL(routeResult.url).pathname;
+    } catch {
+      continue;
+    }
+
+    // Collect suspect files + commits for this route across the recent commits
+    const directFiles = [];
+    const infraFiles  = [];
+    const directCommits = [];
+    const infraCommits  = [];
+    for (const commit of changes) {
+      const { files, global } = matchFilesToRoutePath(commit.files, routePath);
+      if (files.length > 0) {
+        directFiles.push(...files);
+        directCommits.push({ hash: commit.hash, subject: commit.subject });
+      } else if (global) {
+        infraFiles.push(...commit.files.filter(f => INFRA_PATTERNS.some(re => re.test(f))));
+        infraCommits.push({ hash: commit.hash, subject: commit.subject });
+      }
+    }
+
+    const useDirect = directFiles.length > 0;
+    const suspectFiles   = [...new Set(useDirect ? directFiles : infraFiles)].slice(0, MAX_FILES);
+    const suspectCommits = (useDirect ? directCommits : infraCommits).slice(0, MAX_COMMITS);
+    if (suspectFiles.length === 0) continue;
+
+    for (const finding of (routeResult.errors ?? [])) {
+      if (!finding.isNew) continue; // pre-existing findings predate these commits
+      finding.rootCause = {
+        files:   suspectFiles,
+        commits: suspectCommits,
+        global:  !useDirect,
+      };
+      linkedCount++;
+    }
+  }
+
+  if (linkedCount > 0) {
+    logger.info(`[ARGUS] Root cause linking: ${linkedCount} new finding(s) linked to recent commits`);
+  }
+  return { linkedCount };
+}

package/src/utils/screen-recorder.js

@@ -0,0 +1,250 @@
+/**
+ * Argus Screen Recorder
+ *
+ * Records an audit session as a series of JPEG frames by periodically
+ * calling browser.screenshot(). Frames are saved to reports/recordings/<id>/.
+ *
+ * For genuine CDP screencast (Page.startScreencast) instead of polling,
+ * install the optional `ws` package:
+ *   npm install ws
+ * then use CdpScreenRecorder (exported below) which connects directly to
+ * Chrome's WebSocket debugger URL.
+ *
+ * Usage (polling recorder — no extra deps):
+ *   import { PollingRecorder } from './screen-recorder.js';
+ *   const rec = new PollingRecorder(browser, { intervalMs: 500 });
+ *   rec.start();
+ *   // ... run audit ...
+ *   const outputDir = await rec.stop('./reports/recordings/my-run');
+ *
+ * Usage (CDP screencast — requires ws):
+ *   import { CdpScreenRecorder } from './screen-recorder.js';
+ *   const rec = await CdpScreenRecorder.create(9222);
+ *   await rec.start();
+ *   // ...
+ *   const outputDir = await rec.stop('./reports/recordings/my-run');
+ */
+
+import { spawn } from 'child_process';
+import fs   from 'fs';
+import path from 'path';
+import http from 'http';
+
+// ── Polling Recorder (no extra dependencies) ──────────────────────────────────
+
+export class PollingRecorder {
+  /**
+   * @param {import('../adapters/browser.js').CdpBrowserAdapter} browser
+   * @param {{ intervalMs?: number, quality?: number }} [options]
+   */
+  constructor(browser, options = {}) {
+    this._browser   = browser;
+    this._intervalMs = options.intervalMs ?? 500;
+    this._quality    = options.quality    ?? 70;
+    this._frames     = [];
+    this._timer      = null;
+    this._startedAt  = null;
+  }
+
+  /** Begin periodic screenshot capture. */
+  start() {
+    if (this._timer) return;
+    this._startedAt = Date.now();
+    this._frames    = [];
+    this._timer     = setInterval(async () => {
+      try {
+        const raw = await this._browser.screenshot({ quality: this._quality });
+        // screenshot() returns an MCP result — extract base64 data if wrapped
+        const b64 = typeof raw === 'object' ? (raw.result ?? raw.data ?? raw) : raw;
+        if (b64) this._frames.push({ ts: Date.now(), data: b64 });
+      } catch { /* ignore individual capture errors */ }
+    }, this._intervalMs);
+  }
+
+  /**
+   * Stop recording and save frames to outputDir.
+   *
+   * @param {string} outputDir - Directory to write frame-NNN.jpg files into
+   * @returns {Promise<{ outputDir: string, frameCount: number, durationMs: number }>}
+   */
+  async stop(outputDir) {
+    if (this._timer) {
+      clearInterval(this._timer);
+      this._timer = null;
+    }
+
+    const durationMs = Date.now() - (this._startedAt ?? Date.now());
+    const frames     = this._frames.slice();
+    this._frames     = [];
+
+    const resolved = path.resolve(outputDir);
+    fs.mkdirSync(resolved, { recursive: true });
+
+    for (let i = 0; i < frames.length; i++) {
+      const name     = `frame-${String(i).padStart(4, '0')}.jpg`;
+      const filePath = path.join(resolved, name);
+      const b64      = frames[i].data;
+      // b64 may be a data URL prefix — strip it
+      const raw = typeof b64 === 'string'
+        ? b64.replace(/^data:image\/\w+;base64,/, '')
+        : b64;
+      try {
+        fs.writeFileSync(filePath, Buffer.from(raw, 'base64'));
+      } catch { /* skip unwritable frames */ }
+    }
+
+    // Write metadata + ffmpeg hint
+    const meta = {
+      frameCount:  frames.length,
+      durationMs,
+      intervalMs:  this._intervalMs,
+      capturedAt:  new Date(this._startedAt).toISOString(),
+      ffmpegHint:  `ffmpeg -framerate ${Math.round(1000 / this._intervalMs)} -i frame-%04d.jpg -c:v libx264 -pix_fmt yuv420p recording.mp4`,
+    };
+    fs.writeFileSync(path.join(resolved, 'meta.json'), JSON.stringify(meta, null, 2));
+
+    // Run ffmpeg automatically if available
+    await _tryFfmpeg(resolved, meta.intervalMs).catch(() => {});
+
+    return { outputDir: resolved, frameCount: frames.length, durationMs };
+  }
+}
+
+// ── CDP Screencast Recorder (requires ws package) ─────────────────────────────
+
+export class CdpScreenRecorder {
+  constructor(ws, sessionId) {
+    this._ws        = ws;
+    this._sessionId = sessionId;
+    this._frames    = [];
+    this._startedAt = null;
+    this._msgId     = 1;
+  }
+
+  /**
+   * Create a CdpScreenRecorder connected to the first Chrome tab.
+   * Requires the `ws` package: npm install ws
+   *
+   * @param {number} [port=9222]
+   * @returns {Promise<CdpScreenRecorder>}
+   */
+  static async create(port = 9222) {
+    let WebSocket;
+    try {
+      WebSocket = (await import('ws')).default;
+    } catch {
+      throw new Error(
+        'CDP screencast requires the ws package:\n' +
+        '  npm install ws\n' +
+        'Or use PollingRecorder instead (no extra deps).'
+      );
+    }
+
+    const debuggerUrl = await _fetchDebuggerUrl(port);
+    const ws = new WebSocket(debuggerUrl);
+
+    await new Promise((resolve, reject) => {
+      ws.once('open', resolve);
+      ws.once('error', reject);
+    });
+
+    const rec = new CdpScreenRecorder(ws, null);
+    ws.on('message', data => {
+      try {
+        const msg = JSON.parse(data.toString());
+        if (msg.method === 'Page.screencastFrame') {
+          rec._frames.push({ ts: Date.now(), data: msg.params.data });
+          // Acknowledge the frame to keep Chrome sending
+          rec._send('Page.screencastFrameAck', { sessionId: msg.params.metadata.sessionId });
+        }
+      } catch { /* ignore parse errors */ }
+    });
+
+    return rec;
+  }
+
+  _send(method, params = {}) {
+    this._ws.send(JSON.stringify({ id: this._msgId++, method, params }));
+  }
+
+  /** Start CDP screencast. */
+  async start() {
+    this._startedAt = Date.now();
+    this._frames    = [];
+    this._send('Page.startScreencast', {
+      format:        'jpeg',
+      quality:       70,
+      maxWidth:      1280,
+      maxHeight:     900,
+      everyNthFrame: 1,
+    });
+  }
+
+  /**
+   * Stop screencast and save frames to outputDir.
+   *
+   * @param {string} outputDir
+   * @returns {Promise<{ outputDir: string, frameCount: number, durationMs: number }>}
+   */
+  async stop(outputDir) {
+    this._send('Page.stopScreencast');
+    await new Promise(r => setTimeout(r, 200)); // drain any buffered frames
+    this._ws.close();
+
+    const durationMs = Date.now() - (this._startedAt ?? Date.now());
+    const frames     = this._frames.slice();
+    const resolved   = path.resolve(outputDir);
+
+    fs.mkdirSync(resolved, { recursive: true });
+
+    for (let i = 0; i < frames.length; i++) {
+      const name = `frame-${String(i).padStart(4, '0')}.jpg`;
+      fs.writeFileSync(path.join(resolved, name), Buffer.from(frames[i].data, 'base64'));
+    }
+
+    const meta = {
+      frameCount: frames.length,
+      durationMs,
+      capturedAt: new Date(this._startedAt).toISOString(),
+      ffmpegHint: `ffmpeg -framerate 2 -i frame-%04d.jpg -c:v libx264 -pix_fmt yuv420p recording.mp4`,
+    };
+    fs.writeFileSync(path.join(resolved, 'meta.json'), JSON.stringify(meta, null, 2));
+
+    await _tryFfmpeg(resolved, 500).catch(() => {});
+
+    return { outputDir: resolved, frameCount: frames.length, durationMs };
+  }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function _fetchDebuggerUrl(port) {
+  return new Promise((resolve, reject) => {
+    http.get(`http://localhost:${port}/json/list`, res => {
+      let body = '';
+      res.on('data', d => { body += d; });
+      res.on('end', () => {
+        try {
+          const pages = JSON.parse(body);
+          const target = pages.find(p => p.type === 'page') ?? pages[0];
+          if (!target?.webSocketDebuggerUrl) reject(new Error('No debuggable Chrome page found'));
+          else resolve(target.webSocketDebuggerUrl);
+        } catch (e) { reject(e); }
+      });
+    }).on('error', reject);
+  });
+}
+
+function _tryFfmpeg(outputDir, intervalMs) {
+  return new Promise((resolve, reject) => {
+    const fps  = Math.max(1, Math.round(1000 / intervalMs));
+    const proc = spawn('ffmpeg', [
+      '-y', '-framerate', String(fps),
+      '-i', 'frame-%04d.jpg',
+      '-c:v', 'libx264', '-pix_fmt', 'yuv420p',
+      'recording.mp4',
+    ], { cwd: outputDir, stdio: 'ignore' });
+    proc.on('close', code => (code === 0 ? resolve() : reject(new Error(`ffmpeg exited ${code}`))));
+    proc.on('error', reject);
+  });
+}