harnery 0.32.0 → 0.34.0

package/src/lib/browser/qa-reuse.ts

@@ -0,0 +1,306 @@
+// Visual-result reuse for critique tiles (plan 3.3): avoid re-judging pixels
+// that did not change.
+//
+// Two mechanisms share this module; which is primary was decided by the
+// Stage 0 byte-stability experiment, not preference:
+//
+//   Path B (primary): band-level pixel diff. Compare each candidate tile's
+//   document-space rect in the CURRENT full-page screenshot against the SAME
+//   rect in the persisted baseline screenshot (qa-snapshot.ts), with
+//   pixelmatch's anti-aliasing tolerance. At or below a strict mismatch
+//   ratio (default 0.001), the tile region provably didn't change and the
+//   provider call is skipped. No byte identity required, so font
+//   rasterization and raster-path drift don't defeat it.
+//
+//   Path A (observe mode: key computation + logging only): the Stage 0
+//   byte-stability experiment PASSED its gate (100% cross-restart identical
+//   bands on real pages, same-day/same-machine, deterministic settle), so an
+//   exact-digest cache is viable — but Path B subsumes its win (a
+//   byte-identical band pixel-diffs at ratio 0) with zero extra storage, so
+//   only the versioned cache key ships until telemetry shows a payoff Path B
+//   misses (e.g. cross-target tile sharing).
+//
+// Hard rules, both paths: never convert a prior failure into a pass — any
+// baseline finding overlapping a tile's region forces a fresh review; a
+// missing/invalid baseline, changed rubric, or changed critique contract is
+// a miss, never an error.
+
+import { createHash } from "node:crypto";
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+import type { CritiqueFinding, CritiqueTile } from "./critique.js";
+import { fnv1a32 } from "./qa-plan.js";
+
+/** Bump when the critique request/response contract changes in a way that
+ * invalidates persisted findings (rubric semantics, finding schema, tiling
+ * geometry meaning). Part of every cache key and persisted critique. */
+export const QA_CRITIQUE_CONTRACT_VERSION = 1;
+
+/** Default Path B mismatch-ratio threshold. Strict on purpose: reuse trades
+ * essentially nothing for robustness against rasterization noise, and a
+ * looser threshold could hide a sub-threshold real change. */
+export const DEFAULT_REUSE_MISMATCH_RATIO = 0.001;
+
+/** Critique results persisted beside a QA snapshot, enough to decide reuse
+ * later: findings plus the geometry they were judged under. */
+export interface PersistedCritique {
+  contract_version: number;
+  /** fnv1a32 of the exact rubric text the findings were judged under. */
+  rubric_digest: string;
+  outcome: "pass" | "fail";
+  findings: CritiqueFinding[];
+  tiles: Array<{
+    index: number;
+    label: string;
+    x: number;
+    scrollY: number;
+    width: number;
+    height: number;
+  }>;
+}
+
+/** Versioned, canonicalized Path A cache key (observe mode). Field order is
+ * part of the contract — never reorder without bumping the version. */
+export function qaTileCacheKey(parts: {
+  tilePngSha256: string;
+  rubricDigest: string;
+  provider: string;
+  model: string;
+  viewport: string;
+  deviceScaleFactor: number;
+  theme: string;
+  state: string;
+  tileLabel: string;
+  browserVersion?: string;
+}): string {
+  const canonical = [
+    `v${QA_CRITIQUE_CONTRACT_VERSION}`,
+    `png:${parts.tilePngSha256}`,
+    `rubric:${parts.rubricDigest}`,
+    `provider:${parts.provider}`,
+    `model:${parts.model}`,
+    `viewport:${parts.viewport}`,
+    `dpr:${parts.deviceScaleFactor}`,
+    `theme:${parts.theme}`,
+    `state:${parts.state}`,
+    `tile:${parts.tileLabel}`,
+    `browser:${parts.browserVersion ?? "unknown"}`,
+  ].join("\x1f");
+  return `qa1-${createHash("sha256").update(canonical).digest("hex")}`;
+}
+
+export function sha256Hex(buf: Buffer | Uint8Array): string {
+  return createHash("sha256").update(buf).digest("hex");
+}
+
+export function rubricDigest(rubric: string): string {
+  // Whitespace-normalized so formatting-only edits don't invalidate reuse.
+  return fnv1a32(rubric.replace(/\s+/g, " ").trim());
+}
+
+function cropRegion(
+  png: PNG,
+  rect: { x: number; y: number; width: number; height: number },
+): PNG | null {
+  const sx = Math.max(0, Math.min(Math.round(rect.x), png.width - 1));
+  const sy = Math.max(0, Math.min(Math.round(rect.y), png.height - 1));
+  const w = Math.min(Math.round(rect.width), png.width - sx);
+  const h = Math.min(Math.round(rect.height), png.height - sy);
+  if (w <= 0 || h <= 0) return null;
+  const out = new PNG({ width: w, height: h });
+  for (let row = 0; row < h; row++) {
+    const srcStart = ((sy + row) * png.width + sx) * 4;
+    png.data.copy(out.data, row * w * 4, srcStart, srcStart + w * 4);
+  }
+  return out;
+}
+
+/**
+ * Pixel-compare one document-space rect across two full-page screenshots.
+ * `sizeMismatch` is true when the rect isn't fully comparable in both images
+ * (page grew/shrank past it) — the caller treats that as changed.
+ */
+export function rectMismatch(
+  baselineFullPage: PNG,
+  currentFullPage: PNG,
+  rect: { x: number; y: number; width: number; height: number },
+  opts: { pixelThreshold?: number } = {},
+): { ratio: number; comparablePixels: number; sizeMismatch: boolean } {
+  const base = cropRegion(baselineFullPage, rect);
+  const cur = cropRegion(currentFullPage, rect);
+  if (!base || !cur || base.width !== cur.width || base.height !== cur.height) {
+    return { ratio: 1, comparablePixels: 0, sizeMismatch: true };
+  }
+  const mismatched = pixelmatch(base.data, cur.data, undefined, base.width, base.height, {
+    threshold: opts.pixelThreshold ?? 0.1,
+    includeAA: false,
+  });
+  const total = base.width * base.height;
+  return { ratio: mismatched / total, comparablePixels: total, sizeMismatch: false };
+}
+
+export interface TileReuseDecision {
+  index: number;
+  label: string;
+  reuse: boolean;
+  reason: string;
+  /** Rect mismatch ratio, present when a pixel comparison ran. */
+  mismatch_ratio?: number;
+}
+
+export interface CritiqueReusePlan {
+  mode: "band-diff";
+  /** Tiles that must be reviewed fresh, in original order. */
+  review: CritiqueTile[];
+  decisions: TileReuseDecision[];
+  tiles_total: number;
+  tiles_reused: number;
+  tiles_reviewed: number;
+  provider_calls_avoided: number;
+  mismatch_threshold: number;
+  /** Set when the whole baseline was unusable (everything reviews fresh). */
+  invalidation?: string;
+}
+
+function wholeRunMiss(
+  tiles: CritiqueTile[],
+  threshold: number,
+  invalidation: string,
+): CritiqueReusePlan {
+  return {
+    mode: "band-diff",
+    review: tiles,
+    decisions: tiles.map((t) => ({
+      index: t.index,
+      label: t.label,
+      reuse: false,
+      reason: invalidation,
+    })),
+    tiles_total: tiles.length,
+    tiles_reused: 0,
+    tiles_reviewed: tiles.length,
+    provider_calls_avoided: 0,
+    mismatch_threshold: threshold,
+    invalidation,
+  };
+}
+
+/**
+ * Path B reuse plan: decide per tile whether the baseline run's verdict still
+ * covers it. A tile is reused ONLY when (a) the baseline is valid for this
+ * rubric and contract, (b) no baseline finding overlaps the tile's document
+ * region (a prior failure is never converted into a pass), and (c) its rect
+ * pixel-matches the baseline screenshot at or below the strict threshold.
+ * Everything else reviews fresh — reuse can produce false REVIEWS, never
+ * false passes.
+ */
+export function planCritiqueReuse(args: {
+  baselineScreenshot: Buffer;
+  baselineCritique: PersistedCritique;
+  currentScreenshot: Buffer;
+  tiles: CritiqueTile[];
+  rubric: string;
+  mismatchThreshold?: number;
+}): CritiqueReusePlan {
+  const threshold = args.mismatchThreshold ?? DEFAULT_REUSE_MISMATCH_RATIO;
+  const { baselineCritique, tiles } = args;
+  if (baselineCritique.outcome !== "pass") {
+    return wholeRunMiss(tiles, threshold, "baseline critique did not pass");
+  }
+  if (baselineCritique.contract_version !== QA_CRITIQUE_CONTRACT_VERSION) {
+    return wholeRunMiss(
+      tiles,
+      threshold,
+      `baseline critique contract v${baselineCritique.contract_version} != v${QA_CRITIQUE_CONTRACT_VERSION}`,
+    );
+  }
+  if (baselineCritique.rubric_digest !== rubricDigest(args.rubric)) {
+    return wholeRunMiss(tiles, threshold, "rubric changed since the baseline run");
+  }
+  let baselinePng: PNG;
+  let currentPng: PNG;
+  try {
+    baselinePng = PNG.sync.read(args.baselineScreenshot);
+    currentPng = PNG.sync.read(args.currentScreenshot);
+  } catch {
+    return wholeRunMiss(tiles, threshold, "unreadable baseline or current screenshot");
+  }
+
+  // Document regions of baseline tiles that produced findings.
+  const findingTiles = new Set(baselineCritique.findings.map((f) => f.tile));
+  const dirtyRegions = baselineCritique.tiles
+    .filter((t) => findingTiles.has(t.index))
+    .map((t) => ({ top: t.scrollY, bottom: t.scrollY + t.height }));
+
+  const decisions: TileReuseDecision[] = [];
+  const review: CritiqueTile[] = [];
+  for (const tile of tiles) {
+    const top = tile.scrollY;
+    const bottom = tile.scrollY + tile.height;
+    const left = tile.x ?? 0;
+    const right = left + tile.width;
+    const coverage = baselineCritique.tiles
+      .filter((prior) => prior.x <= left && prior.x + prior.width >= right)
+      .map((prior) => ({ top: prior.scrollY, bottom: prior.scrollY + prior.height }))
+      .sort((a, b) => a.top - b.top);
+    let coveredTo = top;
+    for (const region of coverage) {
+      if (region.bottom <= coveredTo || region.top > coveredTo) continue;
+      coveredTo = Math.max(coveredTo, region.bottom);
+      if (coveredTo >= bottom) break;
+    }
+    if (coveredTo < bottom) {
+      decisions.push({
+        index: tile.index,
+        label: tile.label,
+        reuse: false,
+        reason: "baseline critique did not cover this entire region",
+      });
+      review.push(tile);
+      continue;
+    }
+    const overlapsFinding = dirtyRegions.some((r) => r.top < bottom && r.bottom > top);
+    if (overlapsFinding) {
+      decisions.push({
+        index: tile.index,
+        label: tile.label,
+        reuse: false,
+        reason: "baseline run had findings in this region — always re-reviewed",
+      });
+      review.push(tile);
+      continue;
+    }
+    const rect = { x: tile.x ?? 0, y: tile.scrollY, width: tile.width, height: tile.height };
+    const cmp = rectMismatch(baselinePng, currentPng, rect);
+    if (cmp.sizeMismatch || cmp.ratio > threshold) {
+      decisions.push({
+        index: tile.index,
+        label: tile.label,
+        reuse: false,
+        reason: cmp.sizeMismatch
+          ? "region not comparable across screenshots (layout size changed)"
+          : `mismatch ratio ${cmp.ratio.toFixed(6)} > ${threshold}`,
+        mismatch_ratio: cmp.sizeMismatch ? undefined : cmp.ratio,
+      });
+      review.push(tile);
+      continue;
+    }
+    decisions.push({
+      index: tile.index,
+      label: tile.label,
+      reuse: true,
+      reason: `clean region pixel-matched baseline (ratio ${cmp.ratio.toFixed(6)})`,
+      mismatch_ratio: cmp.ratio,
+    });
+  }
+  return {
+    mode: "band-diff",
+    review,
+    decisions,
+    tiles_total: tiles.length,
+    tiles_reused: tiles.length - review.length,
+    tiles_reviewed: review.length,
+    provider_calls_avoided: tiles.length - review.length,
+    mismatch_threshold: threshold,
+  };
+}

package/src/lib/browser/qa-snapshot.ts

@@ -0,0 +1,223 @@
+// Persisted QA snapshots: the baseline source that makes repeat QA cheap.
+//
+// Every passing QA run persists its final page signature (and optionally the
+// serialized DOM + full-page screenshot) per render context. The next run
+// inherits its baseline for free instead of re-rendering production or a git
+// revision. Resolution order (the plan's 2.6):
+//   1. persisted QA snapshot   (this store)
+//   2. production render       (caller-supplied fallback)
+//   3. baseline-revision render (caller-supplied fallback, from a worktree)
+//   4. none                    → classification is `unknown`, never text-only
+//
+// Storage is content-under-a-key, like visual-diff baselines: a directory per
+// target, a subdirectory per context, atomic writes (tmp + rename) so a
+// crashed writer never leaves a half-baseline the next run would trust.
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { fnv1a32, type QaContext, type QaSignature } from "./qa-plan.js";
+import type { PersistedCritique } from "./qa-reuse.js";
+
+const SNAPSHOT_DIR = resolve(homedir(), ".cache", "harnery", "qa-snapshots");
+
+export interface QaSnapshotStoreOptions {
+  /** Override the store root (tests, host-managed cache locations). */
+  root?: string;
+}
+
+export interface StoredQaSnapshot {
+  signature: QaSignature;
+  /** Directory holding this snapshot's files. */
+  path: string;
+  domHtmlPath?: string;
+  screenshotPath?: string;
+  /** Critique results persisted with the snapshot (full-coverage runs only) —
+   * what the band-diff reuse layer replays for provably-unchanged regions. */
+  critique?: PersistedCritique;
+}
+
+/** Filesystem-safe key for a target URL/file + render context. The digest
+ * disambiguates targets whose sanitized slugs collide. */
+export function qaSnapshotKey(target: string): string {
+  const source = target.replace(/^[a-z]+:\/\//i, "");
+  let slug = "";
+  let separatorPending = false;
+  for (let index = 0; index < source.length && slug.length < 80; index++) {
+    const code = source.charCodeAt(index);
+    const alpha = (code >= 65 && code <= 90) || (code >= 97 && code <= 122);
+    const digit = code >= 48 && code <= 57;
+    if (alpha || digit) {
+      if (separatorPending && slug.length > 0 && slug.length < 80) slug += "-";
+      if (slug.length < 80) slug += source[index];
+      separatorPending = false;
+    } else if (slug.length > 0) {
+      separatorPending = true;
+    }
+  }
+  return `${slug || "target"}-${fnv1a32(target).slice(0, 8)}`;
+}
+
+function contextDirName(context: QaContext): string {
+  const clean = (part: string) => part.replace(/[^a-zA-Z0-9_.]+/g, "-");
+  return `${clean(context.viewport)}-${clean(context.theme)}-${clean(context.state)}`;
+}
+
+function snapshotDir(target: string, context: QaContext, opts: QaSnapshotStoreOptions): string {
+  return resolve(opts.root ?? SNAPSHOT_DIR, qaSnapshotKey(target), contextDirName(context));
+}
+
+/**
+ * Persist a QA snapshot atomically. The whole context directory is staged as
+ * `<dir>.tmp-<pid>` and renamed into place, replacing any prior snapshot for
+ * the same target + context — a reader never observes a partial write.
+ */
+export function saveQaSnapshot(
+  target: string,
+  context: QaContext,
+  content: {
+    signature: QaSignature;
+    domHtml?: string;
+    screenshotPng?: Buffer;
+    critique?: PersistedCritique;
+  },
+  opts: QaSnapshotStoreOptions = {},
+): StoredQaSnapshot {
+  const dir = snapshotDir(target, context, opts);
+  const staging = `${dir}.tmp-${process.pid}`;
+  rmSync(staging, { recursive: true, force: true });
+  mkdirSync(staging, { recursive: true });
+  writeFileSync(resolve(staging, "signature.json"), `${JSON.stringify(content.signature)}\n`);
+  if (content.domHtml !== undefined) {
+    writeFileSync(resolve(staging, "dom.html"), content.domHtml);
+  }
+  if (content.screenshotPng !== undefined) {
+    writeFileSync(resolve(staging, "screenshot.png"), content.screenshotPng);
+  }
+  if (content.critique !== undefined) {
+    writeFileSync(resolve(staging, "critique.json"), `${JSON.stringify(content.critique)}\n`);
+  }
+  rmSync(dir, { recursive: true, force: true });
+  renameSync(staging, dir);
+  return {
+    signature: content.signature,
+    path: dir,
+    ...(content.domHtml !== undefined ? { domHtmlPath: resolve(dir, "dom.html") } : {}),
+    ...(content.screenshotPng !== undefined
+      ? { screenshotPath: resolve(dir, "screenshot.png") }
+      : {}),
+  };
+}
+
+/** Load the persisted snapshot for a target + context, or null. A corrupt
+ * signature file returns null (and the caller re-acquires a baseline) rather
+ * than throwing — a bad cache entry must never block QA. */
+export function loadQaSnapshot(
+  target: string,
+  context: QaContext,
+  opts: QaSnapshotStoreOptions = {},
+): StoredQaSnapshot | null {
+  const dir = snapshotDir(target, context, opts);
+  const sigPath = resolve(dir, "signature.json");
+  if (!existsSync(sigPath)) return null;
+  try {
+    const signature = JSON.parse(readFileSync(sigPath, "utf8")) as QaSignature;
+    if (!signature || !Array.isArray(signature.nodes) || !Array.isArray(signature.stylesheets)) {
+      return null;
+    }
+    const domHtmlPath = resolve(dir, "dom.html");
+    const screenshotPath = resolve(dir, "screenshot.png");
+    const critiquePath = resolve(dir, "critique.json");
+    let critique: PersistedCritique | undefined;
+    if (existsSync(critiquePath)) {
+      try {
+        const parsed = JSON.parse(readFileSync(critiquePath, "utf8")) as PersistedCritique;
+        if (parsed && typeof parsed.contract_version === "number" && Array.isArray(parsed.tiles)) {
+          critique = parsed;
+        }
+      } catch {
+        // corrupt critique.json degrades to a reuse miss, never an error
+      }
+    }
+    return {
+      signature,
+      path: dir,
+      ...(existsSync(domHtmlPath) ? { domHtmlPath } : {}),
+      ...(existsSync(screenshotPath) ? { screenshotPath } : {}),
+      ...(critique ? { critique } : {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** List targets with at least one persisted snapshot (store maintenance). */
+export function listQaSnapshotTargets(opts: QaSnapshotStoreOptions = {}): string[] {
+  const root = opts.root ?? SNAPSHOT_DIR;
+  if (!existsSync(root)) return [];
+  try {
+    return readdirSync(root)
+      .filter((name) => !name.includes(".tmp-"))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+export interface ResolvedQaBaseline {
+  /** `qa-snapshot:<capturedAt>` | `production-render:<capturedAt>` |
+   * `revision-render:<label>` | `none` — recorded in the manifest so a
+   * reviewer can judge staleness. */
+  source: string;
+  signature: QaSignature | null;
+}
+
+/**
+ * Walk the baseline resolution order with caller-supplied fallbacks. Pure
+ * orchestration: rendering lives in the caller (production URLs and git
+ * worktrees are its business), this just encodes the order and the source
+ * labeling. A fallback that throws or returns null falls through to the next
+ * rung; exhausting all rungs returns `{ source: "none", signature: null }`,
+ * which classifies as `unknown` — never silently text-only.
+ */
+export async function resolveQaBaseline(opts: {
+  target: string;
+  context: QaContext;
+  store?: QaSnapshotStoreOptions;
+  renderProduction?: () => Promise<QaSignature | null>;
+  renderRevision?: { label: string; render: () => Promise<QaSignature | null> };
+}): Promise<ResolvedQaBaseline> {
+  const stored = loadQaSnapshot(opts.target, opts.context, opts.store ?? {});
+  if (stored) {
+    return { source: `qa-snapshot:${stored.signature.capturedAt}`, signature: stored.signature };
+  }
+  if (opts.renderProduction) {
+    try {
+      const signature = await opts.renderProduction();
+      if (signature) return { source: `production-render:${signature.capturedAt}`, signature };
+    } catch {
+      // fall through — an unreachable production URL is not a verdict
+    }
+  }
+  if (opts.renderRevision) {
+    try {
+      const signature = await opts.renderRevision.render();
+      if (signature) {
+        return { source: `revision-render:${opts.renderRevision.label}`, signature };
+      }
+    } catch {
+      // fall through
+    }
+  }
+  return { source: "none", signature: null };
+}
+
+export { SNAPSHOT_DIR as QA_SNAPSHOT_DIR };

package/src/lib/browser/runts.ts

@@ -129,7 +129,7 @@ export function buildRuntsCheck(): (args: {
       scanned++;
 
       // Map every word to its visual line by rounding the Range rect top.
-      const lines = new Map<number, { words: string[]; last: DOMRect }>();
+      const lines = new Map<number, { words: string[]; last: DOMRect; node: Node }>();
       const tw = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
       for (let n = tw.nextNode(); n; n = tw.nextNode()) {
         const value = n.nodeValue ?? "";
@@ -144,8 +144,9 @@ export function buildRuntsCheck(): (args: {
           if (entry) {
             entry.words.push(m[0]);
             entry.last = rect;
+            entry.node = n;
           } else {
-            lines.set(top, { words: [m[0]], last: rect });
+            lines.set(top, { words: [m[0]], last: rect, node: n });
           }
         }
       }
@@ -156,6 +157,30 @@ export function buildRuntsCheck(): (args: {
       if (last?.words.length !== 1) continue;
       const word = last.words[0] ?? "";
       if (ATOMIC.test(word)) continue;
+      // A chip is not prose. A lone token whose glyphs live inside a padded,
+      // boxed inline element (a <code> chip, pill, or badge) is a UI control:
+      // it cannot be rebalanced by rewording, tag rows legitimately wrap to a
+      // single chip, and its shifted glyph box also buckets as a phantom
+      // "line" when it sits mid-line beside normal text. Walk the word's
+      // inline ancestry (tag-based, since flex/grid parents blockify computed
+      // display) and skip the finding when a chip hosts it.
+      const chipHosted = (() => {
+        for (
+          let e = last.node.parentElement;
+          e && e !== el && INLINE.has(e.tagName);
+          e = e.parentElement
+        ) {
+          const cs = getComputedStyle(e);
+          const padX =
+            (Number.parseFloat(cs.paddingLeft) || 0) + (Number.parseFloat(cs.paddingRight) || 0);
+          const boxed =
+            (cs.backgroundColor !== "rgba(0, 0, 0, 0)" && cs.backgroundColor !== "transparent") ||
+            (Number.parseFloat(cs.borderTopWidth) || 0) > 0;
+          if (padX > 0 && boxed) return true;
+        }
+        return false;
+      })();
+      if (chipHosted) continue;
 
       runts.push({
         block: label(el),