@momentiq/dark-factory-cli 2.17.0 → 3.0.0

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

@@ -0,0 +1,261 @@
+/**
+ * Auto-derived capture surfaces for the Dark Factory **`ui-visual`** verification
+ * route (Designer Mode, cycle 27 Phase C).
+ *
+ * The `playwright` route (`coverage.ts` + `ui-route.producer.spec.ts`) makes a
+ * human hand-author `SURFACES[]` — one entry per URL, with a `covers` glob and a
+ * copy-stable `requiredHeading`. That is right for an engineer who knows the app.
+ * A non-technical Designer-Mode operator cannot. `ui-visual` instead DERIVES the
+ * capture surfaces from the changed Next.js **app-router** files: a changed
+ * `app/pricing/page.tsx` maps to the URL `/pricing`, which the producer navigates
+ * and screenshots. No `SURFACES[]` to edit.
+ *
+ * This module is PURE (no browser, no fs, no Dark Factory / vendor dependency) and
+ * is the load-bearing half of the route — the path→URL mapping and the fail-closed
+ * classification — so it is unit-tested without a browser (mirroring `coverage.ts`).
+ *
+ * ── CONSUMER REFERENCE FILE — ships in the npm tarball next to `coverage.ts`;
+ *    copy it into your repo alongside `ui-visual.producer.spec.ts` and own it.
+ *    `df skills install verify` does NOT overwrite it.
+ */
+
+/** One capture surface derived from a changed app-router file. */
+export interface DerivedSurface {
+  /** URL path to navigate (relative to baseURL), e.g. "/", "/pricing". Dynamic
+   *  routes carry a `:param` placeholder (e.g. "/blog/:slug") and are NOT
+   *  directly navigable — see `dynamic`. */
+  path: string;
+  /** Filesystem-safe slug for the evidence subdir, e.g. "home", "pricing". */
+  slug: string;
+  /** The changed source path this surface is the evidence for. */
+  covers: string;
+  /** True when the route has a `[param]` / `[...catch]` segment: the producer
+   *  cannot navigate it without a concrete value, so it is recorded (for human
+   *  review) rather than auto-captured. */
+  dynamic: boolean;
+}
+
+export interface DerivedSurfacePartition {
+  /** Static, navigable surfaces — the producer captures each. De-duped by slug. */
+  surfaces: DerivedSurface[];
+  /** Dynamic routes touched by the change — recorded (need a concrete param),
+   *  not auto-navigated. De-duped by slug. */
+  dynamic: DerivedSurface[];
+  /** Changed product-UI paths with NO derivable route (a component, a lib, a
+   *  non-`app/` `*.tsx`). Auto-derivation cannot know which page renders a
+   *  component, so these FAIL CLOSED — the change must also touch the page(s)
+   *  that render them, or the operator adds an explicit surface. Mirrors the
+   *  `coverage.ts` fail-closed contract. */
+  uncovered: string[];
+}
+
+// App-router files that render a routable surface. `route.*` (API route
+// handlers) render no UI and are treated as non-visual (exempt). `default.*`
+// (parallel-route fallbacks) render UI at their segment, so they count.
+const ROUTE_FILE_BASENAMES = new Set(["page", "layout", "template", "default"]);
+const ROUTE_FILE_RE = /\.(tsx|jsx|ts|js)$/;
+
+/**
+ * Harness / non-UI files that are EXEMPT from the coverage requirement — the
+ * route's own machinery, styles, tests, type decls, config, data. A change to
+ * ONLY these does not require a capture (there is no rendered surface). Kept in
+ * sync with `coverage.ts`'s `NON_SURFACE_GLOBS` philosophy but self-contained.
+ */
+export const UI_VISUAL_NON_SURFACE_SUFFIXES: readonly string[] = [
+  ".css",
+  ".scss",
+  ".json",
+  ".md",
+  ".mdx",
+  ".d.ts",
+  ".test.ts",
+  ".test.tsx",
+  ".spec.ts",
+  ".spec.tsx",
+];
+
+function isNonSurface(path: string): boolean {
+  const lower = path.toLowerCase();
+  if (UI_VISUAL_NON_SURFACE_SUFFIXES.some((s) => lower.endsWith(s))) return true;
+  // The producer harness itself + Playwright config + test dirs.
+  if (/(^|\/)tests?(\/|$)/.test(lower)) return true;
+  if (/(^|\/)__tests__(\/|$)/.test(lower)) return true;
+  if (/(^|\/)(coverage|ui-visual-surfaces)\.ts$/.test(lower)) return true;
+  if (/playwright[^/]*\.config\.(ts|js|mjs|cjs)$/.test(lower)) return true;
+  if (/\.producer\.spec\.ts$/.test(lower)) return true;
+  return false;
+}
+
+/**
+ * Map one changed source path to a route surface, or `null` when it maps to no
+ * navigable route (a component, a private `_folder` colocation file, a file not
+ * under an `app/` router root, or an API `route.*` handler).
+ */
+export function deriveSurface(changedPath: string): DerivedSurface | null {
+  if (ROUTE_FILE_RE.test(changedPath) === false) return null;
+  const segments = changedPath.split("/");
+  const file = segments[segments.length - 1] ?? "";
+  const dotIdx = file.indexOf(".");
+  const base = dotIdx >= 0 ? file.slice(0, dotIdx) : file;
+  if (!ROUTE_FILE_BASENAMES.has(base)) return null;
+
+  // Locate the app-router root: the LAST `app` segment (handles `web/app/…`,
+  // `apps/web/src/app/…`, `src/app/…`). No `app/` root ⇒ not a routed file.
+  const appIdx = segments.lastIndexOf("app");
+  if (appIdx < 0) return null;
+
+  const routeDirSegments = segments.slice(appIdx + 1, segments.length - 1);
+  const urlSegments: string[] = [];
+  let dynamic = false;
+  for (const seg of routeDirSegments) {
+    // Route groups `(marketing)` and intercepting markers `(.)`,`(..)` — removed
+    // from the URL.
+    if (seg.startsWith("(") && seg.endsWith(")")) continue;
+    // Parallel-route slots `@modal` — not part of the URL.
+    if (seg.startsWith("@")) continue;
+    // Private folders `_components` opt OUT of routing — the file is colocation,
+    // not a route.
+    if (seg.startsWith("_")) return null;
+    // Dynamic segments `[slug]`, `[...all]`, `[[...opt]]` → `:slug` placeholder.
+    const dyn = seg.match(/^\[+\.{0,3}(.+?)\]+$/);
+    if (dyn) {
+      dynamic = true;
+      urlSegments.push(`:${dyn[1]}`);
+      continue;
+    }
+    urlSegments.push(seg);
+  }
+
+  const path = urlSegments.length === 0 ? "/" : `/${urlSegments.join("/")}`;
+  const slug = slugForUrl(urlSegments);
+  return { path, slug, covers: changedPath, dynamic };
+}
+
+function sanitizeSlug(raw: string): string {
+  return raw
+    .replace(/:/g, "")
+    .replace(/[^a-z0-9-]+/gi, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+    .toLowerCase();
+}
+
+function slugForUrl(urlSegments: readonly string[]): string {
+  if (urlSegments.length === 0) return "home";
+  return sanitizeSlug(urlSegments.join("-"));
+}
+
+/**
+ * Partition changed paths (already restricted to the route's trigger surface —
+ * `web/**` / `*.tsx` — by `playwright-route.sh`) into the surfaces to capture,
+ * the dynamic routes to record, and the uncovered product paths that FAIL CLOSED.
+ *
+ * An empty `changed` (a manual run with the env unset) yields nothing derivable;
+ * the producer falls back to capturing the home surface so evidence is never zero.
+ */
+export function deriveSurfacesFromChangedPaths(
+  changed: readonly string[],
+): DerivedSurfacePartition {
+  const surfacesBySlug = new Map<string, DerivedSurface>();
+  const dynamicBySlug = new Map<string, DerivedSurface>();
+  const uncovered: string[] = [];
+
+  for (const raw of changed) {
+    const path = raw.trim();
+    if (!path) continue;
+    if (isNonSurface(path)) continue; // harness / non-UI — exempt.
+    const surface = deriveSurface(path);
+    if (surface === null) {
+      uncovered.push(path);
+      continue;
+    }
+    const bucket = surface.dynamic ? dynamicBySlug : surfacesBySlug;
+    if (!bucket.has(surface.slug)) bucket.set(surface.slug, surface);
+  }
+
+  return {
+    surfaces: [...surfacesBySlug.values()],
+    dynamic: [...dynamicBySlug.values()],
+    uncovered,
+  };
+}
+
+/**
+ * The home surface, smoke-captured when the change armed the route but derived NO
+ * navigable surface AND touched no dynamic/uncovered path (a harness-only or
+ * signal-less manual run) — so the route never passes with zero evidence.
+ */
+export const UI_VISUAL_HOME_FALLBACK: DerivedSurface = {
+  path: "/",
+  slug: "home",
+  covers: "(smoke)",
+  dynamic: false,
+};
+
+/** The producer's capture decision: what to navigate, or why to fail closed. */
+export interface CapturePlan {
+  /** Surfaces the producer captures (empty when `failClosed` is set). */
+  capture: DerivedSurface[];
+  /** Non-null when the route CANNOT produce real evidence and must fail the run
+   *  (a dynamic page that can't be auto-navigated, or an uncovered product path).
+   *  `null` means the plan is safe to capture. */
+  failClosed: { code: "uncovered" | "dynamic-unmapped"; paths: string[]; message: string } | null;
+}
+
+/**
+ * Decide what the `ui-visual` producer captures for a partition of changed paths,
+ * or whether it must FAIL CLOSED. The fail-closed contract (extracted here so it is
+ * unit-tested without a browser):
+ *
+ *  - `uncovered` path(s) present → fail closed (a bare component can't be evidenced
+ *    by rendering an unrelated surface).
+ *  - `dynamic` route(s) present → fail closed. A `[slug]` / `[...all]` page has no
+ *    auto-navigable URL, so this auto-derive route cannot evidence it; capturing
+ *    anything else (a static sibling, or the home fallback) would be a false pass
+ *    for the changed page. Dynamic pages belong to the engineer `playwright` route
+ *    (hand-authored concrete surfaces). Fail closed even when static surfaces are
+ *    also present — a run is all-or-nothing.
+ *  - otherwise capture the derived static surfaces; if there are none, smoke-capture
+ *    the home surface so evidence is never zero.
+ */
+export function planCapture(partition: DerivedSurfacePartition): CapturePlan {
+  const { surfaces, dynamic, uncovered } = partition;
+
+  if (uncovered.length > 0) {
+    return {
+      capture: [],
+      failClosed: {
+        code: "uncovered",
+        paths: [...uncovered],
+        message:
+          "ui-visual route: the following changed UI path(s) map to NO app-router " +
+          "surface, so this route cannot produce real evidence for them and FAILS " +
+          "CLOSED:\n" +
+          uncovered.map((p) => `  - ${p}`).join("\n") +
+          "\n\nAuto-derivation captures app-router pages (e.g. app/foo/page.tsx → " +
+          "/foo). A bare component has no route: also change (or add a page under " +
+          "app/ that renders) the affected UI, so the capture is real.",
+      },
+    };
+  }
+
+  if (dynamic.length > 0) {
+    return {
+      capture: [],
+      failClosed: {
+        code: "dynamic-unmapped",
+        paths: dynamic.map((d) => d.path),
+        message:
+          "ui-visual route: dynamic app-router page(s) changed. This auto-derive " +
+          "route does NOT support dynamic pages (a `[slug]` / `[...all]` route has " +
+          "no concrete URL to auto-navigate), so it FAILS CLOSED:\n" +
+          dynamic.map((d) => `  - ${d.covers} → ${d.path}`).join("\n") +
+          "\n\nCapture dynamic pages with the engineer `playwright` route instead " +
+          "(its hand-authored SURFACES[] take real params).",
+      },
+    };
+  }
+
+  if (surfaces.length > 0) return { capture: [...surfaces], failClosed: null };
+  return { capture: [UI_VISUAL_HOME_FALLBACK], failClosed: null };
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Playwright config for the **`ui-visual` (Designer Mode) verification-route
+ * producer** (cycle 27 Phase C).
+ *
+ * DRY over the base UI-route config: it reuses every setting from
+ * `playwright.ui-route.config.ts` (one chromium project, no retries, optional
+ * storage-state, optional local-preview `webServer`, all the same env knobs) and
+ * changes ONLY `testMatch` so this config runs `ui-visual.producer.spec.ts`
+ * instead of `ui-route.producer.spec.ts`. Kept a separate file so the shared
+ * `playwright-route.sh` can select it via `DF_UI_ROUTE_CONFIG=ui-visual.config.ts`
+ * without disturbing the `playwright` route.
+ *
+ * ── CONSUMER REFERENCE FILE — copy into your repo next to the base config +
+ *    the producer spec and own it. `df skills install verify` does NOT overwrite it.
+ */
+import { defineConfig } from "@playwright/test";
+import base from "./playwright.ui-route.config";
+
+export default defineConfig({
+  ...base,
+  testMatch: /ui-visual\.producer\.spec\.ts$/,
+});

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",
+    );
+  });
+}