argusqa-os 9.2.0

package/src/utils/github-reporter.js

@@ -0,0 +1,310 @@
+/**
+ * Argus Phase C2: GitHub PR comment + commit status integration.
+ *
+ * C2.1  formatPrComment(report, diff)    — build Markdown PR comment body (pure)
+ * C2.2  buildStatusPayload(report, diff) — build GitHub commit status payload (pure)
+ * C2.3  postPrComment(report, diff)      — create/update PR comment via GitHub API
+ * C2.4  setCommitStatus(report, diff)    — set commit status (blocks merge on new criticals)
+ * C2.5  isGitHubConfigured()             — guard: true when GITHUB_TOKEN + GITHUB_REPOSITORY set
+ * C2.6  reportToGitHub(report, diff)     — orchestrates C2.3 + C2.4
+ *
+ * Required env vars:
+ *   GITHUB_TOKEN        — personal access token or Actions GITHUB_TOKEN (required)
+ *   GITHUB_REPOSITORY   — "owner/repo" (set automatically in GitHub Actions)
+ *   GITHUB_SHA          — commit SHA for status checks (set automatically in GitHub Actions)
+ *   GITHUB_PR_NUMBER    — PR number; set in workflow via:
+ *                           env:
+ *                             GITHUB_PR_NUMBER: ${{ github.event.pull_request.number }}
+ *
+ * Optional env vars:
+ *   ARGUS_REPORT_URL    — URL to the full HTML report; linked in the commit status check
+ */
+
+import { childLogger } from './logger.js';
+
+const logger = childLogger('github-reporter');
+
+const COMMENT_MARKER = '<!-- argus-qa-report -->';
+const GITHUB_API     = 'https://api.github.com';
+const MAX_TABLE_ROWS = 15;  // cap table rows to stay within GitHub's 65536-char limit
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const SEV_ICON = { critical: '🔴', warning: '🟡', info: '🔵' };
+function sevIcon(sev) { return SEV_ICON[sev] ?? '⚪'; }
+
+/** Escape pipe characters so they don't break Markdown tables. */
+function mdCell(text, maxLen = 100) {
+  return String(text ?? '').slice(0, maxLen).replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}
+
+// ── C2.1: PR comment formatter (pure — no I/O) ───────────────────────────────
+
+/**
+ * Build the full Markdown body for a PR comment.
+ * Embed COMMENT_MARKER so future runs can find and update the same comment.
+ *
+ * @param {object} report  - runCrawl() report object
+ * @param {object|null} diff - applyBaseline() diff result (null = first run)
+ * @returns {string} Markdown comment body
+ */
+export function formatPrComment(report, diff) {
+  const { baseUrl, summary, routes = [], codebase = [], flows = [] } = report;
+  const runDate  = new Date(report.generatedAt).toUTCString();
+  const isFirst  = !diff || diff.isFirstRun;
+
+  // Collect new findings from all sources, tagging each with a display source label
+  const allNewFindings = [
+    ...routes.flatMap(r =>
+      r.errors
+        .filter(e => e.isNew !== false)
+        .map(e => ({ ...e, _source: r.route }))
+    ),
+    ...(codebase)
+      .filter(f => f.isNew !== false)
+      .map(f => ({ ...f, _source: 'Codebase (C1)' })),
+    ...flows.flatMap(f =>
+      (f.findings ?? [])
+        .filter(e => e.isNew !== false)
+        .map(e => ({ ...e, _source: `Flow: ${f.flowName}` }))
+    ),
+  ];
+
+  const newCriticals = allNewFindings.filter(f => f.severity === 'critical').length;
+  const newWarnings  = allNewFindings.filter(f => f.severity === 'warning').length;
+  const newInfos     = allNewFindings.filter(f => f.severity === 'info').length;
+  // Sum route + flow resolved findings for the display count
+  const resolvedCount = (diff?.resolvedCount ?? 0) + (diff?.flowResolvedCount ?? 0);
+
+  const lines = [
+    COMMENT_MARKER,
+    '## 🔍 Argus QA Report',
+    '',
+    `**Base URL**: ${baseUrl}  `,
+    `**Run time**: ${runDate}  `,
+    '',
+    '| | 🔴 Critical | 🟡 Warning | 🔵 Info | Total |',
+    '|---|---|---|---|---|',
+    `| **Total** | ${summary.critical} | ${summary.warning} | ${summary.info} | ${summary.total} |`,
+  ];
+
+  if (isFirst) {
+    lines.push('| **New** | _first run_ | _first run_ | _first run_ | _baseline established_ |');
+  } else {
+    lines.push(`| **New** | ${newCriticals} | ${newWarnings} | ${newInfos} | ${allNewFindings.length} |`);
+    lines.push(`| **Resolved** | — | — | — | ${resolvedCount} |`);
+  }
+
+  // ── New findings table — skipped on first run (all findings would be "new") ──
+  if (allNewFindings.length > 0 && !isFirst) {
+    lines.push('', `### 🆕 New Findings (${allNewFindings.length})`);
+    lines.push('| Severity | Source | Type | Details |');
+    lines.push('|---|---|---|---|');
+    for (const f of allNewFindings.slice(0, MAX_TABLE_ROWS)) {
+      lines.push(`| ${sevIcon(f.severity)} ${f.severity} | ${f._source} | \`${f.type}\` | ${mdCell(f.message)} |`);
+    }
+    if (allNewFindings.length > MAX_TABLE_ROWS) {
+      lines.push(`| … | … | … | _${allNewFindings.length - MAX_TABLE_ROWS} more — see full report_ |`);
+    }
+  }
+
+  // ── Resolved note ──
+  if (!isFirst && resolvedCount > 0) {
+    lines.push('', `### ✅ Resolved (${resolvedCount})`);
+    lines.push(`${resolvedCount} finding(s) resolved since last baseline.`);
+  }
+
+  // ── C1 codebase findings (all, flagged new where applicable) ──
+  if (codebase.length > 0) {
+    lines.push('', `### 📦 Codebase Analysis — ${codebase.length} finding(s)`);
+    lines.push('| Severity | Type | Details |');
+    lines.push('|---|---|---|');
+    for (const f of codebase.slice(0, MAX_TABLE_ROWS)) {
+      const newTag = f.isNew !== false ? ' _(new)_' : '';
+      lines.push(`| ${sevIcon(f.severity)} | \`${f.type}\` | ${mdCell(f.message)}${newTag} |`);
+    }
+    if (codebase.length > MAX_TABLE_ROWS) {
+      lines.push(`| … | … | _${codebase.length - MAX_TABLE_ROWS} more_ |`);
+    }
+  }
+
+  // ── Screenshot note ──
+  const screenshotCount = routes.filter(r => r.screenshot).length;
+  if (screenshotCount > 0) {
+    lines.push('', `> 📸 ${screenshotCount} route screenshot(s) available in CI artifacts.`);
+  }
+
+  lines.push('', '---');
+  lines.push(`_Generated by [Argus](https://github.com/ironclawdevs/GodMode---AI-Dev-Testing-Tool) · ${new Date(report.generatedAt).toISOString()}_`);
+
+  return lines.join('\n');
+}
+
+// ── C2.2: Commit status payload builder (pure — no I/O) ──────────────────────
+
+/**
+ * Build the payload for the GitHub commit status API.
+ * State is 'failure' when any new critical findings exist (blocks PR merge).
+ * Pure function — reads no env vars; callers attach target_url if desired.
+ *
+ * @param {object} report
+ * @param {object|null} diff
+ * @returns {{ state: string, description: string, context: string }}
+ */
+export function buildStatusPayload(report, diff) {
+  const newCriticals = [
+    ...(report.routes ?? []).flatMap(r =>
+      (r.errors ?? []).filter(e => e.severity === 'critical' && e.isNew !== false)
+    ),
+    ...(report.codebase ?? []).filter(f => f.severity === 'critical' && f.isNew !== false),
+    ...(report.flows ?? []).flatMap(f =>
+      (f.findings ?? []).filter(e => e.severity === 'critical' && e.isNew !== false)
+    ),
+  ].length;
+
+  const passing = newCriticals === 0;
+  return {
+    state:       passing ? 'success' : 'failure',
+    description: passing
+      ? `Argus: All checks passed (${report.summary.total} total finding(s))`
+      : `Argus: ${newCriticals} new critical issue(s) — merge blocked`,
+    context:     'argus-qa',
+  };
+}
+
+// ── GitHub API helper ─────────────────────────────────────────────────────────
+
+async function ghFetch(urlPath, method, body, attempt = 1) {
+  if (!process.env.GITHUB_TOKEN) {
+    throw new Error('GITHUB_TOKEN environment variable is not set — GitHub reporting is disabled');
+  }
+  const headers = {
+    'Authorization':        `Bearer ${process.env.GITHUB_TOKEN}`,
+    'Accept':               'application/vnd.github+json',
+    'X-GitHub-Api-Version': '2022-11-28',
+  };
+  if (body) headers['Content-Type'] = 'application/json';
+
+  let res;
+  try {
+    res = await fetch(`${GITHUB_API}${urlPath}`, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(15000),
+    });
+  } catch (err) {
+    // Network error or timeout — retry up to 3 times with exponential backoff
+    if (attempt < 3) {
+      await new Promise(r => setTimeout(r, attempt * 1000));
+      return ghFetch(urlPath, method, body, attempt + 1);
+    }
+    throw err;
+  }
+
+  // Retry on transient server errors (5xx) and rate-limit (429) with exponential backoff
+  if ((res.status >= 500 || res.status === 429) && attempt < 3) {
+    await new Promise(r => setTimeout(r, attempt * 1000));
+    return ghFetch(urlPath, method, body, attempt + 1);
+  }
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`GitHub API ${method} ${urlPath} → ${res.status}: ${text.slice(0, 200)}`);
+  }
+  return res.json();
+}
+
+// ── C2.3: Post or update PR comment ──────────────────────────────────────────
+
+/**
+ * Create a PR comment, or update the existing Argus comment if one is already present.
+ * Idempotent: re-running on the same PR updates in-place rather than spamming new comments.
+ */
+export async function postPrComment(report, diff) {
+  const repo  = process.env.GITHUB_REPOSITORY;
+  const prNum = process.env.GITHUB_PR_NUMBER;
+  if (!repo || !prNum) throw new Error('[ARGUS] C2: GITHUB_REPOSITORY or GITHUB_PR_NUMBER not set');
+
+  let body = formatPrComment(report, diff);
+
+  // GitHub hard limit is 65536 chars; truncate gracefully if exceeded.
+  const GITHUB_COMMENT_LIMIT = 65000;
+  if (body.length > GITHUB_COMMENT_LIMIT) {
+    const truncMsg = '\n\n_⚠️ Report truncated — full details in the saved JSON report._';
+    body = body.slice(0, GITHUB_COMMENT_LIMIT - truncMsg.length) + truncMsg;
+  }
+
+  // Find existing Argus comment to update
+  const existing = await ghFetch(`/repos/${repo}/issues/${prNum}/comments?per_page=100`, 'GET');
+  const prev = Array.isArray(existing)
+    ? existing.find(c => typeof c.body === 'string' && c.body.includes(COMMENT_MARKER))
+    : null;
+
+  if (prev) {
+    await ghFetch(`/repos/${repo}/issues/comments/${prev.id}`, 'PATCH', { body });
+    logger.info(`[ARGUS] C2: Updated PR #${prNum} comment (id: ${prev.id})`);
+  } else {
+    await ghFetch(`/repos/${repo}/issues/${prNum}/comments`, 'POST', { body });
+    logger.info(`[ARGUS] C2: Posted new comment on PR #${prNum}`);
+  }
+}
+
+// ── C2.4: Set commit status ───────────────────────────────────────────────────
+
+/**
+ * Set a GitHub commit status on GITHUB_SHA.
+ * 'failure' state prevents merge when required status checks are enforced.
+ */
+export async function setCommitStatus(report, diff) {
+  const repo = process.env.GITHUB_REPOSITORY;
+  const sha  = process.env.GITHUB_SHA;
+  if (!repo || !sha) throw new Error('[ARGUS] C2: GITHUB_REPOSITORY or GITHUB_SHA not set');
+
+  const payload = buildStatusPayload(report, diff);
+  // ARGUS_REPORT_URL is I/O-dependent — attached here, not in the pure builder
+  if (process.env.ARGUS_REPORT_URL) {
+    payload.target_url = process.env.ARGUS_REPORT_URL;
+  }
+  await ghFetch(`/repos/${repo}/statuses/${sha}`, 'POST', payload);
+  logger.info(`[ARGUS] C2: Commit status → ${payload.state} (${payload.description})`);
+}
+
+// ── C2.5: Configuration guard ─────────────────────────────────────────────────
+
+export function isGitHubConfigured() {
+  return !!(process.env.GITHUB_TOKEN && process.env.GITHUB_REPOSITORY);
+}
+
+// ── C2.6: Orchestrator ────────────────────────────────────────────────────────
+
+/**
+ * Run both PR comment and commit status updates in parallel.
+ * Each operation is independent — a failure in one doesn't block the other.
+ */
+export async function reportToGitHub(report, diff) {
+  const tasks = [];
+
+  if (process.env.GITHUB_PR_NUMBER) {
+    tasks.push(
+      postPrComment(report, diff).catch(err =>
+        logger.warn(`[ARGUS] C2: PR comment failed — ${err.message}`)
+      )
+    );
+  }
+
+  if (process.env.GITHUB_SHA) {
+    tasks.push(
+      setCommitStatus(report, diff).catch(err =>
+        logger.warn(`[ARGUS] C2: Commit status failed — ${err.message}`)
+      )
+    );
+  }
+
+  if (tasks.length === 0) {
+    logger.info('[ARGUS] C2: No GITHUB_PR_NUMBER or GITHUB_SHA — skipping GitHub reporting');
+    return;
+  }
+
+  await Promise.all(tasks);
+}

package/src/utils/hover-analyzer.js

@@ -0,0 +1,214 @@
+/**
+ * ARGUS Hover-State Analyzer (v3 Phase D8.1)
+ *
+ * Uses browser.hover() to trigger hover state on interactive elements that declare
+ * dropdown or tooltip behaviour via ARIA attributes, then verifies the expected
+ * DOM change occurred after the hover.
+ *
+ * Detections:
+ *   hover_dropdown_broken — [aria-haspopup] element whose controlled popup does
+ *                           not become visible (aria-expanded stays false, popup
+ *                           remains display:none / visibility:hidden / opacity:0)
+ *   hover_tooltip_missing — [data-tooltip] element whose tooltip is not visible
+ *                           in the DOM after hover (not found or opacity:0 /
+ *                           display:none)
+ *
+ * Candidates are capped (8 dropdowns, 5 tooltips) to keep crawl time bounded.
+ * All errors are silently swallowed per-element so a single broken selector
+ * cannot abort the entire analysis.
+ */
+
+import { resolveUidForSelector } from './flow-runner.js';
+import { registerExpensive }    from '../registry.js';
+import { thresholds }           from '../config/targets.js';
+
+// ── Discovery script ──────────────────────────────────────────────────────────
+// Runs in the live page to find hover-testable candidates.
+// Returns JSON array of { kind, selector, controls, tooltipId, label }.
+const HOVER_CANDIDATE_SCRIPT = `() => {
+  var results = [];
+  function buildSelector(el) {
+    // Use CSS.escape() — raw id/class names containing :, ., [, / or spaces
+    // produce invalid selectors that querySelector silently fails to match.
+    if (el.id) return '#' + CSS.escape(el.id);
+    var classes = Array.from(el.classList)
+      .filter(function(c) { return /^[a-zA-Z_-]/.test(c); })
+      .slice(0, 2)
+      .map(function(c) { return CSS.escape(c); });
+    var tag = el.tagName.toLowerCase();
+    if (!classes.length) return tag;
+    var selector = tag + '.' + classes.join('.');
+    if (document.querySelectorAll(selector).length === 1) return selector;
+    // nth-of-type counts within parent, not the full document — may misfire
+    // when same-tag elements exist across multiple parents. Acceptable heuristic.
+    var idx = Array.from(document.querySelectorAll(tag)).indexOf(el) + 1;
+    return tag + ':nth-of-type(' + idx + ')';
+  }
+  var popupEls = document.querySelectorAll('[aria-haspopup]');
+  for (var i = 0; i < Math.min(popupEls.length, ${thresholds.hover.maxDropdowns}); i++) {
+    var el = popupEls[i];
+    var r = el.getBoundingClientRect();
+    if (r.width === 0 && r.height === 0) continue;
+    results.push({
+      kind:     'haspopup',
+      selector: buildSelector(el),
+      controls: el.getAttribute('aria-controls') || null,
+      label:    (el.textContent || el.getAttribute('aria-label') || '').trim().slice(0, 40),
+    });
+  }
+  var tipEls = document.querySelectorAll('[data-tooltip]');
+  for (var j = 0; j < Math.min(tipEls.length, ${thresholds.hover.maxTooltips}); j++) {
+    var tel = tipEls[j];
+    var tr = tel.getBoundingClientRect();
+    if (tr.width === 0 && tr.height === 0) continue;
+    results.push({
+      kind:      'tooltip',
+      selector:  buildSelector(tel),
+      tooltipId: tel.getAttribute('aria-describedby') || null,
+      label:     tel.getAttribute('data-tooltip') || '',
+    });
+  }
+  return JSON.stringify(results);
+}`;
+
+// ── Post-hover check — dropdown ───────────────────────────────────────────────
+// After hovering an [aria-haspopup] element, checks whether:
+//   (a) aria-expanded="true" is now present on any haspopup element, OR
+//   (b) the controlled popup element is visually visible.
+// Returns JSON { expanded: bool, popupVisible: bool }.
+function popupCheckScript(controls) {
+  const ctrlExpr = controls
+    ? `document.getElementById(${JSON.stringify(controls)})`
+    : `(document.querySelector('[role="menu"],[role="listbox"],[role="dialog"]'))`;
+  return `() => {
+    var expanded = document.querySelector('[aria-haspopup][aria-expanded="true"]') !== null;
+    var ctrlEl   = ${ctrlExpr};
+    var popupVisible = false;
+    if (ctrlEl) {
+      var s = window.getComputedStyle(ctrlEl);
+      popupVisible = s.display !== 'none'
+        && s.visibility !== 'hidden'
+        && parseFloat(s.opacity) > 0.05
+        && ctrlEl.offsetHeight > 0;
+    }
+    return JSON.stringify({ expanded: expanded, popupVisible: popupVisible });
+  }`;
+}
+
+// ── Post-hover check — tooltip ────────────────────────────────────────────────
+// After hovering a [data-tooltip] element, checks whether the associated
+// tooltip element is visible (non-zero size, opacity > 0, not display:none).
+// Returns JSON { found: bool, visible: bool }.
+function tooltipCheckScript(tooltipId) {
+  const tipExpr = tooltipId
+    ? `document.getElementById(${JSON.stringify(tooltipId)})`
+    : `document.querySelector('[role="tooltip"]')`;
+  return `() => {
+    var tip = ${tipExpr};
+    if (!tip) tip = document.querySelector('[role="tooltip"]');
+    if (!tip) return JSON.stringify({ found: false, visible: false });
+    var s = window.getComputedStyle(tip);
+    var visible = s.display !== 'none'
+      && s.visibility !== 'hidden'
+      && parseFloat(s.opacity) > 0.05
+      && tip.offsetHeight > 0;
+    return JSON.stringify({ found: true, visible: visible });
+  }`;
+}
+
+// ── JSON parse helper ─────────────────────────────────────────────────────────
+function parseJson(raw) {
+  if (raw == null) return null;
+  if (typeof raw === 'object' && !Array.isArray(raw)) {
+    const inner = raw.result !== undefined ? raw.result : raw;
+    if (typeof inner === 'string') { try { return JSON.parse(inner); } catch { return null; } }
+    return typeof inner === 'object' ? inner : null;
+  }
+  if (typeof raw === 'string') { try { return JSON.parse(raw); } catch { return null; } }
+  return null;
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Analyse hover-state behaviour for interactive elements on a page.
+ *
+ * Navigates to the URL, discovers hover-testable elements, hovers each one,
+ * then verifies that the expected DOM change occurred. Silently skips elements
+ * whose selector cannot be resolved or whose hover call throws.
+ *
+ * @param {object}  mcp        - MCP tool interface (navigate_page, evaluate_script, hover)
+ * @param {string}  url        - Fully-qualified URL to analyse
+ * @param {boolean} isCritical - Whether the route is marked critical in targets.js
+ * @returns {Promise<object[]>} Array of hover-bug finding objects
+ */
+export async function analyzeHover(browser, url, isCritical = false) {
+  const findings = [];
+
+  try {
+    await browser.navigate(url);
+    await browser.waitFor({ state: 'networkidle' }).catch(() => {});
+    await new Promise(r => setTimeout(r, 1000));
+  } catch {
+    return findings;
+  }
+
+  let candidates = [];
+  try {
+    const raw = await browser.evaluate(HOVER_CANDIDATE_SCRIPT);
+    const parsed = parseJson(raw);
+    candidates = Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return findings;
+  }
+
+  for (const candidate of candidates) {
+    try {
+      // Browser hover requires uid (not CSS selector) — resolve via snapshot
+      const hoverUid = await resolveUidForSelector(browser, candidate.selector);
+      if (!hoverUid) continue; // element not found in snapshot — skip
+      await browser.hover(hoverUid);
+      await new Promise(r => setTimeout(r, thresholds.hover.waitMs));
+
+      if (candidate.kind === 'haspopup') {
+        const raw   = await browser.evaluate(popupCheckScript(candidate.controls));
+        const state = parseJson(raw);
+        if (state && !state.expanded && !state.popupVisible) {
+          findings.push({
+            type:     'hover_dropdown_broken',
+            selector: candidate.selector,
+            label:    candidate.label,
+            message:  `Hover on "${candidate.label || candidate.selector}" (aria-haspopup) did not open its dropdown — aria-expanded stayed false and controlled popup remained hidden`,
+            severity: isCritical ? 'critical' : 'warning',
+            url,
+          });
+        }
+      } else if (candidate.kind === 'tooltip') {
+        const raw   = await browser.evaluate(tooltipCheckScript(candidate.tooltipId));
+        const state = parseJson(raw);
+        if (state && !state.visible) {
+          findings.push({
+            type:     'hover_tooltip_missing',
+            selector: candidate.selector,
+            label:    candidate.label,
+            message:  `Hover on "${candidate.label || candidate.selector}" (data-tooltip) did not reveal a tooltip — tooltip element ${state.found ? 'exists but is hidden (opacity / display / visibility override)' : 'was not found in DOM'}`,
+            severity: 'warning',
+            url,
+          });
+        }
+      }
+    } catch {
+      // Individual hover check failed — skip this element silently
+    }
+  }
+
+  return findings;
+}
+
+// ── Self-registration ─────────────────────────────────────────────────────────
+registerExpensive({
+  name: 'hover',
+  async analyze(browser, url, route) {
+    return analyzeHover(browser, url, route?.critical ?? false);
+  },
+});