@farmslot/recipe-runner 0.23.0

package/visual-review/feedback-draft.mjs

@@ -0,0 +1,82 @@
+/**
+ * Restores a portable feedback document into the board's editable draft. The function is
+ * serialized into the static board script, so it must stay self-contained.
+ */
+export function feedbackDraftFromDocument(source, document) {
+  if (
+    !document ||
+    document.kind !== 'visual-review-feedback' ||
+    document.version !== 1 ||
+    !Array.isArray(document.surfaceNotes) ||
+    !Array.isArray(document.annotations)
+  ) {
+    throw new Error('Not a visual-review-feedback v1 document.');
+  }
+  if (document.source?.id !== source.id) {
+    throw new Error(
+      'Feedback belongs to source ' + document.source?.id + ', not ' + source.id + '.',
+    );
+  }
+  if (document.source.capturedAt !== source.capturedAt) {
+    throw new Error(
+      'Feedback was written for the capture of ' +
+        document.source.capturedAt +
+        '; this board shows the capture of ' +
+        source.capturedAt +
+        '.',
+    );
+  }
+  const surfaceIds = new Set(source.surfaces.map((surface) => surface.id));
+  const captureKeys = new Set(
+    source.surfaces.flatMap((surface) =>
+      surface.captures.map((capture) => surface.id + ':' + capture.id),
+    ),
+  );
+  const isUnit = (value) => typeof value === 'number' && value >= 0 && value <= 1;
+  const isExtent = (start, size) =>
+    isUnit(start) && typeof size === 'number' && size > 0 && start + size <= 1;
+  const ids = new Set();
+  const invalid = [];
+  const surfaceNotes = {};
+  document.surfaceNotes.forEach((note, index) => {
+    const valid =
+      surfaceIds.has(note?.surfaceId) &&
+      !Object.hasOwn(surfaceNotes, note.surfaceId) &&
+      typeof note.body === 'string' &&
+      note.body.trim() !== '';
+    if (valid) {
+      surfaceNotes[note.surfaceId] = note.body;
+    } else {
+      invalid.push('surfaceNotes[' + index + ']');
+    }
+  });
+  document.annotations.forEach((annotation, index) => {
+    const valid =
+      captureKeys.has(annotation?.surfaceId + ':' + annotation?.captureId) &&
+      typeof annotation.id === 'string' &&
+      annotation.id.trim() !== '' &&
+      !ids.has(annotation.id) &&
+      typeof annotation.body === 'string' &&
+      annotation.body.trim() !== '' &&
+      // Same #rrggbb rule as the protocol's feedback validator; this function cannot import it.
+      (annotation.color == null || /^#[0-9a-f]{6}$/iu.test(String(annotation.color))) &&
+      (annotation.shape === 'point'
+        ? isUnit(annotation.x) && isUnit(annotation.y)
+        : annotation.shape === 'area' &&
+          isExtent(annotation.x, annotation.width) &&
+          isExtent(annotation.y, annotation.height));
+    if (valid) ids.add(annotation.id);
+    else invalid.push('annotations[' + index + ']');
+  });
+  // Exports never contain these (blank entries are dropped on export), so any invalid entry
+  // means the wrong or an edited file.
+  if (invalid.length) {
+    throw new Error(
+      'Feedback has invalid entries: ' + invalid.join(', ') + '. Nothing was opened.',
+    );
+  }
+  return {
+    surfaceNotes,
+    annotations: document.annotations.map((annotation) => ({ ...annotation })),
+  };
+}

package/visual-review/index.d.mts

@@ -0,0 +1,41 @@
+import type { VisualReviewFeedbackDraft, VisualReviewSourceDocument } from '@farmslot/protocol';
+
+export interface GenerateReviewBoardOptions {
+  outputDir: string;
+  source: VisualReviewSourceDocument;
+  storageKey: string;
+  defaultPlatform?: string;
+}
+
+export function visualReviewFeedbackStorageKey(source: VisualReviewSourceDocument): string;
+
+export interface VisualReviewServer {
+  url: string;
+  host: string;
+  port: number;
+  close(): Promise<void>;
+}
+
+/** Reopens a portable feedback document as the board's editable draft for `source`. */
+export function feedbackDraftFromDocument(
+  source: VisualReviewSourceDocument,
+  document: unknown,
+): VisualReviewFeedbackDraft;
+export function generateReviewBoard(options: GenerateReviewBoardOptions): void;
+export function buildRecipeReviewBoard(options: {
+  artifactsDir: string;
+  outputDir: string;
+  platform: string;
+  recipePath: string;
+  sourceId: string;
+  project?: string;
+  runId?: string;
+  surfaceLocations?: Record<string, string>;
+  title?: string;
+  storageKey?: string;
+}): VisualReviewSourceDocument;
+export function serveReviewBoard(options: {
+  directory: string;
+  host?: string;
+  port?: number;
+}): Promise<VisualReviewServer>;

package/visual-review/index.mjs

@@ -0,0 +1,4 @@
+export { feedbackDraftFromDocument } from './feedback-draft.mjs';
+export { buildRecipeReviewBoard } from './recipe-board.mjs';
+export { generateReviewBoard, visualReviewFeedbackStorageKey } from './review-board.mjs';
+export { serveReviewBoard } from './server.mjs';

package/visual-review/recipe-board.mjs

@@ -0,0 +1,142 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { generateReviewBoard, visualReviewFeedbackStorageKey } from './review-board.mjs';
+
+function visualCaptureNodes(recipe, surfaceLocations) {
+  return Object.entries(recipe.workflow?.nodes ?? {})
+    .filter(
+      ([, node]) =>
+        node.action === 'ui.capture_surface' ||
+        (node.action === 'ui.screenshot' && node.visual_review),
+    )
+    .map(([nodeId, node]) => ({
+      id: nodeId,
+      title: node.label ?? nodeId,
+      nodeId,
+      proofTargets: node.proves ?? [],
+      ...(surfaceLocations[nodeId] ? { location: surfaceLocations[nodeId] } : {}),
+      ...(node.visual_review?.parent ? { parentId: node.visual_review.parent } : {}),
+      navigation: node.visual_review?.navigation ?? [],
+      ...(node.visual_review?.related ? { relatedSurfaceIds: node.visual_review.related } : {}),
+      imageTemplate: node.path ?? `screenshots/${nodeId}.png`,
+    }));
+}
+
+function resolveArtifact(root, relativePath, label) {
+  const resolvedRoot = path.resolve(root);
+  const resolved = path.resolve(resolvedRoot, relativePath);
+  if (resolved !== resolvedRoot && !resolved.startsWith(`${resolvedRoot}${path.sep}`)) {
+    throw new Error(`${label} must stay inside ${resolvedRoot}.`);
+  }
+  return resolved;
+}
+
+export function buildRecipeReviewBoard({
+  artifactsDir,
+  outputDir,
+  platform,
+  recipePath,
+  sourceId,
+  project,
+  runId,
+  surfaceLocations = {},
+  title,
+  storageKey,
+}) {
+  const recipe = JSON.parse(readFileSync(recipePath, 'utf8'));
+  const captures = visualCaptureNodes(recipe, surfaceLocations);
+  if (captures.length === 0) {
+    throw new Error(`Recipe has no visual review capture nodes: ${recipePath}`);
+  }
+
+  const resolvedOutputDir = path.resolve(outputDir);
+  mkdirSync(resolvedOutputDir, { recursive: true });
+  const sourcePath = path.join(resolvedOutputDir, 'visual-review-source.json');
+  const previous = existsSync(sourcePath) ? JSON.parse(readFileSync(sourcePath, 'utf8')) : null;
+  const previousSurfaces =
+    previous?.kind === 'visual-review-source' && previous.id === sourceId ? previous.surfaces : [];
+  const previousNavigationEdges =
+    previous?.kind === 'visual-review-source' && previous.id === sourceId
+      ? (previous.navigationEdges ?? [])
+      : [];
+  const byId = new Map(previousSurfaces.map((surface) => [surface.id, surface]));
+  const imageCopies = [];
+
+  for (const capture of captures) {
+    const relativeImagePath = capture.imageTemplate.replaceAll('{{params.platform}}', platform);
+    const sourceImagePath = resolveArtifact(
+      artifactsDir,
+      relativeImagePath,
+      'Recipe artifact path',
+    );
+    if (!existsSync(sourceImagePath)) {
+      throw new Error(`Recipe capture artifact is missing: ${sourceImagePath}`);
+    }
+    const destinationPath = resolveArtifact(
+      resolvedOutputDir,
+      relativeImagePath,
+      'Review image path',
+    );
+    imageCopies.push({ destinationPath, sourceImagePath });
+
+    const existing = byId.get(capture.id);
+    const captureId = `${platform}-${capture.id}`;
+    byId.set(capture.id, {
+      id: capture.id,
+      title: capture.title,
+      nodeId: capture.nodeId,
+      proofTargets: capture.proofTargets,
+      ...(capture.location ? { location: capture.location } : {}),
+      ...(capture.parentId ? { parentId: capture.parentId } : {}),
+      ...(capture.relatedSurfaceIds ? { relatedSurfaceIds: capture.relatedSurfaceIds } : {}),
+      captures: [
+        ...(existing?.captures ?? []).filter((candidate) => candidate.id !== captureId),
+        {
+          id: captureId,
+          platform,
+          image: { path: relativeImagePath, mimeType: 'image/png' },
+        },
+      ],
+    });
+  }
+
+  const surfaces = [...byId.values()];
+  const replacedTargets = new Set(captures.map((capture) => capture.id));
+  const navigationEdges = [
+    ...previousNavigationEdges.filter((edge) => !replacedTargets.has(edge.toSurfaceId)),
+    ...captures.flatMap((capture) =>
+      capture.navigation.map((edge) => ({
+        fromSurfaceId: edge.from,
+        toSurfaceId: capture.id,
+        kind: edge.kind,
+      })),
+    ),
+  ];
+  const platforms = [
+    ...new Set(surfaces.flatMap((surface) => surface.captures.map((capture) => capture.platform))),
+  ].sort();
+  const source = {
+    version: 1,
+    kind: 'visual-review-source',
+    id: sourceId,
+    title: title ?? recipe.title ?? sourceId,
+    capturedAt: new Date().toISOString(),
+    description: `${surfaces.length} surface${surfaces.length === 1 ? '' : 's'} · ${platforms.join('/')}`,
+    ...(project ? { project } : {}),
+    ...(runId ? { runId } : {}),
+    surfaces,
+    ...(navigationEdges.length > 0 ? { navigationEdges } : {}),
+  };
+  generateReviewBoard({
+    outputDir: resolvedOutputDir,
+    source,
+    storageKey: storageKey ?? visualReviewFeedbackStorageKey(source),
+    defaultPlatform: platform,
+  });
+  for (const { destinationPath, sourceImagePath } of imageCopies) {
+    mkdirSync(path.dirname(destinationPath), { recursive: true });
+    if (sourceImagePath !== destinationPath) copyFileSync(sourceImagePath, destinationPath);
+  }
+  return source;
+}