argusqa-os 9.2.0

package/src/config/targets.js

@@ -0,0 +1,309 @@
+/**
+ * ARGUS Target Configuration
+ *
+ * Define which URLs to test, what flows to check, and per-route settings.
+ * Claude Code reads this file when building test runs.
+ */
+
+import { childLogger } from '../utils/logger.js';
+const logger = childLogger('targets');
+
+export const config = {
+  /** Milliseconds to wait after navigation before capturing state */
+  pageSettleMs: 2000,
+
+  /** Screenshot quality (1–100) */
+  screenshotQuality: 90,
+
+  /** Pixel diff % above which a visual change is flagged */
+  screenshotDiffThreshold: parseFloat(process.env.SCREENSHOT_DIFF_THRESHOLD ?? '0.5'),
+
+  /** Directory to write reports and screenshots */
+  outputDir: process.env.REPORT_OUTPUT_DIR ?? './reports',
+};
+
+/**
+ * Centralized detection thresholds (v9.1.5).
+ * All magic-number limits across analyzers live here — change once, apply everywhere.
+ * Override individual values in your fork; never edit analyzer source files for tuning.
+ */
+export const thresholds = {
+  perf: {
+    LCP:  2500,  // ms — Largest Contentful Paint
+    CLS:  0.1,   // Cumulative Layout Shift
+    FID:  100,   // ms — First Input Delay (approx via TBT)
+    TTFB: 800,   // ms — Time to First Byte
+  },
+  network: {
+    slowWarning:   1000,            // ms — API response time warning
+    slowCritical:  3000,            // ms — API response time critical
+    sizeWarning:   500 * 1024,      // bytes — payload size warning  (500 KB)
+    sizeCritical:  2 * 1024 * 1024, // bytes — payload size critical (2 MB)
+  },
+  memory: {
+    detachedWarning:    10,              // detached DOM nodes → warning
+    detachedCritical:   100,             // detached DOM nodes → critical
+    heapGrowthWarning:  2 * 1024 * 1024,  // bytes heap growth → warning  (2 MB)
+    heapGrowthCritical: 10 * 1024 * 1024, // bytes heap growth → critical (10 MB)
+  },
+  hover: {
+    waitMs:       350,  // ms to wait after hover before checking DOM state
+    maxDropdowns: 8,    // max [aria-haspopup] elements to test per page
+    maxTooltips:  5,    // max [data-tooltip] elements to test per page
+  },
+  security: {
+    headTimeoutMs: 3000, // ms — HEAD fetch timeout for CSP/XFrame header check
+  },
+  apiFrequency: {
+    warningCount:  3,  // API called ≥ this many times → warning
+    criticalCount: 5,  // API called ≥ this many times → critical
+  },
+  lighthouse: {
+    accessibility:    { critical: 50, warning: 90 },
+    performance:      { critical: 50, warning: 90 },
+    seo:              { critical: 50, warning: 90 },
+    'best-practices': { critical: 50, warning: 90 },
+  },
+};
+
+/**
+ * Routes to test in crawl-and-report.js (error detection).
+ * Add every key page your application serves.
+ *
+ * Fields:
+ *   path        — URL path appended to the base URL
+ *   name        — human-readable label for reports
+ *   critical    — if true, any error on this route is escalated to 'critical'
+ *   waitFor     — optional CSS selector to wait for before capturing (signals page ready)
+ */
+export const routes = [
+  { path: '/', name: 'Home', critical: true, waitFor: 'main' },
+  { path: '/login', name: 'Login', critical: true, waitFor: 'form' },
+  { path: '/dashboard', name: 'Dashboard', critical: true, waitFor: '[data-testid="dashboard"]' },
+  { path: '/settings', name: 'Settings', critical: false, waitFor: null },
+  // Add more routes here as your app grows
+];
+
+/**
+ * Comparison route pairs for env-comparison.js.
+ * Each entry maps a dev path to the equivalent staging path (usually the same).
+ */
+export const comparisonRoutes = [
+  { path: '/', name: 'Home' },
+  { path: '/login', name: 'Login' },
+  { path: '/dashboard', name: 'Dashboard' },
+];
+
+/**
+ * API endpoints to validate response shapes against (D7.4).
+ * Each entry is checked against captured network requests on every crawled route.
+ *
+ * Fields:
+ *   url        — path (e.g. '/api/user') or full URL for exact match
+ *   method     — HTTP method to match (optional — omit to match any method)
+ *   schema     — inline JSON Schema object (preferred)
+ *   schemaFile — path to a JSON file containing the schema (alternative to schema)
+ *
+ * Supported schema keywords: type, required, properties, items.
+ *
+ * Violations are emitted as api_contract_violation warnings in the report.
+ *
+ * Examples:
+ *   { url: '/api/user', method: 'GET', schema: { type: 'object', required: ['id', 'name'], properties: { id: { type: 'number' }, name: { type: 'string' } } } }
+ *   { url: '/api/products', method: 'GET', schemaFile: './schemas/products.json' }
+ */
+export const apiContracts = [
+  // Uncomment and configure to validate API response shapes:
+  // { url: '/api/user',     method: 'GET', schema: { type: 'object', required: ['id', 'name'], properties: { id: { type: 'number' }, name: { type: 'string' } } } },
+  // { url: '/api/products', method: 'GET', schemaFile: './schemas/products.json' },
+];
+
+/**
+ * Severity policy overrides (D7.5).
+ * Post-processes all findings before Slack routing, letting teams adjust or
+ * silence specific detection types without editing analyzer source code.
+ *
+ * Keys are finding type strings (e.g. 'seo_missing_description').
+ * Values are one of: 'critical' | 'warning' | 'info' | 'suppress'
+ *   'suppress' removes the finding entirely from the report and Slack alerts.
+ *
+ * Examples:
+ *   seo_missing_description: 'info'     — demote noisy SEO finding to info
+ *   cache_headers_missing:   'suppress' — silence entirely on this project
+ *   redirect_chain:          'warning'  — keep at warning (already is; no-op)
+ */
+export const severityOverrides = {
+  // seo_missing_description: 'info',
+  // cache_headers_missing:   'suppress',
+};
+
+/**
+ * Auth session persistence (v3 Phase B2 / D7.6).
+ *
+ * When set, runCrawl() runs the login flow once before crawling, saves the
+ * session state (cookies + localStorage), and restores it before each route.
+ * This unlocks crawling of authenticated routes without re-logging in per page.
+ *
+ * D7.6 mid-run refresh: before each route, if the saved session has less than
+ * `sessionRefreshWindowMs` of validity remaining, the login flow is re-run
+ * automatically so long crawls never fail due to an expired auth cookie.
+ *
+ * Credentials MUST come from environment variables — never hardcode them here.
+ * Add ARGUS_AUTH_EMAIL and ARGUS_AUTH_PASSWORD to your .env file.
+ *
+ * Fields:
+ *   sessionFile           — path for the saved session JSON (default: .argus-session.json)
+ *   sessionMaxAgeMs       — max session lifetime before forcing re-login (default: 1 h)
+ *   sessionRefreshWindowMs — refresh when this many ms remain before expiry (default: 5 min)
+ *   steps                 — login flow steps (navigate, fill, click, waitFor, sleep)
+ *
+ * Set to null to disable auth (public crawl only).
+ */
+export const auth = null;
+
+/**
+ * User flow definitions (v3 Phase B5).
+ *
+ * Each flow is a named sequence of steps executed end-to-end by flow-runner.js.
+ * Supported actions:
+ *   navigate      — { action: 'navigate', path: '/route' }  or  url: 'https://...' for absolute
+ *   fill          — { action: 'fill', selector: 'input#email', value: 'x@y.com' }
+ *                   Add typing: true to dispatch real keyboard events (needed for input-validation handlers)
+ *   click         — { action: 'click', selector: 'button[type=submit]' }
+ *   press_key     — { action: 'press_key', key: 'Tab' | 'Enter' | 'Escape' | 'ArrowDown' | ... }
+ *   drag          — { action: 'drag', sourceSelector: '.card', targetSelector: '.dropzone' }
+ *   upload_file   — { action: 'upload_file', selector: 'input[type=file]', filePath: '/abs/path' }
+ *   select_option — { action: 'select_option', selector: 'select#country', value: 'US' }
+ *   waitFor       — { action: 'waitFor', selector: '#results', timeout: 10000 }
+ *   sleep         — { action: 'sleep', ms: 500 }   (avoid; use waitFor instead)
+ *   handle_dialog — { action: 'handle_dialog', accept: true }  or  accept: false
+ *   assert        — { action: 'assert', type: '...' } — see types below
+ *
+ * Assert types: no_console_errors, no_network_errors, element_visible, element_not_visible,
+ *               url_contains, no_js_errors
+ *
+ * Set to [] to disable (default).
+ */
+export const flows = [];
+
+// Uncomment and configure to test user journeys:
+// export const flows = [
+//   {
+//     name: 'Login flow',
+//     steps: [
+//       { action: 'navigate',  path: '/login' },
+//       { action: 'fill',      selector: '#email',    value: process.env.ARGUS_AUTH_EMAIL    ?? '' },
+//       { action: 'fill',      selector: '#password', value: process.env.ARGUS_AUTH_PASSWORD ?? '' },
+//       { action: 'click',     selector: 'button[type="submit"]' },
+//       { action: 'waitFor',   selector: '[data-testid="dashboard"]', timeout: 15000 },
+//       { action: 'assert',    type: 'no_console_errors' },
+//       { action: 'assert',    type: 'url_contains', value: '/dashboard' },
+//     ],
+//   },
+//   {
+//     name: 'Checkout flow',
+//     steps: [
+//       { action: 'navigate',  path: '/cart' },
+//       { action: 'click',     selector: '[data-testid="checkout-btn"]' },
+//       { action: 'waitFor',   selector: '[data-testid="payment-form"]' },
+//       { action: 'assert',    type: 'no_network_errors' },
+//       { action: 'assert',    type: 'element_visible', selector: '[data-testid="order-summary"]' },
+//     ],
+//   },
+//   {
+//     name: 'Advanced interactions',
+//     steps: [
+//       { action: 'navigate',    path: '/upload' },
+//       // Upload a file — resolves the file input by selector
+//       { action: 'upload_file', selector: 'input[type="file"]', filePath: '/tmp/test-file.pdf' },
+//       // Select a dropdown option
+//       { action: 'navigate',    path: '/settings' },
+//       { action: 'select_option', selector: 'select#country', value: 'US' },
+//       // Drag and drop
+//       { action: 'navigate',    path: '/kanban' },
+//       { action: 'drag',        sourceSelector: '[data-testid="card-1"]', targetSelector: '[data-testid="done-column"]' },
+//       // Keyboard navigation test
+//       { action: 'navigate',    path: '/menu' },
+//       { action: 'press_key',   key: 'Tab' },
+//       { action: 'press_key',   key: 'Enter' },
+//       { action: 'assert',      type: 'element_visible', selector: '[data-testid="submenu"]' },
+//       // Type with real keyboard events (for inputs with keydown validators)
+//       { action: 'fill',        selector: 'input[name="search"]', value: 'hello', typing: true },
+//     ],
+//   },
+// ];
+
+/**
+ * Codebase cross-reference (Phase C1).
+ *
+ * Point sourceDir at your app's source code to enable:
+ *   - env_var_missing      — process.env.X used in code but absent from .env files
+ *   - feature_flag_leakage — conditional env var that is falsy/unset in .env
+ *   - error_source_linked  — console error stack trace parsed to file:line (info)
+ *   - dead_route           — internal nav link that returns 404
+ *
+ * Set to null to disable (default).
+ */
+export const codebase = {
+  sourceDir: process.env.ARGUS_SOURCE_DIR ?? null,
+  envFile:   process.env.ARGUS_ENV_FILE   ?? null,
+};
+
+// Warn at startup when codebase analysis is unconfigured so operators know
+// env_var_missing / feature_flag_leakage detections will be silently skipped.
+if (!codebase.sourceDir) {
+  logger.warn('[ARGUS] codebase.sourceDir not configured — codebase analysis will be skipped (set ARGUS_SOURCE_DIR to enable)');
+}
+
+/**
+ * Auto route discovery (Phase C3).
+ *
+ * Augments the manual routes[] above with paths discovered from:
+ *   sitemap     — fetches /sitemap.xml from the base URL; follows one level of sitemap index
+ *   nextjs      — scans pages/ (Next 12) and app/ (Next 13+) under codebase.sourceDir
+ *   reactRouter — greps JS/TS source for <Route path="..."> and { path: "..." } patterns
+ *
+ * Discovered routes get: critical: false, waitFor: null, discovered: true.
+ * Manual route config (critical, waitFor, name) is always preserved.
+ * Set to null to disable auto-discovery entirely.
+ */
+export const autoDiscover = {
+  sitemap:     true,   // fetch /sitemap.xml from BASE_URL
+  nextjs:      true,   // scan pages/ + app/ under codebase.sourceDir (if set)
+  reactRouter: false,  // grep source for React Router path declarations (experimental)
+};
+
+/**
+ * GitHub PR integration (Phase C2).
+ *
+ * All configuration is via environment variables — no settings object needed here.
+ *
+ * Required env vars (set in .env or GitHub Actions secrets):
+ *   GITHUB_TOKEN        — personal access token or Actions GITHUB_TOKEN
+ *   GITHUB_REPOSITORY   — "owner/repo"  (set automatically in GitHub Actions)
+ *
+ * Optional env vars:
+ *   GITHUB_SHA          — commit SHA for status checks (auto in GitHub Actions)
+ *   GITHUB_PR_NUMBER    — PR number; add to your workflow:
+ *                           env:
+ *                             GITHUB_PR_NUMBER: ${{ github.event.pull_request.number }}
+ *   ARGUS_REPORT_URL    — URL to the full HTML report; linked from the commit status check
+ *
+ * When GITHUB_TOKEN + GITHUB_REPOSITORY are present, Argus will:
+ *   - Post (or update) a findings summary comment on the open PR
+ *   - Set a commit status check: 'failure' if new criticals exist, 'success' otherwise
+ */
+
+// Uncomment and configure for authenticated crawls:
+// export const auth = {
+//   sessionFile:             '.argus-session.json',
+//   sessionMaxAgeMs:         60 * 60 * 1000,   // 1 hour — re-login after this
+//   sessionRefreshWindowMs:  5 * 60 * 1000,    // refresh when < 5 min remain (D7.6)
+//   steps: [
+//     { action: 'navigate', path: '/login' },
+//     { action: 'fill',     selector: '#email',    value: process.env.ARGUS_AUTH_EMAIL    ?? '' },
+//     { action: 'fill',     selector: '#password', value: process.env.ARGUS_AUTH_PASSWORD ?? '' },
+//     { action: 'click',    selector: 'button[type="submit"]' },
+//     { action: 'waitFor',  selector: '[data-testid="dashboard"]', timeout: 15000 },
+//   ],
+// };

package/src/domain/finding.js

@@ -0,0 +1,25 @@
+/**
+ * Finding factory — enforces required fields and valid severity at creation time.
+ *
+ * All analyzer modules should build findings with createFinding() instead of
+ * raw object literals so missing fields throw at dev time rather than silently
+ * producing malformed reports.
+ *
+ * Object.freeze() prevents accidental mutation as findings pass through the
+ * dedup, severity-override, and baseline-diff pipeline.
+ */
+
+const VALID_SEVERITIES = new Set(['critical', 'warning', 'info']);
+
+/**
+ * Create an immutable finding object.
+ *
+ * @param {{ type: string, severity: string, message: string, url?: string }} opts
+ * @returns {Readonly<object>}
+ */
+export function createFinding({ type, severity, message, url = '', ...rest }) {
+  if (!type)                           throw new Error(`Finding missing: type`);
+  if (!VALID_SEVERITIES.has(severity)) throw new Error(`Invalid severity "${severity}" for type "${type}"`);
+  if (!message)                        throw new Error(`Finding missing: message`);
+  return Object.freeze({ type, severity, message, url, ...rest });
+}

package/src/mcp-server.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+/**
+ * Argus MCP Server (v9.2.0)
+ *
+ * Exposes Argus as an MCP server so Claude (or any MCP client) can call
+ * argus_audit, argus_audit_full, argus_compare, and argus_last_report
+ * directly from a conversation without using the CLI.
+ *
+ * Architecture: MCP-inside-MCP
+ *   Claude (MCP client)
+ *     → Argus MCP Server (this file)
+ *       → chrome-devtools-mcp client (mcp-client.js)
+ *         → Chrome (CDP)
+ *
+ * Registration: add to .mcp.json as "argus" server.
+ * Run standalone: node src/mcp-server.js
+ */
+
+import { Server }              from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import fs   from 'fs';
+import path from 'path';
+
+import { createMcpClient }                    from './utils/mcp-client.js';
+import { crawlRouteCheap, runCrawl }          from './orchestration/crawl-and-report.js';
+import { runComparison }                      from './orchestration/env-comparison.js';
+
+const REPORTS_DIR = path.resolve(process.cwd(), 'reports');
+
+// ── Tool definitions ─────────────────────────────────────────────────────────
+
+const TOOLS = [
+  {
+    name: 'argus_audit',
+    description: 'Run a quick (cheap) QA pass on a URL. Returns findings as JSON.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url:      { type: 'string',  description: 'Full URL to audit (e.g. http://localhost:3000/checkout)' },
+        critical: { type: 'boolean', description: 'Treat this route as critical — console errors become critical severity', default: false },
+      },
+      required: ['url'],
+    },
+  },
+  {
+    name: 'argus_audit_full',
+    description: 'Run a deep QA pass on a URL using all analyzers — Lighthouse performance/accessibility scoring, responsive layout checks across mobile/tablet/desktop viewports, memory leak detection via heap snapshot, hover-state bug detection, and accessibility tree snapshot. Returns a full JSON report with findings grouped by severity.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url:      { type: 'string',  description: 'Full URL to audit (e.g. https://example.com/dashboard)' },
+        critical: { type: 'boolean', description: 'Mark this route as critical — console errors are escalated to critical severity', default: false },
+      },
+      required: ['url'],
+    },
+  },
+  {
+    name: 'argus_compare',
+    description: 'Snapshot and diff two environments (dev vs staging) side-by-side. Navigates both URLs, captures screenshots, runs the full analyzer suite on each, then diffs the findings to surface regressions — things that appear in staging but not dev, or changed severity. Configure the two target URLs via TARGET_DEV_URL and TARGET_STAGING_URL environment variables before starting the server.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'argus_last_report',
+    description: 'Return the most recent Argus JSON report from the reports/ directory.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+];
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+async function withMcp(fn) {
+  const mcp = await createMcpClient();
+  try {
+    return await fn(mcp);
+  } finally {
+    try { mcp.close(); } catch { /* ignore — process already gone */ }
+  }
+}
+
+// ── Tool handlers ─────────────────────────────────────────────────────────────
+
+async function handleAudit({ url, critical = false }) {
+  return withMcp(async (mcp) => {
+    const parsed  = new URL(url);
+    const route   = { path: parsed.pathname + parsed.search + parsed.hash, name: 'audit', critical };
+    const findings = await crawlRouteCheap(route, parsed.origin, mcp);
+    return { content: [{ type: 'text', text: JSON.stringify(findings, null, 2) }] };
+  });
+}
+
+async function handleAuditFull({ url, critical = false }) {
+  return withMcp(async (mcp) => {
+    const parsed = new URL(url);
+    const report = await runCrawl(
+      mcp,
+      [{ path: parsed.pathname + parsed.search + parsed.hash, name: 'audit', critical }],
+      parsed.origin,
+    );
+    return { content: [{ type: 'text', text: JSON.stringify(report, null, 2) }] };
+  });
+}
+
+async function handleCompare() {
+  return withMcp(async (mcp) => {
+    const report = await runComparison(mcp);
+    return { content: [{ type: 'text', text: JSON.stringify(report, null, 2) }] };
+  });
+}
+
+async function handleLastReport() {
+  if (!fs.existsSync(REPORTS_DIR)) {
+    return { content: [{ type: 'text', text: '{"error":"No reports found in reports/"}' }] };
+  }
+  const files = fs.readdirSync(REPORTS_DIR).filter(f => f.endsWith('.json'));
+  if (files.length === 0) {
+    return { content: [{ type: 'text', text: '{"error":"No reports found in reports/"}' }] };
+  }
+  const latest = files
+    .map(f => ({ f, mt: fs.statSync(path.join(REPORTS_DIR, f)).mtimeMs }))
+    .sort((a, b) => b.mt - a.mt)[0].f;
+  const json = fs.readFileSync(path.join(REPORTS_DIR, latest), 'utf8');
+  return { content: [{ type: 'text', text: json }] };
+}
+
+// ── Server bootstrap ──────────────────────────────────────────────────────────
+
+const server = new Server(
+  { name: 'argus', version: '9.2.0' },
+  { capabilities: { tools: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  try {
+    switch (req.params.name) {
+      case 'argus_audit':       return await handleAudit(req.params.arguments ?? {});
+      case 'argus_audit_full':  return await handleAuditFull(req.params.arguments ?? {});
+      case 'argus_compare':     return await handleCompare();
+      case 'argus_last_report': return await handleLastReport();
+      default: throw new Error(`Unknown tool: ${req.params.name}`);
+    }
+  } catch (err) {
+    return {
+      content: [{ type: 'text', text: JSON.stringify({ error: err.message }) }],
+      isError: true,
+    };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/orchestration/crawl-and-report.js

@@ -0,0 +1,16 @@
+/**
+ * Argus Crawl Pipeline — backward-compat re-export shell (v9.2.0)
+ *
+ * The implementation has been split across three focused modules:
+ *
+ *   orchestrator.js     — crawl loop, route/flow crawl functions, runCrawl()
+ *   report-processor.js — dedup, severity overrides, baseline, JSON write
+ *   dispatcher.js       — Slack / GitHub / HTML dispatch
+ *
+ * All callers (argus.js, batch-runner.js, server handlers, test-harness)
+ * continue to import from this file unchanged.
+ */
+
+export { runCrawl, crawlRouteCheap, crawlRouteExpensive } from './orchestrator.js';
+export { processReport, deduplicateFindings, rebuildSummary } from './report-processor.js';
+export { dispatchAll } from './dispatcher.js';