@monoes/monobrowse 1.0.12 → 1.0.13

package/src/report/history.ts

@@ -0,0 +1,219 @@
+/**
+ * Persistent run history for `monobrowse report` (RIG-13).
+ *
+ * Every run is appended to a per-URL directory under the monomind data dir,
+ * so the next run can say "LCP has crept up 400ms over nine runs" instead of
+ * reporting a number with no context. Deliberately not a database: one JSON
+ * file per run plus its screenshot is greppable, diffable, rsync-able, and
+ * survives this tool being uninstalled.
+ *
+ *   ~/.monomind/browser-reports/
+ *     shop.test-checkout-1f4c9a2b/
+ *       url.txt                              <- the full URL, for humans
+ *       20260921T100000Z-8f2a1c4d.json       <- HistoryRun
+ *       20260921T100000Z-8f2a1c4d.png        <- main screenshot, for the diff
+ *
+ * Set `MONOBROWSE_HISTORY_DIR` to relocate the root (the tests do).
+ */
+
+import { createHash, randomBytes } from 'node:crypto';
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { pngFromDataUrl } from './png.js';
+import type { ImageSize, Report, StructureNode, VerdictValue, VitalsData } from './types.js';
+
+/** Runs kept per URL before the oldest are pruned. Override with --history-max. */
+export const DEFAULT_HISTORY_MAX = 20;
+
+/**
+ * Screenshots above this are not archived for the diff. A 30MB full-page PNG
+ * per run would turn a 20-run history into 600MB on someone's laptop, and the
+ * pixel diff is the only consumer.
+ */
+const MAX_ARCHIVED_SCREENSHOT_BYTES = 8 * 1024 * 1024;
+
+export interface HistoryRun {
+  /** `<compact ISO timestamp>-<8 hex>`, also the basename of its files. */
+  id: string;
+  url: string;
+  finalUrl: string;
+  title: string;
+  capturedAt: string;
+  durationMs: number;
+  verdict: VerdictValue;
+  counts: Report['counts'];
+  vitals: VitalsData;
+  failures: Array<{ budget: string; expected: string; actual: string }>;
+  /** `<rule>@<locator>` per finding, so a11y regressions are attributable. */
+  a11ySignatures: string[];
+  structure: StructureNode[];
+  /** Basename of the sibling PNG, when one was archived. */
+  screenshotFile?: string;
+  screenshotSize?: ImageSize;
+}
+
+export function historyRoot(): string {
+  const override = process.env.MONOBROWSE_HISTORY_DIR;
+  if (override?.trim()) return override.trim();
+  return join(homedir(), '.monomind', 'browser-reports');
+}
+
+/**
+ * Directory name for a URL: readable prefix plus a hash of the full URL.
+ *
+ * The hash is what makes it correct — `?page=2` and `?page=3` must not share
+ * a history — and the prefix is what makes `ls` useful.
+ */
+export function historyKey(url: string): string {
+  const hash = createHash('sha256').update(url).digest('hex').slice(0, 8);
+  let readable: string;
+  try {
+    const parsed = new URL(url);
+    const path = parsed.pathname.replace(/\/+$/, '').replace(/[^a-z0-9]+/gi, '-');
+    readable = `${parsed.hostname}${path}`;
+  } catch {
+    readable = url.replace(/[^a-z0-9]+/gi, '-');
+  }
+  readable = readable.replace(/-+/g, '-').replace(/^-|-$/g, '').toLowerCase().slice(0, 60);
+  return `${readable || 'page'}-${hash}`;
+}
+
+export function historyDirFor(url: string, root = historyRoot()): string {
+  return join(root, historyKey(url));
+}
+
+export function compactTimestamp(iso: string): string {
+  return iso.replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z');
+}
+
+export function newRunId(capturedAt: string): string {
+  return `${compactTimestamp(capturedAt)}-${randomBytes(4).toString('hex')}`;
+}
+
+/** The record we persist — a Report minus the megabytes of inline base64. */
+export function toHistoryRun(report: Report, id: string): HistoryRun {
+  return {
+    id,
+    url: report.url,
+    finalUrl: report.finalUrl,
+    title: report.title,
+    capturedAt: report.capturedAt,
+    durationMs: report.durationMs,
+    verdict: report.verdict,
+    counts: report.counts,
+    vitals: report.vitals,
+    failures: report.failures.map((f) => ({
+      budget: String(f.budget),
+      expected: f.expected,
+      actual: f.actual,
+    })),
+    a11ySignatures: report.a11y.map((f) => `${f.rule}@${f.locator}`),
+    structure: report.structure ?? [],
+  };
+}
+
+const RUN_FILE = /^(\d{8}T\d{6}Z)-([0-9a-f]{8})\.json$/;
+
+/**
+ * Every run for a URL, oldest first.
+ *
+ * A file that will not parse is skipped rather than thrown: a half-written
+ * record from a killed process must not permanently break the next report.
+ */
+export async function listRuns(dir: string): Promise<HistoryRun[]> {
+  let names: string[];
+  try {
+    names = await readdir(dir);
+  } catch {
+    return [];
+  }
+  const runs: HistoryRun[] = [];
+  for (const name of names.filter((n) => RUN_FILE.test(n)).sort()) {
+    try {
+      const parsed = JSON.parse(await readFile(join(dir, name), 'utf8')) as HistoryRun;
+      if (parsed && typeof parsed.capturedAt === 'string') runs.push(parsed);
+    } catch {
+      // Unreadable record — ignore it and carry on.
+    }
+  }
+  return runs.sort((a, b) => a.capturedAt.localeCompare(b.capturedAt));
+}
+
+/** Delete all but the newest `max` runs, taking each one's PNG with it. */
+export async function pruneHistory(dir: string, max: number): Promise<string[]> {
+  if (!Number.isFinite(max) || max <= 0) return [];
+  const runs = await listRuns(dir);
+  if (runs.length <= max) return [];
+  const doomed = runs.slice(0, runs.length - max);
+  const removed: string[] = [];
+  for (const run of doomed) {
+    for (const file of [`${run.id}.json`, run.screenshotFile]) {
+      if (!file) continue;
+      await rm(join(dir, file), { force: true }).catch(() => {});
+      removed.push(file);
+    }
+  }
+  return removed;
+}
+
+export interface SaveRunOptions {
+  root?: string;
+  max?: number;
+  /** Fixed id, for deterministic tests. */
+  id?: string;
+}
+
+export interface SaveRunResult {
+  dir: string;
+  file: string;
+  run: HistoryRun;
+  pruned: string[];
+}
+
+/**
+ * Append this run to its URL's history and prune the tail. Callers treat a
+ * rejection as non-fatal — a read-only home directory should cost you the
+ * trend section, not the report.
+ */
+export async function saveRun(
+  report: Report,
+  options: SaveRunOptions = {},
+): Promise<SaveRunResult> {
+  const root = options.root ?? historyRoot();
+  const dir = join(root, historyKey(report.url));
+  await mkdir(dir, { recursive: true });
+  await writeFile(join(dir, 'url.txt'), `${report.url}\n`, 'utf8').catch(() => {});
+
+  const id = options.id ?? newRunId(report.capturedAt);
+  const run = toHistoryRun(report, id);
+
+  const main = report.screenshots.find((s) => s.label === 'page') ?? report.screenshots[0];
+  if (main?.dataUrl) {
+    try {
+      const bytes = pngFromDataUrl(main.dataUrl);
+      if (bytes.length <= MAX_ARCHIVED_SCREENSHOT_BYTES) {
+        const file = `${id}.png`;
+        await writeFile(join(dir, file), bytes);
+        run.screenshotFile = file;
+        run.screenshotSize = { width: main.width, height: main.height };
+      }
+    } catch {
+      // No archived screenshot means no pixel diff next run. Not fatal.
+    }
+  }
+
+  const file = join(dir, `${id}.json`);
+  await writeFile(file, `${JSON.stringify(run, null, 2)}\n`, 'utf8');
+  const pruned = await pruneHistory(dir, options.max ?? DEFAULT_HISTORY_MAX);
+  return { dir, file, run, pruned };
+}
+
+export async function loadRunScreenshot(dir: string, run: HistoryRun): Promise<Uint8Array | null> {
+  if (!run.screenshotFile) return null;
+  try {
+    return new Uint8Array(await readFile(join(dir, run.screenshotFile)));
+  } catch {
+    return null;
+  }
+}

package/src/report/index.ts

@@ -0,0 +1,307 @@
+/**
+ * `monobrowse report <url>` — open a page, measure it, judge it against a
+ * budget, and leave behind one self-contained HTML file plus a sibling JSON.
+ *
+ * collect.ts (drive the browser) -> analyze.ts (a11y + budgets -> verdict)
+ * -> history/trend/diff (what changed since last time) -> render.ts (HTML).
+ * This module is the seam that wires them together and writes the two files.
+ */
+
+import { mkdir, stat, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import type { CdpClient } from '../browser/cdp.js';
+import { buildReport, summarizeVerdict } from './analyze.js';
+import { loadBudget } from './budget.js';
+import type { CollectOptions } from './collect.js';
+import { collect } from './collect.js';
+import { buildEvidence } from './evidence.js';
+import { analyzeFlake, type FlakeReport, summarizeFlake } from './flake.js';
+import {
+  DEFAULT_HISTORY_MAX,
+  type HistoryRun,
+  historyDirFor,
+  historyRoot,
+  listRuns,
+  saveRun,
+} from './history.js';
+import { renderHtml } from './render.js';
+import { buildRunDiff } from './run-diff.js';
+import { buildTrend } from './trend.js';
+import type { Budget, CaptureData, Report } from './types.js';
+
+export * from './a11y.js';
+export * from './analyze.js';
+export * from './budget.js';
+export * from './collect.js';
+export * from './collect-a11y.js';
+export * from './evidence.js';
+export * from './flake.js';
+export * from './history.js';
+export * from './pixel-diff.js';
+export * from './png.js';
+export * from './render.js';
+export * from './run-diff.js';
+export * from './structure.js';
+export * from './trend.js';
+export * from './types.js';
+
+/** Prior runs a trend is charted over. Older runs stay on disk, off the chart. */
+export const DEFAULT_TREND_WINDOW = 10;
+
+export interface RunReportOptions extends CollectOptions {
+  /** Output path: a `.html` file, or a directory to drop the default name in. */
+  out?: string;
+  /** Budget file path or inline JSON. Omitted means DEFAULT_BUDGET. */
+  budget?: string | Budget;
+  cwd?: string;
+  /** Persist this run and compare against previous ones. Default true. */
+  history?: boolean;
+  /** Runs kept per URL. Default DEFAULT_HISTORY_MAX. */
+  historyMax?: number;
+  /** Root of the history store. Default `~/.monomind/browser-reports`. */
+  historyDir?: string;
+  /** Prior runs charted. Default DEFAULT_TREND_WINDOW. */
+  trendWindow?: number;
+}
+
+export interface ReportResult {
+  report: Report;
+  htmlPath: string;
+  jsonPath: string;
+  summary: string;
+  /** Present when the run was saved to the history store. */
+  historyDir?: string;
+  /** Present only for a `--repeat` run (RIG-14); see RepeatResult. */
+  flake?: FlakeReport;
+}
+
+function slugFor(url: string): string {
+  try {
+    const parsed = new URL(url);
+    const path = parsed.pathname.replace(/\/+$/, '').replace(/[^a-z0-9]+/gi, '-');
+    return `${parsed.hostname}${path}`.replace(/-+/g, '-').replace(/^-|-$/g, '').toLowerCase();
+  } catch {
+    return (
+      url
+        .replace(/[^a-z0-9]+/gi, '-')
+        .replace(/^-|-$/g, '')
+        .toLowerCase() || 'page'
+    );
+  }
+}
+
+function timestamp(iso: string): string {
+  return iso.replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z');
+}
+
+/**
+ * Resolve `--out` into an absolute .html path. A path that is an existing
+ * directory, or that ends in a separator, gets the generated filename
+ * appended — `--out ./reports` should not silently produce a file called
+ * `reports`.
+ */
+export async function resolveOutPath(
+  out: string | undefined,
+  url: string,
+  capturedAt: string,
+  cwd: string,
+): Promise<string> {
+  const defaultName = `monobrowse-report-${slugFor(url)}-${timestamp(capturedAt)}.html`;
+  if (!out) return join(cwd, defaultName);
+
+  const abs = isAbsolute(out) ? out : resolve(cwd, out);
+  if (/[\\/]$/.test(out)) return join(abs, defaultName);
+  const isDir = await stat(abs)
+    .then((s) => s.isDirectory())
+    .catch(() => false);
+  if (isDir) return join(abs, defaultName);
+  return abs.toLowerCase().endsWith('.html') || abs.toLowerCase().endsWith('.htm')
+    ? abs
+    : `${abs}.html`;
+}
+
+/**
+ * The JSON sibling drops the base64 image payloads — they are megabytes of
+ * noise for anything reading this programmatically, and the HTML already
+ * carries them inline. `path` still points at the PNG on disk. The pixel
+ * diff's highlight image and the evidence frames go the same way: every
+ * measurement survives, only the pixels are dropped.
+ */
+export function toJsonReport(report: Report): Record<string, unknown> {
+  const { screenshots, recording, diff, evidence, ...rest } = report;
+  void recording;
+  return {
+    ...rest,
+    screenshots: screenshots.map(({ label, width, height, path }) => ({
+      label,
+      width,
+      height,
+      path,
+    })),
+    ...(diff
+      ? {
+          diff: {
+            ...diff,
+            pixels: diff.pixels ? { ...diff.pixels, diffDataUrl: undefined } : undefined,
+          },
+        }
+      : {}),
+    ...(evidence
+      ? {
+          evidence: {
+            ...evidence,
+            frames: evidence.frames.map(({ offsetMs, bytes }) => ({ offsetMs, bytes })),
+          },
+        }
+      : {}),
+  };
+}
+
+export async function writeReportFiles(
+  report: Report,
+  htmlPath: string,
+  extras: { flake?: FlakeReport } = {},
+): Promise<{ htmlPath: string; jsonPath: string }> {
+  const jsonPath = `${htmlPath.replace(/\.html?$/i, '')}.json`;
+  await mkdir(dirname(htmlPath), { recursive: true });
+  await writeFile(htmlPath, renderHtml(report, extras), 'utf8');
+  const json = extras.flake
+    ? { ...toJsonReport(report), flake: extras.flake }
+    : toJsonReport(report);
+  await writeFile(jsonPath, `${JSON.stringify(json, null, 2)}\n`, 'utf8');
+  return { htmlPath, jsonPath };
+}
+
+/**
+ * Attach the trend and the diff, then persist the run.
+ *
+ * Order matters: history is read BEFORE the run is saved, so a run never
+ * trends or diffs against itself. A failure anywhere in here becomes a note
+ * on the report rather than an error — an unwritable home directory should
+ * cost you the trend section, not the report.
+ */
+async function applyHistory(
+  report: Report,
+  options: RunReportOptions,
+): Promise<string | undefined> {
+  if (options.history === false) return undefined;
+  const root = options.historyDir ?? historyRoot();
+  const dir = historyDirFor(report.url, root);
+  try {
+    const previous = await listRuns(dir);
+    const window = options.trendWindow ?? DEFAULT_TREND_WINDOW;
+    report.trend = buildTrend(report, previous.slice(-window));
+    report.diff = await buildRunDiff(dir, previous.at(-1), report);
+    await saveRun(report, { root, max: options.historyMax ?? DEFAULT_HISTORY_MAX });
+    return dir;
+  } catch (err) {
+    report.notes.push(
+      `Run history unavailable (${(err as Error).message}) — no trend or diff for this run.`,
+    );
+    return undefined;
+  }
+}
+
+/** Turn the recorder's raw frames into the evidence block, when warranted. */
+function applyEvidence(report: Report, data: CaptureData): void {
+  const recording = data.recording;
+  if (!recording) return;
+  if (report.verdict !== 'fail' && !recording.requested) return;
+  report.evidence = buildEvidence({
+    reason: report.verdict === 'fail' ? 'budget-failure' : 'requested',
+    startedAtMs: recording.startedAtMs,
+    frames: recording.frames,
+    bufferDropped: recording.droppedFrames,
+    console: report.console,
+    pageErrors: report.pageErrors,
+    requests: report.requests,
+    failures: report.failures,
+  });
+}
+
+async function resolveBudget(options: RunReportOptions): Promise<Budget> {
+  return options.budget && typeof options.budget === 'object'
+    ? options.budget
+    : await loadBudget(options.budget as string | undefined);
+}
+
+/** One run: collect, judge, compare against history, write the two files. */
+export async function runReport(
+  client: CdpClient,
+  sessionId: string,
+  options: RunReportOptions,
+): Promise<ReportResult> {
+  const budget = await resolveBudget(options);
+  const data: CaptureData = await collect(client, sessionId, options);
+  const report = buildReport(data, budget);
+
+  applyEvidence(report, data);
+  const historyDir = await applyHistory(report, options);
+  // Working material, not report content — and megabytes of it.
+  report.recording = undefined;
+
+  const htmlPath = await resolveOutPath(
+    options.out,
+    options.url,
+    data.capturedAt,
+    options.cwd ?? process.cwd(),
+  );
+  const paths = await writeReportFiles(report, htmlPath);
+  return { report, ...paths, summary: summarizeVerdict(report), historyDir };
+}
+
+export interface RepeatResult extends ReportResult {
+  flake: FlakeReport;
+  /** Every run, in order. `report` is the last of them. */
+  reports: Report[];
+}
+
+/**
+ * `--repeat N`: run the same URL N times and judge the set (RIG-14).
+ *
+ * Only the last run is written out in full — N runs' worth of inlined
+ * screenshots is not something anyone wants on disk — but the flake analysis
+ * covers all of them, and it is the flake verdict that decides the exit code.
+ * A check that passed three times and failed twice must not exit 0.
+ */
+export async function runReportRepeated(
+  client: CdpClient,
+  sessionId: string,
+  options: RunReportOptions & { repeat: number },
+): Promise<RepeatResult> {
+  const times = Math.max(1, Math.floor(options.repeat));
+  const budget = await resolveBudget(options);
+  const reports: Report[] = [];
+
+  for (let i = 0; i < times; i++) {
+    const data = await collect(client, sessionId, options);
+    const report = buildReport(data, budget);
+    applyEvidence(report, data);
+    report.recording = undefined;
+    reports.push(report);
+  }
+
+  const flake = analyzeFlake(reports);
+  const report = reports[reports.length - 1];
+  // Only the run we keep is persisted: writing N history entries for one
+  // command would let a single `--repeat 20` evict the whole trend window.
+  const historyDir = await applyHistory(report, options);
+
+  const htmlPath = await resolveOutPath(
+    options.out,
+    options.url,
+    report.capturedAt,
+    options.cwd ?? process.cwd(),
+  );
+  const paths = await writeReportFiles(report, htmlPath, { flake });
+  return { report, reports, flake, ...paths, summary: summarizeFlake(flake), historyDir };
+}
+
+/** `--history <url>`: the stored runs for a URL, oldest first. */
+export async function readHistory(
+  url: string,
+  options: { historyDir?: string } = {},
+): Promise<{ dir: string; runs: HistoryRun[] }> {
+  const dir = historyDirFor(url, options.historyDir ?? historyRoot());
+  return { dir, runs: await listRuns(dir) };
+}