@momentiq/dark-factory-cli 3.0.1 → 3.1.0

package/skills/verify/producer/surface-declaration.ts

@@ -0,0 +1,373 @@
+/**
+ * Designer-safe UI-surface COVERAGE DECLARATION for the reusable playwright
+ * (UI) verification-route producer (momentiq-ai/dark-factory#359).
+ *
+ * ## The wall this removes
+ *
+ * The engineer `playwright` route fails closed when a changed product-UI path
+ * maps to NO `SURFACES[]` entry (`coverage.ts`). The ONLY way to clear that
+ * block was to EDIT the Playwright spec — hand-author a `UiSurface` (a route
+ * `path`, a `requiredHeading` **RegExp**, and `covers` globs) in
+ * `ui-route.producer.spec.ts`. That is pure engineer work: a designer touching
+ * an unmapped area (e.g. `web/components/chat/**`) mid-feature is walled by a
+ * TS/RegExp edit they cannot safely make.
+ *
+ * ## What this adds (WITHOUT weakening the gate)
+ *
+ * A plain DATA file — `.darkfactory/ui-surfaces.json` — in which a designer
+ * DECLARES "this changed area is shown on `<route>`". The producer reads the
+ * declaration, turns each entry into a real `UiSurface`, and CAPTURES that route
+ * (navigates, asserts its heading, screenshots) exactly like a hand-authored
+ * surface. So the coverage requirement is UNCHANGED — the declared route must
+ * really render — only the AUTHORING surface moves from "edit test/TS code" to
+ * "add a JSON entry". Anything that maps to no surface AND no declaration still
+ * FAILS CLOSED (the engineer contract is untouched).
+ *
+ * Two deliberate designer-safety choices:
+ *  - `requiredHeading` is a plain string matched case-insensitively as a
+ *    LITERAL (escaped), so no regex knowledge is required and a stray metachar
+ *    cannot silently widen the assertion.
+ *  - A malformed declaration fails LOUD (never silently ignored) — a designer
+ *    who mis-declares sees a clear error, not a still-blocked route.
+ *
+ * ── CONSUMER REFERENCE FILE — ships in the npm tarball next to `coverage.ts`;
+ *    copy it into your repo alongside the producer spec and own it. It is pure
+ *    (Node builtins only, no Dark Factory / vendor dependency) and unit-tested
+ *    without a browser (mirroring `coverage.ts`).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+
+import type { UiSurface } from "./coverage";
+
+/** Repo-root-relative default location of the designer declaration. */
+export const DECLARATION_REL_PATH = ".darkfactory/ui-surfaces.json";
+
+/** Env var that overrides the declaration location (absolute or start-dir-
+ *  relative). Exported by `playwright-route.sh` as the canonical repo-root path;
+ *  falls back to an upward filesystem walk when unset. */
+export const DECLARATION_ENV_VAR = "DF_UI_SURFACES";
+
+const EXAMPLE_JSON =
+  `  {\n` +
+  `    "surfaces": [\n` +
+  `      { "path": "/chat", "covers": ["web/components/chat/**"], "requiredHeading": "Chat" }\n` +
+  `    ]\n` +
+  `  }`;
+
+/**
+ * The DESIGNER-FACING shape of one declaration entry (the JSON a designer
+ * writes). Deliberately simpler than `UiSurface`: `requiredHeading` is a plain
+ * string (not a RegExp) and `slug` is optional (derived from `path` when
+ * omitted). This is documentation of the accepted shape; parsing accepts
+ * `unknown` and validates defensively.
+ */
+export interface DeclaredSurfaceInput {
+  /** URL path the producer navigates + captures, e.g. "/chat". Must start "/". */
+  path: string;
+  /** Source-path globs this route is the evidence for — the changed paths it
+   *  COVERS, e.g. ["web/components/chat/**"]. Non-empty. */
+  covers: string[];
+  /** A word/phrase from the page's main heading (role=heading, accessible
+   *  name). Matched case-insensitively as a LITERAL — no regex. Non-empty. */
+  requiredHeading: string;
+  /** Optional evidence-subdir slug; derived from `path` when omitted. */
+  slug?: string;
+}
+
+/** Escape a plain string so it matches LITERALLY inside a RegExp. */
+function escapeRegExp(literal: string): string {
+  return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function sanitizeSlug(raw: string): string {
+  const s = raw
+    .replace(/[^a-z0-9]+/gi, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+    .toLowerCase();
+  return s.length > 0 ? s : "surface";
+}
+
+function slugFromPath(path: string): string {
+  const s = sanitizeSlug(path.replace(/^\/+/, ""));
+  return s === "surface" ? "home" : s;
+}
+
+/** Pull the entry array out of either a bare array or a `{ surfaces: [...] }`
+ *  wrapper. Anything else is a loud parse error. `prefix` names the source (the
+ *  resolved file, when known) so the operator sees WHICH declaration is wrong. */
+function extractEntries(raw: unknown, prefix: string): unknown[] {
+  if (Array.isArray(raw)) return raw;
+  if (raw !== null && typeof raw === "object" && "surfaces" in raw) {
+    const surfaces = (raw as { surfaces: unknown }).surfaces;
+    if (Array.isArray(surfaces)) return surfaces;
+    throw new Error(
+      `${prefix}: the top-level "surfaces" key must be an array of surface ` +
+        `entries. Example:\n${EXAMPLE_JSON}`,
+    );
+  }
+  throw new Error(
+    `${prefix}: expected a JSON array of surface entries, or an object with a ` +
+      `"surfaces" array. Example:\n${EXAMPLE_JSON}`,
+  );
+}
+
+function toUiSurface(entry: unknown, index: number, prefix: string): UiSurface {
+  const at = `${prefix} entry [${index}]`;
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+    throw new Error(
+      `${at} must be an object with "path", "covers", and "requiredHeading".`,
+    );
+  }
+  const rec = entry as Record<string, unknown>;
+
+  const rawPath = rec["path"];
+  if (typeof rawPath !== "string" || rawPath.trim().length === 0) {
+    throw new Error(
+      `${at} is missing a non-empty "path" string (the route to navigate, e.g. ` +
+        `"/chat").`,
+    );
+  }
+  const path = rawPath.trim();
+  if (!path.startsWith("/")) {
+    throw new Error(
+      `${at} "path" must start with "/" (a route relative to your site root), ` +
+        `got ${JSON.stringify(rawPath)}.`,
+    );
+  }
+
+  const rawCovers = rec["covers"];
+  if (!Array.isArray(rawCovers) || rawCovers.length === 0) {
+    throw new Error(
+      `${at} is missing a non-empty "covers" array (the source globs this route ` +
+        `is the evidence for, e.g. ["web/components/chat/**"]).`,
+    );
+  }
+  const covers = rawCovers.map((glob, gi) => {
+    if (typeof glob !== "string" || glob.trim().length === 0) {
+      throw new Error(`${at} "covers[${gi}]" must be a non-empty glob string.`);
+    }
+    return glob.trim();
+  });
+
+  const rawHeading = rec["requiredHeading"];
+  if (typeof rawHeading !== "string" || rawHeading.trim().length === 0) {
+    throw new Error(
+      `${at} is missing a non-empty "requiredHeading" string (a word from the ` +
+        `page's main heading — matched case-insensitively, NOT a regex).`,
+    );
+  }
+  const heading = rawHeading.trim();
+
+  const rawSlug = rec["slug"];
+  let slug: string;
+  if (rawSlug === undefined) {
+    slug = slugFromPath(path);
+  } else if (typeof rawSlug === "string" && rawSlug.trim().length > 0) {
+    slug = sanitizeSlug(rawSlug);
+  } else {
+    throw new Error(`${at} "slug", when present, must be a non-empty string.`);
+  }
+
+  return {
+    path,
+    slug,
+    requiredHeading: new RegExp(escapeRegExp(heading), "i"),
+    covers,
+  };
+}
+
+/**
+ * Parse an already-JSON-decoded declaration (a bare array or `{ surfaces: [] }`)
+ * into real `UiSurface[]`. PURE (no fs) — the load-bearing validation is
+ * unit-tested without touching disk. Throws a clear, actionable error on any
+ * malformed entry (loud, never silent). `source` (the resolved file path, when
+ * called from `loadDeclaredSurfaces`) is woven into every error so the operator
+ * can tell WHICH declaration is wrong — `DF_UI_SURFACES` can override the path.
+ */
+export function parseSurfaceDeclaration(
+  raw: unknown,
+  source?: string,
+): UiSurface[] {
+  const prefix =
+    typeof source === "string" && source.trim().length > 0
+      ? `ui-surfaces declaration (${source})`
+      : "ui-surfaces declaration";
+  return extractEntries(raw, prefix).map((entry, i) =>
+    toUiSurface(entry, i, prefix),
+  );
+}
+
+/**
+ * Merge designer-DECLARED surfaces onto the hand-authored `SURFACES[]`, FAILING
+ * CLOSED on a slug collision. Evidence is written per surface to
+ * `<out-dir>/<slug>/`, so two surfaces sharing a slug would SILENTLY OVERWRITE
+ * each other's screenshots. Rather than dedupe (which drops a real surface's
+ * evidence) or overwrite, this throws a loud, plain-language error naming the
+ * colliding slug — the designer renames the declaration's `slug`. Detects a
+ * declared slug colliding with an existing `SURFACES[]` entry OR with another
+ * declared surface. (A pre-existing collision WITHIN `base` is the engineer's
+ * own concern and is not re-checked here.)
+ */
+export function mergeDeclaredSurfaces(
+  base: readonly UiSurface[],
+  declared: readonly UiSurface[],
+): UiSurface[] {
+  const origin = new Map<string, "surface" | "declaration">();
+  for (const s of base) origin.set(s.slug, "surface");
+  for (const d of declared) {
+    const clash = origin.get(d.slug);
+    if (clash !== undefined) {
+      const owner =
+        clash === "surface"
+          ? "an existing SURFACES[] entry"
+          : "another declared surface";
+      throw new Error(
+        `ui-surfaces declaration: the declared surface for path "${d.path}" uses ` +
+          `slug "${d.slug}", which is ALREADY used by ${owner}. Evidence is ` +
+          `written per surface to <out-dir>/${d.slug}/, so two surfaces sharing a ` +
+          `slug would SILENTLY OVERWRITE each other's screenshots — this route ` +
+          `FAILS CLOSED instead. Give this declaration a unique "slug" in ` +
+          `.darkfactory/ui-surfaces.json (e.g. "slug": "${d.slug}-2").`,
+      );
+    }
+    origin.set(d.slug, "declaration");
+  }
+  return [...base, ...declared];
+}
+
+/**
+ * Resolve the declaration file location: the `DF_UI_SURFACES` override first
+ * (absolute or `startDir`-relative), else an upward filesystem walk from
+ * `startDir` for `.darkfactory/ui-surfaces.json`. Returns `null` when no
+ * declaration exists.
+ *
+ * The upward walk exists because the producer runs with `cwd` = the web dir
+ * (e.g. `web/`) but the declaration lives at the REPO ROOT alongside the other
+ * `.darkfactory/` config — a `join(cwd, ...)` would miss it.
+ */
+export function resolveDeclarationPath(
+  startDir: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string | null {
+  const override = env[DECLARATION_ENV_VAR];
+  if (typeof override === "string" && override.trim().length > 0) {
+    const raw = override.trim();
+    const abs = isAbsolute(raw) ? raw : resolve(startDir, raw);
+    return existsSync(abs) ? abs : null;
+  }
+  let dir = resolve(startDir);
+  for (;;) {
+    const candidate = join(dir, DECLARATION_REL_PATH);
+    if (existsSync(candidate)) return candidate;
+    // Stop at the repo root (a dir/file named `.git` — a plain repo has a dir, a
+    // worktree/submodule has a file): the declaration is a repo-root artifact, so
+    // never search ABOVE it, which would risk picking up an unrelated
+    // `.darkfactory/ui-surfaces.json` in a parent checkout.
+    if (existsSync(join(dir, ".git"))) return null;
+    const parent = dirname(dir);
+    if (parent === dir) return null; // reached the filesystem root
+    dir = parent;
+  }
+}
+
+/**
+ * Load + parse the designer declaration, returning the extra `UiSurface[]` to
+ * merge into the producer's `SURFACES[]`. A MISSING declaration is normal (no
+ * designer override) → `[]`. A PRESENT-but-malformed declaration (bad JSON or a
+ * failed field validation) THROWS — fail loud, never silently un-cover a path.
+ */
+export function loadDeclaredSurfaces(
+  startDir: string,
+  env: NodeJS.ProcessEnv = process.env,
+): UiSurface[] {
+  const file = resolveDeclarationPath(startDir, env);
+  if (file === null) return [];
+
+  let text: string;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch (err) {
+    throw new Error(
+      `ui-surfaces declaration: failed to read ${file}: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+
+  let json: unknown;
+  try {
+    json = JSON.parse(text);
+  } catch (err) {
+    throw new Error(
+      `ui-surfaces declaration: ${file} is not valid JSON: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+
+  // Pass the resolved file so a schema-validation error names WHICH file is
+  // wrong (DF_UI_SURFACES can override the location).
+  return parseSurfaceDeclaration(json, file);
+}
+
+/** Context for the fail-closed coverage message. */
+export interface UncoveredErrorContext {
+  /** The changed UI path(s) with no mapped/declared surface. */
+  uncovered: readonly string[];
+  /** The active operator mode (e.g. `process.env.DF_MODE`). When set (a
+   *  non-empty operator-driven session — Designer Mode is the first), the
+   *  message routes to `/designer-handoff` in plain language instead of "edit
+   *  the spec". */
+  mode?: string | undefined;
+  /** Where the designer declaration lives (for the message). */
+  declarationPath?: string;
+}
+
+/**
+ * Build the fail-closed coverage error. Pure + unit-tested so both personas'
+ * copy is asserted:
+ *  - ENGINEER (no operator mode): points to `SURFACES[]` AND the designer
+ *    declaration — both clear the block; the coverage requirement is unchanged.
+ *  - DESIGNER / operator mode active: plain-language, framed as the gate WORKING
+ *    (not a rejection), with two designer-safe options — the JSON declaration,
+ *    or `/designer-handoff` as PROGRESS. It never routes a designer to a
+ *    TS/spec edit. (References the `/designer-handoff` skill; does NOT edit it.)
+ */
+export function formatUncoveredError(ctx: UncoveredErrorContext): string {
+  const declPath = ctx.declarationPath ?? DECLARATION_REL_PATH;
+  const list = ctx.uncovered.map((p) => `  - ${p}`).join("\n");
+  const example = `${declPath}:\n${EXAMPLE_JSON}`;
+  const operatorMode =
+    typeof ctx.mode === "string" && ctx.mode.trim().length > 0;
+
+  if (operatorMode) {
+    return (
+      `Design verification can't see this change yet.\n\n` +
+      `The UI you changed isn't mapped to a screen this check captures, so it ` +
+      `can't produce real before/after evidence for it — it stops here. This is ` +
+      `the safety gate doing its job, NOT a rejection of your work:\n${list}\n\n` +
+      `Two designer-safe ways forward — neither touches test or TypeScript code:\n\n` +
+      `  1. Say which screen shows this change, in ${example}\n\n` +
+      `     (read: "the /chat screen is where web/components/chat/** appears"). ` +
+      `Commit it and re-run — this check then captures /chat as the evidence.\n\n` +
+      `  2. If you can't map it to a screen, hand it to an engineer as PROGRESS: ` +
+      `run \`/designer-handoff\`. It escalates with the context filled in — never ` +
+      `a rejection.`
+    );
+  }
+
+  return (
+    `Evidence-Gated Validation playwright route: the following changed UI ` +
+    `path(s) have NO mapped capture surface, so this route cannot produce real ` +
+    `evidence for them and FAILS CLOSED:\n${list}\n\n` +
+    `Fix (either — the coverage requirement is unchanged; the added/declared ` +
+    `route must really render):\n` +
+    `  • Engineer: add a surface (path + requiredHeading + covers glob) to ` +
+    `SURFACES[] in ui-route.producer.spec.ts.\n` +
+    `  • No test-code edit: declare the covering route in ${example}\n\n` +
+    `Do NOT widen NON_SURFACE_GLOBS to suppress a real UI change — that ` +
+    `re-opens the false-positive hole this gate closes.`
+  );
+}

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

@@ -30,6 +30,12 @@
  * cannot be satisfied by rendering only an unaffected surface. The mapping logic
  * lives in the unit-tested `coverage.ts`.
  *
+ * A changed area can be covered EITHER by editing `SURFACES[]` below (engineer)
+ * OR by declaring the covering route in `.darkfactory/ui-surfaces.json` — a
+ * designer-safe DATA file that needs no test/TS edit (#359, `surface-declaration.ts`).
+ * Declared surfaces are captured identically, so the coverage requirement is
+ * unchanged; only the authoring surface differs.
+ *
  * ## Auth (consumer-supplied storage-state — NOT vendor-coupled)
  *
  * Public surfaces need no auth. For PROTECTED surfaces, supply an authenticated
@@ -53,14 +59,21 @@
  * gate without a real, passing capture bound to the SHA.
  *
  * ── CONSUMER REFERENCE FILE — copy into your repo and OWN it. The one block you
- *    MUST edit is `SURFACES[]` below (your routes + their required headings +
- *    the source globs each one covers). `df skills install verify` does NOT
- *    overwrite this file; it is yours to maintain.
+ *    edit for engineer-authored surfaces is `SURFACES[]` below (your routes +
+ *    their required headings + the source globs each one covers); a designer can
+ *    instead add covering routes to `.darkfactory/ui-surfaces.json` with no code
+ *    edit (#359). `df skills install verify` does NOT overwrite this file; it is
+ *    yours to maintain.
  */
 import { test, expect, type Page } from "@playwright/test";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { partitionChangedPaths, type UiSurface } from "./coverage";
+import {
+  formatUncoveredError,
+  loadDeclaredSurfaces,
+  mergeDeclaredSurfaces,
+} from "./surface-declaration";
 
 const SHA = process.env.DF_UI_ROUTE_SHA ?? "unknown";
 const OUT_DIR =
@@ -134,11 +147,29 @@ const CHANGED_UI_PATHS = (process.env.DF_UI_ROUTE_CHANGED_PATHS ?? "")
   .map((p) => p.trim())
   .filter(Boolean);
 
+// Designer-safe coverage declaration (#359): a designer can DECLARE a covering
+// route in `.darkfactory/ui-surfaces.json` (a data file) instead of editing the
+// SURFACES[] above — pure engineer work they can't safely do mid-feature.
+// Declared entries become real UiSurfaces, so the producer navigates + asserts +
+// screenshots them exactly like a hand-authored surface: the fail-closed
+// coverage REQUIREMENT is unchanged; only the AUTHORING surface (JSON data vs
+// TS/RegExp) differs. Missing declaration → []; a malformed one throws (loud).
+// Resolved from the repo root (the producer runs with cwd = the web dir) via
+// DF_UI_SURFACES or an upward filesystem walk. `mergeDeclaredSurfaces` FAILS
+// CLOSED on a slug collision (a declared slug equal to an existing SURFACES[]
+// slug or another declaration): evidence is written to <out>/<slug>/, so a
+// shared slug would silently overwrite another surface's screenshots.
+const DECLARED_SURFACES = loadDeclaredSurfaces(process.cwd(), process.env);
+const ALL_SURFACES: readonly UiSurface[] = mergeDeclaredSurfaces(
+  SURFACES,
+  DECLARED_SURFACES,
+);
+
 const {
   armed: ARMED_SURFACES,
   uncovered: UNCOVERED_PATHS,
   smokeAllSurfaces: SMOKE_ALL_SURFACES,
-} = partitionChangedPaths(CHANGED_UI_PATHS, SURFACES, NON_SURFACE_GLOBS);
+} = partitionChangedPaths(CHANGED_UI_PATHS, ALL_SURFACES, NON_SURFACE_GLOBS);
 
 function routeOutDir(slug: string): string {
   return join(OUT_DIR, slug);
@@ -197,14 +228,16 @@ async function captureBefore(
 // NON_SURFACE_GLOBS to hide it.
 test("ui-route-coverage — every changed UI path maps to a capture surface", async () => {
   if (UNCOVERED_PATHS.length > 0) {
+    // Mode-aware message (#359): an engineer sees the SURFACES[] + declaration
+    // fix; a Designer-Mode / operator session (DF_MODE set) is routed to the
+    // designer-safe `.darkfactory/ui-surfaces.json` declaration and
+    // `/designer-handoff` as PROGRESS — never to a TS/spec edit. The coverage
+    // REQUIREMENT is identical either way; only the remediation copy changes.
     throw new Error(
-      "Evidence-Gated Validation playwright route: the following changed UI " +
-        "path(s) have NO mapped capture surface, so this route cannot produce " +
-        "real evidence for them and FAILS CLOSED:\n" +
-        UNCOVERED_PATHS.map((p) => `  - ${p}`).join("\n") +
-        "\n\nAdd a surface for the affected area to SURFACES[] in " +
-        "ui-route.producer.spec.ts. Do NOT widen NON_SURFACE_GLOBS to suppress " +
-        "a real UI change — that re-opens the false-positive hole this gate closes.",
+      formatUncoveredError({
+        uncovered: UNCOVERED_PATHS,
+        mode: process.env.DF_MODE,
+      }),
     );
   }
   expect(UNCOVERED_PATHS).toEqual([]);