@momentiq/dark-factory-cli 2.18.0 → 3.0.1

package/skills/verify/producer/ui-visual.producer.spec.ts

@@ -0,0 +1,137 @@
+/**
+ * Reusable **`ui-visual` (Designer Mode) verification-route producer** (cycle 27
+ * Phase C).
+ *
+ * The Designer-Mode sibling of `ui-route.producer.spec.ts`. Same evidence shape
+ * and the same shared plumbing (`playwright-route.sh`, pointed here via
+ * `DF_UI_ROUTE_CONFIG=ui-visual.config.ts`), with ONE difference that makes it
+ * usable by a non-technical operator: the capture surfaces are **auto-derived**
+ * from the changed Next.js app-router files (`ui-visual-surfaces.ts`) instead of a
+ * hand-authored `SURFACES[]`. A changed `app/pricing/page.tsx` is captured at
+ * `/pricing`; the designer edits no config.
+ *
+ * For each derived surface it captures the required floor:
+ *   (1) an **ARIA snapshot** (accessibility tree — structural, tamper-resistant),
+ *   (2) an **after screenshot** at the SHA under review, plus an optional
+ *       **before screenshot** baseline when `DF_UI_ROUTE_BEFORE_BASE_URL` is set
+ *       (the before/after pair the PR embed helper renders for humans).
+ *
+ * Fail-closed coverage (see `planCapture`): a changed product-UI path that maps to
+ * NO route (a bare component, a non-`app/` `*.tsx`), or a DYNAMIC page (`[slug]` /
+ * `[...all]`), BLOCKS the route — auto-derivation can evidence neither by rendering
+ * an unrelated surface. Dynamic pages are unsupported by this auto-derive route, so
+ * capture them with the engineer `playwright` route (hand-authored surfaces); cover
+ * a component by also touching the page(s) that render it. Never passes with zero
+ * evidence: a harness-only or signal-less run smoke-captures the home surface.
+ *
+ * ── CONSUMER REFERENCE FILE — copy into your repo (with `ui-visual-surfaces.ts`
+ *    and `ui-visual.config.ts`) and own it. `df skills install verify` does NOT
+ *    overwrite it.
+ */
+import { test, expect, type Page } from "@playwright/test";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  deriveSurfacesFromChangedPaths,
+  planCapture,
+  type DerivedSurface,
+} from "./ui-visual-surfaces";
+
+const SHA = process.env.DF_UI_ROUTE_SHA ?? "unknown";
+const OUT_DIR =
+  process.env.DF_UI_ROUTE_OUT ?? `agent-reviews/quality-gates/ui/${SHA}`;
+const BEFORE_BASE_URL = process.env.DF_UI_ROUTE_BEFORE_BASE_URL?.replace(/\/$/, "");
+
+const CHANGED_UI_PATHS = (process.env.DF_UI_ROUTE_CHANGED_PATHS ?? "")
+  .split(/\r?\n/)
+  .map((p) => p.trim())
+  .filter(Boolean);
+
+const partition = deriveSurfacesFromChangedPaths(CHANGED_UI_PATHS);
+
+// The capture decision + fail-closed contract live in the pure, unit-tested
+// `planCapture`: a dynamic-page change FAILS CLOSED (it has no auto-navigable URL
+// — see the module header) instead of "passing" on an unrelated capture. Never
+// zero evidence for a real static change.
+const plan = planCapture(partition);
+const CAPTURE_SURFACES: DerivedSurface[] = plan.capture;
+
+function routeOutDir(slug: string): string {
+  return join(OUT_DIR, slug);
+}
+
+// FAIL-CLOSED coverage gate: when `planCapture` cannot produce real evidence for a
+// changed path (an uncovered bare component, or a dynamic page with no concrete
+// surface), the route FAILS rather than "passing" on an unrelated home capture.
+test("ui-visual coverage — every changed UI path maps to a real capture or is exempt", async () => {
+  if (plan.failClosed) throw new Error(plan.failClosed.message);
+  expect(plan.failClosed).toBeNull();
+});
+
+async function captureBefore(page: Page, surface: DerivedSurface, dir: string): Promise<void> {
+  if (!BEFORE_BASE_URL) return;
+  const beforeUrl = `${BEFORE_BASE_URL}${surface.path}`;
+  try {
+    await page.goto(beforeUrl, { waitUntil: "networkidle", timeout: 30_000 });
+    await page.screenshot({ path: join(dir, "before.png"), fullPage: true });
+  } catch (err) {
+    // The baseline is best-effort; a missing/unreachable baseline must not fail
+    // the route (the ARIA + after capture is the floor). Record why.
+    test.info().annotations.push({
+      type: "before-capture-skipped",
+      description: `baseline ${beforeUrl} unreachable: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    });
+  }
+}
+
+for (const surface of CAPTURE_SURFACES) {
+  test(`ui-visual evidence — ${surface.slug} (${surface.path})`, async ({ page }) => {
+    const dir = routeOutDir(surface.slug);
+    mkdirSync(dir, { recursive: true });
+
+    // --- (optional) BEFORE baseline from the configured origin ---
+    await captureBefore(page, surface, dir);
+
+    // --- AFTER: the SHA under review ---
+    await page.goto(surface.path, { waitUntil: "networkidle", timeout: 30_000 });
+
+    // Structural render floor: a real page exposes a `main` landmark. This is a
+    // relaxed, copy-STABLE assertion (no per-surface heading to hand-author) that
+    // still fails a blank screen / crash / error boundary — the point of a gate.
+    await expect(page.getByRole("main").first()).toBeVisible({ timeout: 15_000 });
+
+    // Floor evidence #1 — ARIA snapshot (accessibility tree). Structural,
+    // diff-able, hard to stage. Non-trivial, then persisted.
+    const ariaSnapshot = await page.locator("body").ariaSnapshot();
+    expect(ariaSnapshot.trim().length).toBeGreaterThan(0);
+    writeFileSync(join(dir, "aria.snapshot.txt"), `${ariaSnapshot}\n`, "utf8");
+
+    // Floor evidence #2 — the "after" screenshot bound to the gated SHA.
+    await page.screenshot({ path: join(dir, "after.png"), fullPage: true });
+
+    writeFileSync(
+      join(dir, "meta.json"),
+      `${JSON.stringify(
+        {
+          surface: surface.slug,
+          path: surface.path,
+          covers: surface.covers,
+          sha: SHA,
+          capturedAt: new Date().toISOString(),
+          baseURL: test.info().project.use.baseURL ?? null,
+          beforeBaseURL: BEFORE_BASE_URL ?? null,
+          ariaSnapshotBytes: Buffer.byteLength(ariaSnapshot, "utf8"),
+          evidenceKind: "playwright",
+          route: "ui-visual",
+          floor: ["aria-snapshot", "after-screenshot"],
+          beforeScreenshot: BEFORE_BASE_URL ? "before.png" : null,
+        },
+        null,
+        2,
+      )}\n`,
+      "utf8",
+    );
+  });
+}