@monoes/monobrowse 1.0.12 → 1.0.13

package/src/cli/commands.ts

@@ -1698,6 +1698,272 @@ const evalCommand: Command = {
   },
 };
 
+const reportCommand: Command = {
+  name: 'report',
+  description:
+    'Test a page and write one self-contained HTML report + sibling JSON. Usage: monomind browse report <url>',
+  options: [
+    { name: 'out', short: 'o', type: 'string', description: 'Output .html path, or a directory' },
+    {
+      name: 'budget',
+      short: 'b',
+      type: 'string',
+      description: 'Budget JSON file path, or inline JSON',
+    },
+    {
+      name: 'devices',
+      short: 'd',
+      type: 'string',
+      description: 'Comma-separated device names for the screenshot matrix',
+    },
+    {
+      name: 'wait',
+      short: 'w',
+      type: 'string',
+      description: 'Extra settle step: a CSS selector to wait for, or milliseconds',
+    },
+    { name: 'json', type: 'boolean', description: 'Output as JSON', default: false },
+    {
+      name: 'full-page',
+      type: 'boolean',
+      description: 'Full-page screenshot (--no-full-page for viewport only)',
+      default: true,
+    },
+    {
+      name: 'vitals-wait',
+      type: 'number',
+      description: 'Milliseconds to let the web-vitals observers run',
+      default: 2500,
+    },
+    {
+      name: 'timeout',
+      type: 'number',
+      description: 'Milliseconds to wait for the page to go network-idle',
+      default: 20000,
+    },
+    {
+      name: 'keep-open',
+      type: 'boolean',
+      description: 'Leave the browser running after the report',
+      default: false,
+    },
+    {
+      name: 'repeat',
+      type: 'number',
+      description: 'Run the URL N times and report per-check flake rates (RIG-14)',
+    },
+    {
+      name: 'record',
+      type: 'boolean',
+      description: 'Record frames for the evidence timeline even when the run passes',
+      default: false,
+    },
+    {
+      name: 'history',
+      type: 'boolean',
+      description: 'Print the stored run history for this URL instead of running it',
+      default: false,
+    },
+    {
+      name: 'save',
+      type: 'boolean',
+      description: 'Save this run to the history store (--no-save to skip)',
+      default: true,
+    },
+    {
+      name: 'history-max',
+      type: 'number',
+      description: 'Runs kept per URL before the oldest are pruned (default 20)',
+    },
+    {
+      name: 'trend-window',
+      type: 'number',
+      description: 'Prior runs charted in the trend section (default 10)',
+    },
+  ],
+  examples: [
+    { command: 'monomind browse report https://example.com', description: 'Report with defaults' },
+    {
+      command: 'monomind browse report https://example.com --repeat 5',
+      description: 'Run five times and report flake rates',
+    },
+    {
+      command: 'monomind browse report https://example.com --history',
+      description: 'Show the stored run history for a URL',
+    },
+    {
+      command: 'monomind browse report https://example.com --record',
+      description: 'Attach a frame-by-frame evidence timeline',
+    },
+    {
+      command: 'monomind browse report https://example.com --out ./reports/home.html',
+      description: 'Choose the output path',
+    },
+    {
+      command: 'monomind browse report https://example.com --budget \'{"lcp":4000}\'',
+      description: 'Relax a budget inline',
+    },
+    {
+      command: 'monomind browse report https://example.com --devices "iPhone 14,iPad"',
+      description: 'Add a device screenshot matrix',
+    },
+  ],
+  action: async (ctx: CommandContext): Promise<CommandResult> => {
+    const url = ctx.args[0] as string;
+    if (!url) throw new Error('URL required. Usage: monomind browse report <url>');
+
+    // Imported lazily for the same reason getBrowser() is: this module loads
+    // on every CLI invocation, and nothing but `report` needs the renderer.
+    const { runReport, runReportRepeated, readHistory } = await import('../report/index.js');
+
+    // --history is a read of the store, so it deliberately never launches a
+    // browser — `report --history` must work offline and on a dead site.
+    if (ctx.flags.history) {
+      const { dir, runs } = await readHistory(url);
+      if (ctx.flags.json) {
+        print(JSON.stringify({ data: { dir, runs } }, null, 2));
+      } else if (!runs.length) {
+        output.printWarning(`No stored runs for ${url}`);
+        print(`Looked in: ${dir}`);
+      } else {
+        print(`${runs.length} run(s) for ${url}`);
+        print(`Stored in: ${dir}`);
+        for (const run of runs) {
+          const lcp = run.vitals.lcp === undefined ? '—' : `${Math.round(run.vitals.lcp)}ms`;
+          print(
+            `  ${run.capturedAt}  ${run.verdict.toUpperCase().padEnd(4)}  ` +
+              `LCP ${lcp.padStart(7)}  ${run.counts.consoleErrors} console errors  ` +
+              `${run.counts.failedRequests} failed requests  ${run.counts.a11yErrors} a11y errors`,
+          );
+        }
+      }
+      return { success: true, data: { dir, runs } };
+    }
+
+    const repeatRaw = ctx.flags.repeat as number | undefined;
+    const repeat =
+      typeof repeatRaw === 'number' && Number.isFinite(repeatRaw) && repeatRaw > 1
+        ? Math.floor(repeatRaw)
+        : undefined;
+
+    const { client, sessionId } = await ensureConnected(_port);
+    const browser = await getBrowser();
+
+    const rawDevices = ctx.flags.devices;
+    const devices =
+      typeof rawDevices === 'string'
+        ? rawDevices
+            .split(',')
+            .map((d) => d.trim())
+            .filter(Boolean)
+        : undefined;
+
+    const runOptions = {
+      url,
+      out: ctx.flags.out as string | undefined,
+      budget: ctx.flags.budget as string | undefined,
+      devices,
+      wait: ctx.flags.wait as string | undefined,
+      vitalsWaitMs: ctx.flags['vitals-wait'] as number | undefined,
+      loadTimeoutMs: ctx.flags.timeout as number | undefined,
+      fullPage: ctx.flags['full-page'] !== false,
+      cwd: ctx.cwd,
+      // A failing run records its own evidence without being asked; --record
+      // is for when you want the timeline from a run that passes.
+      record: ctx.flags.record === true,
+      history: ctx.flags.save !== false,
+      historyMax: ctx.flags['history-max'] as number | undefined,
+      trendWindow: ctx.flags['trend-window'] as number | undefined,
+    };
+
+    let result:
+      | Awaited<ReturnType<typeof runReport>>
+      | Awaited<ReturnType<typeof runReportRepeated>>;
+    try {
+      result = repeat
+        ? await runReportRepeated(client, sessionId, { ...runOptions, repeat })
+        : await runReport(client, sessionId, runOptions);
+    } finally {
+      // A report is a one-shot command — CI should not be left with an
+      // orphan Chrome. Only close a browser THIS process launched: an
+      // attached one belongs to the user's own `open`/`connect` session.
+      if (!ctx.flags['keep-open'] && browser.getLaunchedPid(_port) !== undefined) {
+        browser.stopRequestCapture(sessionId);
+        browser.teardownConsoleCapture(sessionId);
+        try {
+          await browser.closeBrowser(client, _port);
+        } catch {
+          /* best-effort */
+        }
+        _client = null;
+        _sessionId = '';
+        _targetId = '';
+        _refs = new Map();
+        await browser.clearActivePort();
+        await browser.clearRefCache();
+      }
+    }
+
+    const { report, htmlPath, jsonPath, summary, historyDir } = result;
+    const { flake } = result;
+    // With --repeat the flake verdict governs: a check that failed 2 of 5
+    // runs must not exit 0 just because the last run happened to be green.
+    const passed = flake ? flake.verdict === 'pass' : report.verdict === 'pass';
+
+    if (ctx.flags.json) {
+      const { toJsonReport } = await import('../report/index.js');
+      print(
+        JSON.stringify(
+          { data: { ...toJsonReport(report), flake, htmlPath, jsonPath, historyDir } },
+          null,
+          2,
+        ),
+      );
+    } else {
+      if (passed) output.printSuccess(summary);
+      else output.printError(summary);
+      if (flake) {
+        print(`    ${flake.confidenceNote}`);
+        for (const check of flake.checks.filter((c) => !c.stable)) {
+          print(`    ${check.label}: failed ${check.failed} of ${check.runs} runs`);
+        }
+        for (const signal of flake.signals.slice(0, 5)) {
+          print(
+            `    ${signal.kind} "${signal.signature}" in ${signal.runs} of ${signal.total} runs`,
+          );
+        }
+      }
+      for (const failure of report.failures) {
+        print(`    ${failure.budget}: expected ${failure.expected}, got ${failure.actual}`);
+        if (failure.detail) print(`      ${failure.detail}`);
+      }
+      for (const headline of report.trend?.headlines ?? []) output.printWarning(headline);
+      if (report.diff?.structure) {
+        const d = report.diff.structure;
+        print(
+          `    vs previous run: ${d.gained.length} gained, ${d.lost.length} lost, ${d.renamed.length} renamed`,
+        );
+      }
+      if (report.diff?.pixels?.comparable) {
+        print(
+          `    vs previous run: ${report.diff.pixels.changedPercent.toFixed(2)}% of pixels changed`,
+        );
+      }
+      for (const note of report.notes) output.printWarning(note);
+      print(`Report: ${htmlPath}`);
+      print(`JSON:   ${jsonPath}`);
+      if (historyDir) print(`History: ${historyDir}`);
+    }
+
+    // Non-zero exit is the point of RIG-06 — CI and agents gate on it.
+    return {
+      success: passed,
+      exitCode: passed ? 0 : 1,
+      data: { htmlPath, jsonPath, report, flake },
+    };
+  },
+};
+
 const closeCommand: Command = {
   name: 'close',
   description: 'Close the active browser session',
@@ -3859,6 +4125,7 @@ const browseCommand: Command = {
     traceCommand,
     profilerCommand,
     vitalsCommand,
+    reportCommand,
     harCommand,
     resizeCommand,
     closeCommand,
@@ -3892,6 +4159,10 @@ const browseCommand: Command = {
       command: 'monomind browse network route --pattern "https://api.*" --abort',
       description: 'Abort API calls',
     },
+    {
+      command: 'monomind browse report https://example.com',
+      description: 'One-command page report with a pass/fail verdict',
+    },
     { command: 'monomind browse close', description: 'Close browser session' },
   ],
   action: async (_ctx: CommandContext): Promise<CommandResult> => {
@@ -3948,6 +4219,7 @@ const browseCommand: Command = {
     output.printInfo('  batch          Execute multiple commands');
     output.printInfo('  addinitscript  Add script to run before page navigation');
     output.printInfo('  removeinitscript Remove a previously added init script');
+    output.printInfo('  report         Test a page and write an HTML report');
     output.printInfo('  close          Close the browser session');
     return { success: true };
   },

package/src/report/a11y.ts

@@ -0,0 +1,242 @@
+/**
+ * Accessibility rules computed from the CDP accessibility tree.
+ *
+ * Deliberate scope limit: colour contrast is NOT computed here. Contrast
+ * needs resolved foreground/background pixels or computed styles, and the AX
+ * tree carries neither — guessing it would produce confident nonsense. The
+ * report says so explicitly instead.
+ *
+ * Every rule is a pure function of a node array, so the fixtures in the tests
+ * are just hand-written AX trees.
+ */
+
+import type { A11yFinding, AxNode, FocusCandidate } from './types.js';
+
+/** Roles whose whole purpose is to be activated — a nameless one is unusable. */
+const COMMAND_ROLES = new Set([
+  'button',
+  'link',
+  'menuitem',
+  'menuitemcheckbox',
+  'menuitemradio',
+  'tab',
+  'switch',
+  'treeitem',
+]);
+
+/** Roles that take user input and therefore need a programmatic label. */
+const FORM_FIELD_ROLES = new Set([
+  'textbox',
+  'searchbox',
+  'combobox',
+  'listbox',
+  'checkbox',
+  'radio',
+  'slider',
+  'spinbutton',
+]);
+
+const IMAGE_ROLES = new Set(['image', 'img']);
+
+/** Natively focusable tags — a negative tabindex on these removes them from the tab order. */
+const NATIVELY_FOCUSABLE = new Set(['a', 'button', 'input', 'select', 'textarea', 'summary']);
+
+function strValue(v: unknown): string {
+  return typeof v === 'string' ? v : v == null ? '' : String(v);
+}
+
+function roleOf(node: AxNode): string {
+  return strValue(node.role?.value).toLowerCase();
+}
+
+function nameOf(node: AxNode): string {
+  return strValue(node.name?.value).trim();
+}
+
+function propOf(node: AxNode, name: string): unknown {
+  return node.properties?.find((p) => p.name === name)?.value?.value;
+}
+
+function locatorFor(node: AxNode, locators?: Map<number, string>): string {
+  if (node.backendDOMNodeId !== undefined) {
+    const found = locators?.get(node.backendDOMNodeId);
+    if (found) return found;
+  }
+  return `ax-node:${node.nodeId}`;
+}
+
+/**
+ * Depth-first document order. `Accessibility.getFullAXTree` usually returns
+ * nodes pre-ordered already, but heading-order is the one rule where a
+ * reordered array would silently produce wrong findings, so we walk childIds
+ * ourselves. Nodes unreachable from a root are appended in array order rather
+ * than dropped.
+ */
+export function orderNodes(nodes: AxNode[]): AxNode[] {
+  const byId = new Map<string, AxNode>();
+  for (const n of nodes) byId.set(String(n.nodeId), n);
+
+  const ids = new Set(byId.keys());
+  const roots = nodes.filter((n) => n.parentId === undefined || !ids.has(String(n.parentId)));
+
+  const seen = new Set<string>();
+  const ordered: AxNode[] = [];
+  const visit = (node: AxNode): void => {
+    const id = String(node.nodeId);
+    if (seen.has(id)) return;
+    seen.add(id);
+    ordered.push(node);
+    for (const childId of node.childIds ?? []) {
+      const child = byId.get(String(childId));
+      if (child) visit(child);
+    }
+  };
+  for (const root of roots) visit(root);
+  for (const node of nodes) if (!seen.has(String(node.nodeId))) ordered.push(node);
+  return ordered;
+}
+
+/**
+ * Nameless controls, images without alt text, and unlabelled form fields.
+ *
+ * `ignored` nodes are skipped: that is how `<img alt="">` correctly escapes
+ * the image rule — a deliberately decorative image is dropped from the AX
+ * tree, while `<img>` with no alt attribute at all stays in it with an empty
+ * name, which is the bug we want to report.
+ */
+export function findNamingIssues(nodes: AxNode[], locators?: Map<number, string>): A11yFinding[] {
+  const findings: A11yFinding[] = [];
+  for (const node of nodes) {
+    if (node.ignored) continue;
+    const role = roleOf(node);
+    if (!role) continue;
+    const name = nameOf(node);
+    if (name) continue;
+
+    if (FORM_FIELD_ROLES.has(role)) {
+      findings.push({
+        rule: 'form-field-no-label',
+        impact: 'error',
+        role,
+        name: null,
+        locator: locatorFor(node, locators),
+        detail: `${role} has no accessible name — no <label>, aria-label or aria-labelledby resolves to one`,
+      });
+      continue;
+    }
+
+    if (COMMAND_ROLES.has(role)) {
+      findings.push({
+        rule: 'unlabelled-control',
+        impact: 'error',
+        role,
+        name: null,
+        locator: locatorFor(node, locators),
+        detail: `${role} has no accessible name — a screen reader announces it as just "${role}"`,
+      });
+      continue;
+    }
+
+    if (IMAGE_ROLES.has(role)) {
+      findings.push({
+        rule: 'image-missing-alt',
+        impact: 'error',
+        role,
+        name: null,
+        locator: locatorFor(node, locators),
+        detail: 'image has no alt text (use alt="" if it is purely decorative)',
+      });
+    }
+  }
+  return findings;
+}
+
+/**
+ * Headings that skip a level (h1 -> h3), plus a document whose first heading
+ * is not h1. Both break the outline screen-reader users navigate by.
+ */
+export function findHeadingIssues(nodes: AxNode[], locators?: Map<number, string>): A11yFinding[] {
+  const findings: A11yFinding[] = [];
+  let previous: number | null = null;
+
+  for (const node of orderNodes(nodes)) {
+    if (node.ignored) continue;
+    if (roleOf(node) !== 'heading') continue;
+    const raw = propOf(node, 'level');
+    const level = typeof raw === 'number' ? raw : Number.parseInt(strValue(raw), 10);
+    if (!Number.isFinite(level) || level < 1) continue;
+
+    const name = nameOf(node);
+    if (previous === null) {
+      if (level > 1) {
+        findings.push({
+          rule: 'heading-order-jump',
+          impact: 'warning',
+          role: 'heading',
+          name: name || null,
+          locator: locatorFor(node, locators),
+          detail: `document outline starts at h${level} — the first heading should be h1`,
+        });
+      }
+    } else if (level > previous + 1) {
+      findings.push({
+        rule: 'heading-order-jump',
+        impact: 'warning',
+        role: 'heading',
+        name: name || null,
+        locator: locatorFor(node, locators),
+        detail: `heading level jumps h${previous} -> h${level}`,
+      });
+    }
+    previous = level;
+  }
+  return findings;
+}
+
+/**
+ * Interactive elements pulled out of the keyboard tab order by a negative
+ * tabindex. They stay clickable with a mouse and stay in the AX tree, so
+ * nothing else in this file can see them — the candidates come from a DOM
+ * sweep in collect.ts.
+ */
+export function findFocusOrderIssues(candidates: FocusCandidate[]): A11yFinding[] {
+  const findings: A11yFinding[] = [];
+  for (const c of candidates) {
+    if (c.tabindex >= 0) continue;
+    const interactive = NATIVELY_FOCUSABLE.has(c.tag.toLowerCase()) || c.role !== '';
+    if (!interactive) continue;
+    findings.push({
+      rule: 'negative-tabindex',
+      impact: 'warning',
+      role: c.role || c.tag.toLowerCase(),
+      name: c.name,
+      locator: c.locator,
+      detail: `<${c.tag.toLowerCase()}> has tabindex="${c.tabindex}" — mouse users can reach it, keyboard users cannot`,
+    });
+  }
+  return findings;
+}
+
+export interface A11yInput {
+  nodes: AxNode[];
+  focusCandidates?: FocusCandidate[];
+  locators?: Map<number, string>;
+}
+
+export function runA11yRules({ nodes, focusCandidates = [], locators }: A11yInput): A11yFinding[] {
+  return [
+    ...findNamingIssues(nodes, locators),
+    ...findHeadingIssues(nodes, locators),
+    ...findFocusOrderIssues(focusCandidates),
+  ];
+}
+
+export function countA11y(findings: A11yFinding[]): { errors: number; warnings: number } {
+  let errors = 0;
+  let warnings = 0;
+  for (const f of findings) {
+    if (f.impact === 'error') errors++;
+    else warnings++;
+  }
+  return { errors, warnings };
+}