pursr 0.4.0 → 0.6.0

package/src/report.js

@@ -0,0 +1,176 @@
+// pursor - PDF report generator.
+//
+// Renders a sweep summary into a styled, self-contained PDF report.
+// Embeds each capture (PNG) inline so the report can be emailed/shared
+// without any external assets.
+//
+// CLI:
+//   pursr report --sweep ./out/sweep-xxx/sweep.json --out ./out/report.pdf
+//   pursr sweep plan.json   # writes sweep.json + .html; PDF generated separately
+//
+// Library:
+//   import { renderSweepPdf } from "pursr/report";
+//   const bytes = await renderSweepPdf(summary, { out: "report.pdf" });
+
+import PDFDocument from "pdfkit";
+import { createReadStream, existsSync, statSync } from "node:fs";
+import { join, dirname, basename } from "node:path";
+import { writeFile } from "node:fs/promises";
+import { escapeHtml } from "./util.js";
+
+// A4 in points (1pt = 1/72 in)
+const PAGE_W = 595.28;
+const PAGE_H = 841.89;
+const MARGIN = 40;
+const CONTENT_W = PAGE_W - MARGIN * 2;
+
+/**
+ * Render a sweep summary as a PDF.
+ *
+ * @param {object} summary       - Sweep summary from runSweep()
+ * @param {object} [opts]
+ * @param {string} [opts.out]    - Output PDF file path
+ * @param {string} [opts.title]  - Report title (defaults to sweep.name)
+ * @param {string} [opts.subtitle] - Subtitle
+ * @param {boolean} [opts.embedImages=true] - Embed each capture PNG inline
+ * @returns {Promise<Buffer>}   - PDF bytes (also written to opts.out if set)
+ */
+export async function renderSweepPdf(summary, opts = {}) {
+  if (!summary || !Array.isArray(summary.steps)) {
+    throw new Error("renderSweepPdf: summary.steps must be an array");
+  }
+  const title = opts.title || `pursr sweep: ${summary.name || "(unnamed)"}`;
+  const subtitle = opts.subtitle || `${summary.steps.length} steps · ${summary.ts || ""} · ${summary.outDir || ""}`;
+  const embedImages = opts.embedImages !== false;
+
+  const doc = new PDFDocument({ size: "A4", margin: MARGIN, info: {
+    Title: title,
+    Author: "pursr",
+    Subject: "Visual sweep report",
+    CreationDate: new Date(),
+  }});
+
+  // Collect bytes
+  const chunks = [];
+  doc.on("data", (c) => chunks.push(c));
+  const done = new Promise((resolve, reject) => {
+    doc.on("end", () => resolve(Buffer.concat(chunks)));
+    doc.on("error", reject);
+  });
+
+  // ---- Header ----
+  doc.fillColor("#0B0B0F").rect(0, 0, PAGE_W, 80).fill();
+  doc.fillColor("#FF2EA6").fontSize(22).font("Helvetica-Bold").text("pursr", MARGIN, 30);
+  doc.fillColor("#FFFFFF").fontSize(14).font("Helvetica").text(title, MARGIN + 70, 36);
+  doc.fillColor("#A0A0AA").fontSize(9).text(subtitle, MARGIN + 70, 56);
+  doc.moveDown(3);
+
+  // ---- Summary stats ----
+  const total = summary.steps.length;
+  const passed = summary.steps.filter((s) => s.ok).length;
+  const failed = total - passed;
+  const totalMs = summary.steps.reduce((acc, s) => acc + (s.ms || 0), 0);
+
+  doc.fillColor("#0B0B0F").font("Helvetica-Bold").fontSize(14).text("Summary", MARGIN, doc.y);
+  doc.moveDown(0.5);
+  const stats = [
+    ["Steps", `${total}`],
+    ["Passed", `${passed}`],
+    ["Failed", `${failed}`],
+    ["Total time", `${(totalMs / 1000).toFixed(1)}s`],
+  ];
+  drawStatGrid(doc, stats, MARGIN, doc.y, CONTENT_W);
+  doc.moveDown(1.5);
+
+  // ---- Per-step results ----
+  for (let i = 0; i < summary.steps.length; i++) {
+    const step = summary.steps[i];
+    // Page break if less than 200pt left
+    if (doc.y > PAGE_H - 200) doc.addPage();
+
+    // Step header
+    const status = step.ok ? "OK" : "FAIL";
+    const statusColor = step.ok ? "#0a8a4a" : "#d03030";
+    doc.fillColor("#0B0B0F").font("Helvetica-Bold").fontSize(12).text(`#${step.i} ${step.name || "step-" + step.i}`, MARGIN, doc.y);
+    doc.fillColor(statusColor).font("Helvetica-Bold").fontSize(10).text(status, MARGIN + CONTENT_W - 40, doc.y - 12, { width: 40, align: "right" });
+    doc.moveDown(0.3);
+    doc.fillColor("#666").font("Helvetica").fontSize(9);
+    const opLine = `${step.op || "?"} · ${step.ms || 0}ms${step.meta?.url ? " · " + step.meta.url : ""}`;
+    doc.text(opLine, MARGIN, doc.y);
+    doc.moveDown(0.3);
+
+    // Embed image
+    if (embedImages) {
+      const img = step.meta?.out || (step.meta?.currentPath);
+      if (img && existsSync(img)) {
+        try {
+          const maxW = CONTENT_W;
+          const maxH = 280;
+          doc.image(img, MARGIN, doc.y, { fit: [maxW, maxH], align: "center" });
+          doc.moveDown(0.5);
+          doc.y += 5;
+        } catch (e) {
+          doc.fillColor("#999").font("Helvetica-Oblique").fontSize(8).text(`[image error: ${e.message}]`, MARGIN, doc.y);
+          doc.moveDown(0.5);
+        }
+      }
+    }
+
+    // Diffs / errors
+    if (step.meta?.numDiff !== undefined) {
+      doc.fillColor("#444").font("Helvetica").fontSize(9);
+      const pct = step.meta.diffPct?.toFixed?.(3) ?? "?";
+      doc.text(`Diff: ${step.meta.numDiff} pixels (${pct}%) differ from reference`, MARGIN, doc.y);
+      doc.moveDown(0.3);
+    }
+    if (!step.ok && step.error) {
+      doc.fillColor("#a01010").font("Helvetica").fontSize(9).text(`Error: ${step.error}`, MARGIN, doc.y);
+      doc.moveDown(0.3);
+    }
+    if (step.meta?.har) {
+      doc.fillColor("#666").font("Helvetica").fontSize(8).text(`HAR: ${step.meta.har}`, MARGIN, doc.y);
+      doc.moveDown(0.3);
+    }
+    if (step.meta?.violations !== undefined) {
+      const v = step.meta.violations || step.meta.violationSummary;
+      const total = typeof v === "object" ? v.total : v;
+      doc.fillColor("#444").font("Helvetica").fontSize(9).text(`Audit: ${total} violations`, MARGIN, doc.y);
+      doc.moveDown(0.3);
+    }
+
+    doc.moveDown(0.8);
+    // Separator
+    doc.strokeColor("#e0e0e8").lineWidth(0.5).moveTo(MARGIN, doc.y).lineTo(MARGIN + CONTENT_W, doc.y).stroke();
+    doc.moveDown(0.5);
+  }
+
+  // ---- Footer ----
+  const range = doc.bufferedPageRange();
+  for (let i = 0; i < range.count; i++) {
+    doc.switchToPage(range.start + i);
+    doc.fillColor("#999").fontSize(8).font("Helvetica");
+    doc.text(`${i + 1} / ${range.count}`, MARGIN, PAGE_H - 30, { width: CONTENT_W, align: "center" });
+    doc.text("Generated by pursr", MARGIN, PAGE_H - 30, { width: CONTENT_W, align: "right" });
+  }
+
+  doc.end();
+  const buf = await done;
+  if (opts.out) {
+    await writeFile(opts.out, buf);
+  }
+  return buf;
+}
+
+function drawStatGrid(doc, items, x, y, w) {
+  const cols = items.length;
+  const cellW = w / cols;
+  for (let i = 0; i < cols; i++) {
+    const [label, value] = items[i];
+    const cx = x + cellW * i;
+    doc.fillColor("#FF2EA6").font("Helvetica-Bold").fontSize(20).text(value, cx, y, { width: cellW - 8, align: "left" });
+    doc.fillColor("#666").font("Helvetica").fontSize(8).text(label, cx, y + 24, { width: cellW - 8, align: "left" });
+  }
+  return y + 50;
+}
+
+export { renderSweepPdf as default };

package/src/snap.js

@@ -0,0 +1,129 @@
+// pursor — component-level snapshot.
+//
+// Capture one screenshot per matched element (Percy / Chromatic style).
+// Uses Playwright's elementHandle.screenshot() to clip precisely to the
+// element's bounding box, even if it scrolls offscreen.
+//
+// CLI:
+//   pursr snap <url> "<selector>" [--out ./snaps/] [--selector "a.btn"]
+//   pursr snap <url> "<selector>" --baseline myapp
+//
+// Library:
+//   import { runSnap } from "pursr/snap";
+//   const result = await runSnap({ url, selector, outDir: "./snaps" });
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { launch, newPage } from "./runway.js";
+import { resolveViewport } from "./viewport.js";
+import { gotoOrThrow, settle, CLICK_TIMEOUT_MS } from "./overlays.js";
+import { resolveLocator, parseTextSelector } from "./selector.js";
+import { resolveHealedSelector } from "./selector-heal.js";
+import { asNum, nowIso, requireArg } from "./util.js";
+import { saveBaseline, diffKey } from "./baseline.js";
+
+/**
+ * Capture one screenshot per matched element on a page.
+ *
+ * @param {object} opts
+ * @param {string} opts.url                    Target URL
+ * @param {string|string[]} opts.selector      CSS selector, or chain (heal-fallback)
+ * @param {string} [opts.outDir=./snaps]      Output directory
+ * @param {string} [opts.name]                 Optional name prefix (defaults to selector slug)
+ * @param {object} [opts.flags]                Viewport/flags (resolved via resolveViewport)
+ * @param {number} [opts.settleMs=400]         Wait after locator resolves
+ * @param {number} [opts.max=20]               Max elements to capture (safety)
+ * @param {boolean} [opts.scrollIntoView=true] Scroll each into view before capture
+ * @param {boolean} [opts.omitBackground=false] Transparent background
+ * @returns {Promise<{ url, selector, count, captures: [...], outDir, ts }>}
+ */
+export async function runSnap(opts) {
+  requireArg("url", opts?.url, "string");
+  requireArg("selector", opts?.selector, "string");
+  const url = opts.url;
+  const selector = opts.selector;
+  const outDir = opts.outDir || "./snaps";
+  const flags = opts.flags || {};
+  const viewport = resolveViewport(flags);
+  const settleMs = asNum(opts.settleMs, 400);
+  const max = Math.max(1, asNum(opts.max, 20));
+  const scrollIntoView = opts.scrollIntoView !== false;
+  const omitBackground = !!opts.omitBackground;
+  const name = opts.name || (Array.isArray(selector) ? selector[0] : selector).replace(/[^a-z0-9]+/gi, "_").replace(/^_+|_+$/g, "").slice(0, 48) || "snap";
+
+  mkdirSync(outDir, { recursive: true });
+  const browser = await launch();
+  const captures = [];
+  try {
+    const page = await newPage(browser, viewport);
+    const r = await gotoOrThrow(page, url);
+    await settle(page);
+
+    // Resolve to a locator (with auto-heal chain support)
+    const locator = Array.isArray(selector)
+      ? (await resolveHealedSelector(page, selector)).locator
+      : await resolveLocator(page, selector);
+
+    const count = await locator.count();
+    if (!count) throw new Error(`snap: selector matched 0 elements`);
+
+    const limit = Math.min(count, max);
+    for (let i = 0; i < limit; i++) {
+      const handle = locator.nth(i);
+      try {
+        if (scrollIntoView) await handle.scrollIntoViewIfNeeded({ timeout: CLICK_TIMEOUT_MS }).catch(() => {});
+        await page.waitForTimeout(settleMs);
+        const file = join(outDir, `${String(i).padStart(2, "0")}-${name}.png`);
+        await handle.screenshot({ path: file, omitBackground });
+        // Try to get a human label
+        let label = null;
+        try {
+          label = (await handle.evaluate((el) => {
+            return el.getAttribute("aria-label")
+              || el.getAttribute("title")
+              || el.getAttribute("alt")
+              || (el.textContent || "").trim().slice(0, 80)
+              || el.tagName.toLowerCase();
+          }));
+        } catch {}
+        captures.push({ i, file, label });
+      } catch (e) {
+        captures.push({ i, error: e.message });
+      }
+    }
+
+    // Write summary
+    const summary = {
+      url,
+      selector,
+      viewport: { width: viewport.width, height: viewport.height, dpr: viewport.dpr },
+      count,
+      captured: captures.length,
+      outDir,
+      captures,
+      ts: nowIso(),
+      nav: { status: r.status, title: r.title },
+    };
+    writeFileSync(join(outDir, "snap.json"), JSON.stringify(summary, null, 2));
+    return summary;
+  } finally {
+    try { await browser.close(); } catch {}
+  }
+}
+
+/**
+ * Save a snap result as baselines (one per captured element).
+ * Useful for "approve all current component screenshots as the new baseline".
+ */
+export async function approveSnapsAsBaselines({ project, snapResult, id }) {
+  if (!snapResult?.captures) throw new Error("approveSnapsAsBaselines: missing snapResult");
+  const _id = id || diffKey({ url: snapResult.url, viewport: snapResult.viewport, flags: {} });
+  const out = [];
+  for (const c of snapResult.captures) {
+    if (c.error || !c.file) continue;
+    const step = `snap-${String(c.i).padStart(2, "0")}-${(c.label || "elem").replace(/[^a-z0-9._-]+/gi, "_").slice(0, 32)}`;
+    const saved = saveBaseline({ project, id: _id, step, png: c.file, meta: { url: snapResult.url, viewport: snapResult.viewport, flags: {} } });
+    out.push(saved);
+  }
+  return out;
+}

package/src/watch.js

@@ -0,0 +1,134 @@
+// pursor - watch mode.
+//
+// Re-runs a shoot/sweep whenever watched files change.
+
+import { watch as fsWatch, existsSync } from "node:fs";
+import { resolve, join, dirname, relative } from "node:path";
+import { runShootWithSidecar } from "./shoot.js";
+import { runSweep } from "./sweep.js";
+import { nowIso } from "./util.js";
+
+function normalizeGlobs(globs) {
+  if (!globs) return null;
+  const arr = Array.isArray(globs) ? globs : [globs];
+  return arr.filter(Boolean);
+}
+
+const BC = String.fromCharCode(92);
+const ESC_RX = /[.+^$X()|YZ\\]/g;
+function escapeForRegex(s) {
+  return s.replace(ESC_RX, function (m) {
+    if (m === "X") return BC + "$";
+    if (m === "Y") return BC + "{";
+    if (m === "Z") return BC + "}";
+    return BC + m;
+  });
+}
+
+function matchGlob(path, pattern) {
+  const p = String(path).split(BC).join("/");
+  const pat = String(pattern);
+  let re = "^";
+  for (let i = 0; i < pat.length; i++) {
+    const c = pat[i];
+    if (c === BC) {
+      const next = pat[i + 1];
+      if (next === undefined) { re += BC + BC; continue; }
+      re += escapeForRegex(next);
+      i++;
+    } else if (c === "*") {
+      if (pat[i + 1] === "*") { re += ".*"; i++; }
+      else { re += "[^/]*"; }
+    } else if (c === "?") {
+      re += "[^/]";
+    } else {
+      re += escapeForRegex(c);
+    }
+  }
+  re += "$";
+  return new RegExp(re).test(p);
+}
+
+function shouldFire(path, globs) {
+  if (!globs || globs.length === 0) return true;
+  return globs.some((g) => matchGlob(path, g));
+}
+
+function debounce(fn, ms) {
+  let t = null;
+  return (...args) => {
+    if (t) clearTimeout(t);
+    t = setTimeout(() => { t = null; fn(...args); }, ms);
+  };
+}
+
+export async function startWatch(opts) {
+  if (!opts.url && !opts.plan) throw new Error("startWatch: requires url or plan");
+  const globs = normalizeGlobs(opts.on);
+  const debounceMs = opts.debounceMs ?? 300;
+  const verbose = !!opts.verbose;
+
+  let fireCount = 0;
+  let runningPromise = Promise.resolve();
+  let closed = false;
+
+  const runOne = async (event) => {
+    if (closed) return;
+    fireCount++;
+    try {
+      let capture = null;
+      if (opts.plan) {
+        capture = await runSweep(opts.plan, opts.outDir);
+      } else {
+        capture = await runShootWithSidecar({ url: opts.url, out: opts.out, flags: opts.flags || {} });
+      }
+      if (typeof opts.onChange === "function") {
+        try { await opts.onChange({ ...event, capture }); } catch (e) {
+          if (verbose) console.error("[pursr watch] onChange error:", e.message);
+        }
+      }
+    } catch (e) {
+      if (verbose) console.error("[pursr watch] capture error:", e.message);
+    }
+  };
+
+  const debouncedRun = debounce((event) => { runningPromise = runningPromise.then(() => runOne(event)); }, debounceMs);
+
+  const targets = globs && globs.length > 0
+    ? globs.map((g) => {
+        const lit = g.split(/[*?]/)[0];
+        return resolve(lit || ".");
+      })
+    : [resolve(process.cwd())];
+
+  const watchers = [];
+  for (const target of targets) {
+    if (!existsSync(target)) continue;
+    try {
+      const w = fsWatch(target, { recursive: true }, (eventType, filename) => {
+        if (!filename) return;
+        const full = join(target, filename);
+        const rel = relative(process.cwd(), full).split(BC).join("/");
+        if (!shouldFire(rel, globs)) return;
+        debouncedRun({ type: eventType, path: full, ts: nowIso() });
+      });
+      w.on("error", (e) => { if (verbose) console.error("[pursr watch] watcher error:", e.message); });
+      watchers.push(w);
+    } catch (e) {
+      if (verbose) console.error("[pursr watch] cannot watch", target, e.message);
+    }
+  }
+
+  runningPromise = runningPromise.then(() => runOne({ type: "init", path: null, ts: nowIso() }));
+
+  return {
+    close: async () => {
+      closed = true;
+      for (const w of watchers) { try { w.close(); } catch {} }
+      await runningPromise.catch(() => {});
+    },
+    fires: () => fireCount,
+  };
+}
+
+export { matchGlob, shouldFire };