@demon-utils/playwright 0.1.5 → 0.1.6

package/src/recorder.ts

@@ -0,0 +1,74 @@
+import type { Page } from "@playwright/test";
+
+import type { ShowCommentaryOptions } from "./commentary.ts";
+import { showCommentary as defaultShowCommentary } from "./commentary.ts";
+
+export interface DemoStep {
+  text: string;
+  timestampSeconds: number;
+}
+
+type ShowCommentaryFn = (
+  page: Page,
+  options: ShowCommentaryOptions,
+) => Promise<void>;
+
+type TestStepFn = (
+  title: string,
+  body: () => Promise<void>,
+) => Promise<void>;
+
+export interface DemoRecorderOptions {
+  showCommentary?: ShowCommentaryFn;
+  testStep?: TestStepFn;
+}
+
+export class DemoRecorder {
+  private steps: DemoStep[] = [];
+  private startTime: number;
+  private showCommentaryFn: ShowCommentaryFn;
+  private testStepFn: TestStepFn | undefined;
+
+  constructor(options?: DemoRecorderOptions) {
+    this.startTime = Date.now();
+    this.showCommentaryFn = options?.showCommentary ?? defaultShowCommentary;
+    this.testStepFn = options?.testStep;
+  }
+
+  async step(
+    page: Page,
+    text: string,
+    options: { selector: string },
+  ): Promise<void> {
+    const body = async () => {
+      await this.showCommentaryFn(page, {
+        selector: options.selector,
+        text,
+      });
+
+      const timestampSeconds =
+        Math.round((Date.now() - this.startTime) / 100) / 10;
+
+      this.steps.push({ text, timestampSeconds });
+    };
+
+    if (this.testStepFn) {
+      await this.testStepFn(text, body);
+    } else {
+      await body();
+    }
+  }
+
+  getSteps(): DemoStep[] {
+    return [...this.steps];
+  }
+
+  async save(outputDir: string): Promise<void> {
+    const { join } = await import("node:path");
+    const { mkdirSync, writeFileSync } = await import("node:fs");
+
+    mkdirSync(outputDir, { recursive: true });
+    const filePath = join(outputDir, "demo-steps.json");
+    writeFileSync(filePath, JSON.stringify(this.steps, null, 2) + "\n");
+  }
+}

package/src/review-types.ts

@@ -1,9 +1,27 @@
 export interface DemoMetadata {
   file: string;
   summary: string;
-  annotations: Array<{ timestampSeconds: number; text: string }>;
+  steps: Array<{ timestampSeconds: number; text: string }>;
+}
+
+export type IssueSeverity = "major" | "minor" | "nit";
+
+export interface ReviewIssue {
+  severity: IssueSeverity;
+  description: string;
+}
+
+export type ReviewVerdict = "approve" | "request_changes";
+
+export interface CodeReview {
+  summary: string;
+  highlights: string[];
+  verdict: ReviewVerdict;
+  verdictReason: string;
+  issues: ReviewIssue[];
 }
 
 export interface ReviewMetadata {
   demos: DemoMetadata[];
+  review?: CodeReview;
 }

package/src/review.test.ts

@@ -3,116 +3,314 @@ import { describe, test, expect } from "bun:test";
 import type { SpawnFn } from "./review.ts";
 import {
   buildReviewPrompt,
+  extractJson,
   invokeClaude,
-  parseReviewMetadata,
+  parseLlmResponse,
 } from "./review.ts";
 
+function makeValidResponse(overrides?: Record<string, unknown>) {
+  return {
+    demos: [{ file: "login.webm", summary: "Shows a login flow" }],
+    review: {
+      summary: "Good changes overall",
+      highlights: ["Clean implementation"],
+      verdict: "approve",
+      verdictReason: "No major issues found",
+      issues: [],
+    },
+    ...overrides,
+  };
+}
+
 describe("buildReviewPrompt", () => {
   test("includes all filenames in the prompt", () => {
-    const prompt = buildReviewPrompt(["login-flow.webm", "signup.webm"]);
-    expect(prompt).toContain("- login-flow.webm");
-    expect(prompt).toContain("- signup.webm");
+    const stepsMap = {
+      "login-flow.webm": [],
+      "signup.webm": [],
+    };
+    const prompt = buildReviewPrompt({ filenames: ["login-flow.webm", "signup.webm"], stepsMap });
+    expect(prompt).toContain("login-flow.webm");
+    expect(prompt).toContain("signup.webm");
   });
 
   test("includes schema instructions", () => {
-    const prompt = buildReviewPrompt(["demo.webm"]);
+    const stepsMap = { "demo.webm": [] };
+    const prompt = buildReviewPrompt({ filenames: ["demo.webm"], stepsMap });
     expect(prompt).toContain('"demos"');
     expect(prompt).toContain('"file"');
     expect(prompt).toContain('"summary"');
-    expect(prompt).toContain('"annotations"');
-    expect(prompt).toContain('"timestampSeconds"');
+  });
+
+  test("does not include annotations in schema", () => {
+    const stepsMap = { "demo.webm": [] };
+    const prompt = buildReviewPrompt({ filenames: ["demo.webm"], stepsMap });
+    expect(prompt).not.toContain('"annotations"');
+  });
+
+  test("includes step data in prompt", () => {
+    const stepsMap = {
+      "login-flow.webm": [
+        { text: "Navigate to login", timestampSeconds: 0.5 },
+        { text: "Enter credentials", timestampSeconds: 3.2 },
+      ],
+    };
+    const prompt = buildReviewPrompt({ filenames: ["login-flow.webm"], stepsMap });
+    expect(prompt).toContain("[0.5s] Navigate to login");
+    expect(prompt).toContain("[3.2s] Enter credentials");
+    expect(prompt).toContain("Recorded steps:");
+  });
+
+  test("shows (no steps recorded) when steps array is empty", () => {
+    const stepsMap = { "demo.webm": [] };
+    const prompt = buildReviewPrompt({ filenames: ["demo.webm"], stepsMap });
+    expect(prompt).toContain("(no steps recorded)");
+  });
+
+  test("shows (no steps recorded) when video not in stepsMap", () => {
+    const stepsMap = { "other.webm": [] };
+    const prompt = buildReviewPrompt({ filenames: ["demo.webm"], stepsMap });
+    expect(prompt).toContain("(no steps recorded)");
+  });
+
+  test("includes git diff when provided", () => {
+    const prompt = buildReviewPrompt({
+      filenames: ["demo.webm"],
+      stepsMap: { "demo.webm": [] },
+      gitDiff: "diff --git a/file.ts\n+added line",
+    });
+    expect(prompt).toContain("## Git Diff");
+    expect(prompt).toContain("+added line");
+  });
+
+  test("does not include git diff section when not provided", () => {
+    const prompt = buildReviewPrompt({
+      filenames: ["demo.webm"],
+      stepsMap: { "demo.webm": [] },
+    });
+    expect(prompt).not.toContain("## Git Diff");
+  });
+
+  test("includes guidelines when provided", () => {
+    const prompt = buildReviewPrompt({
+      filenames: ["demo.webm"],
+      stepsMap: { "demo.webm": [] },
+      guidelines: ["# CLAUDE.md\nUse dependency injection"],
+    });
+    expect(prompt).toContain("## Coding Guidelines");
+    expect(prompt).toContain("Use dependency injection");
+  });
+
+  test("does not include guidelines section when empty", () => {
+    const prompt = buildReviewPrompt({
+      filenames: ["demo.webm"],
+      stepsMap: { "demo.webm": [] },
+      guidelines: [],
+    });
+    expect(prompt).not.toContain("## Coding Guidelines");
+  });
+
+  test("truncates git diff at 50k characters", () => {
+    const longDiff = "x".repeat(60_000);
+    const prompt = buildReviewPrompt({
+      filenames: ["demo.webm"],
+      stepsMap: { "demo.webm": [] },
+      gitDiff: longDiff,
+    });
+    expect(prompt).toContain("diff truncated at 50k characters");
+    expect(prompt).not.toContain("x".repeat(60_000));
+  });
+
+  test("includes review schema in prompt", () => {
+    const prompt = buildReviewPrompt({
+      filenames: ["demo.webm"],
+      stepsMap: { "demo.webm": [] },
+    });
+    expect(prompt).toContain('"review"');
+    expect(prompt).toContain('"verdict"');
+    expect(prompt).toContain('"issues"');
+    expect(prompt).toContain('"highlights"');
   });
 });
 
-describe("parseReviewMetadata", () => {
-  const validInput = JSON.stringify({
-    demos: [
-      {
-        file: "login.webm",
-        summary: "Shows a login flow",
-        annotations: [{ timestampSeconds: 0, text: "Start" }],
-      },
-    ],
+describe("extractJson", () => {
+  test("returns raw string when it is valid JSON", () => {
+    const json = '{"key": "value"}';
+    expect(extractJson(json)).toBe(json);
+  });
+
+  test("strips preamble text before JSON object", () => {
+    const raw = 'Here is the review.\n\n{"demos": []}';
+    expect(extractJson(raw)).toBe('{"demos": []}');
+  });
+
+  test("strips trailing text after JSON object", () => {
+    const raw = '{"demos": []}\n\nHope this helps!';
+    expect(extractJson(raw)).toBe('{"demos": []}');
+  });
+
+  test("strips both preamble and trailing text", () => {
+    const raw = 'Let me analyze this.\n{"demos": []}\nDone.';
+    expect(extractJson(raw)).toBe('{"demos": []}');
+  });
+
+  test("handles nested braces correctly", () => {
+    const json = '{"a": {"b": "c"}}';
+    const raw = `Some preamble\n${json}\nsome trailing`;
+    expect(extractJson(raw)).toBe(json);
+  });
+
+  test("throws when no JSON object found", () => {
+    expect(() => extractJson("no json here at all")).toThrow("No JSON object found");
   });
 
+  test("throws when only opening brace", () => {
+    expect(() => extractJson("just { nothing")).toThrow("No JSON object found");
+  });
+});
+
+describe("parseLlmResponse", () => {
   test("parses valid input correctly", () => {
-    const result = parseReviewMetadata(validInput);
+    const result = parseLlmResponse(JSON.stringify(makeValidResponse()));
     expect(result.demos).toHaveLength(1);
     expect(result.demos[0]!.file).toBe("login.webm");
     expect(result.demos[0]!.summary).toBe("Shows a login flow");
-    expect(result.demos[0]!.annotations).toHaveLength(1);
-    expect(result.demos[0]!.annotations[0]!.timestampSeconds).toBe(0);
-    expect(result.demos[0]!.annotations[0]!.text).toBe("Start");
+    expect(result.review.verdict).toBe("approve");
+    expect(result.review.summary).toBe("Good changes overall");
+    expect(result.review.highlights).toEqual(["Clean implementation"]);
+    expect(result.review.issues).toEqual([]);
+  });
+
+  test("parses response with issues", () => {
+    const input = makeValidResponse({
+      review: {
+        summary: "Needs work",
+        highlights: ["Good tests"],
+        verdict: "request_changes",
+        verdictReason: "Major bug found",
+        issues: [
+          { severity: "major", description: "Null pointer dereference" },
+          { severity: "minor", description: "Missing error message" },
+          { severity: "nit", description: "Inconsistent naming" },
+        ],
+      },
+    });
+    const result = parseLlmResponse(JSON.stringify(input));
+    expect(result.review.issues).toHaveLength(3);
+    expect(result.review.issues[0]!.severity).toBe("major");
+    expect(result.review.verdict).toBe("request_changes");
+  });
+
+  test("parses response with preamble text before JSON", () => {
+    const json = JSON.stringify(makeValidResponse());
+    const raw = `Let me review the changes.\n\n${json}`;
+    const result = parseLlmResponse(raw);
+    expect(result.demos).toHaveLength(1);
+    expect(result.review.verdict).toBe("approve");
   });
 
-  test("throws on invalid JSON", () => {
-    expect(() => parseReviewMetadata("not json")).toThrow("Invalid JSON");
+  test("parses response with trailing text after JSON", () => {
+    const json = JSON.stringify(makeValidResponse());
+    const raw = `${json}\n\nHope this helps!`;
+    const result = parseLlmResponse(raw);
+    expect(result.demos).toHaveLength(1);
+  });
+
+  test("throws when no JSON object found", () => {
+    expect(() => parseLlmResponse("not json at all")).toThrow("No JSON object found");
   });
 
   test("throws when demos array is missing", () => {
-    expect(() => parseReviewMetadata("{}")).toThrow("Missing 'demos' array");
+    expect(() => parseLlmResponse("{}")).toThrow("Missing 'demos' array");
   });
 
   test("throws when demos is not an array", () => {
-    expect(() => parseReviewMetadata('{"demos": "nope"}')).toThrow(
+    expect(() => parseLlmResponse('{"demos": "nope"}')).toThrow(
       "'demos' must be an array",
     );
   });
 
   test("throws when demo is missing file", () => {
     expect(() =>
-      parseReviewMetadata(
-        JSON.stringify({ demos: [{ summary: "x", annotations: [] }] }),
+      parseLlmResponse(
+        JSON.stringify({ demos: [{ summary: "x" }], review: makeValidResponse().review }),
       ),
     ).toThrow("'file' string");
   });
 
   test("throws when demo is missing summary", () => {
     expect(() =>
-      parseReviewMetadata(
-        JSON.stringify({ demos: [{ file: "x", annotations: [] }] }),
+      parseLlmResponse(
+        JSON.stringify({ demos: [{ file: "x" }], review: makeValidResponse().review }),
       ),
     ).toThrow("'summary' string");
   });
 
-  test("throws when annotations is missing", () => {
+  test("throws when review object is missing", () => {
     expect(() =>
-      parseReviewMetadata(
+      parseLlmResponse(
         JSON.stringify({ demos: [{ file: "x", summary: "s" }] }),
       ),
-    ).toThrow("'annotations' array");
+    ).toThrow("Missing 'review' object");
   });
 
-  test("throws when annotation has wrong timestampSeconds type", () => {
-    expect(() =>
-      parseReviewMetadata(
-        JSON.stringify({
-          demos: [
-            {
-              file: "x",
-              summary: "s",
-              annotations: [{ timestampSeconds: "0", text: "t" }],
-            },
-          ],
-        }),
-      ),
-    ).toThrow("'timestampSeconds' number");
+  test("throws when review.verdict is invalid", () => {
+    const input = makeValidResponse({
+      review: { ...makeValidResponse().review, verdict: "maybe" },
+    });
+    expect(() => parseLlmResponse(JSON.stringify(input))).toThrow(
+      "review.verdict must be 'approve' or 'request_changes'",
+    );
   });
 
-  test("throws when annotation has wrong text type", () => {
-    expect(() =>
-      parseReviewMetadata(
-        JSON.stringify({
-          demos: [
-            {
-              file: "x",
-              summary: "s",
-              annotations: [{ timestampSeconds: 0, text: 123 }],
-            },
-          ],
-        }),
-      ),
-    ).toThrow("'text' string");
+  test("throws when review.highlights is empty", () => {
+    const input = makeValidResponse({
+      review: { ...makeValidResponse().review, highlights: [] },
+    });
+    expect(() => parseLlmResponse(JSON.stringify(input))).toThrow(
+      "review.highlights must not be empty",
+    );
+  });
+
+  test("throws when review.summary is missing", () => {
+    const input = makeValidResponse({
+      review: { ...makeValidResponse().review, summary: 42 },
+    });
+    expect(() => parseLlmResponse(JSON.stringify(input))).toThrow(
+      "review.summary must be a string",
+    );
+  });
+
+  test("throws when review.verdictReason is missing", () => {
+    const input = makeValidResponse({
+      review: { ...makeValidResponse().review, verdictReason: null },
+    });
+    expect(() => parseLlmResponse(JSON.stringify(input))).toThrow(
+      "review.verdictReason must be a string",
+    );
+  });
+
+  test("throws when issue has invalid severity", () => {
+    const input = makeValidResponse({
+      review: {
+        ...makeValidResponse().review,
+        issues: [{ severity: "critical", description: "bad" }],
+      },
+    });
+    expect(() => parseLlmResponse(JSON.stringify(input))).toThrow(
+      "Each issue severity must be 'major', 'minor', or 'nit'",
+    );
+  });
+
+  test("throws when issue is missing description", () => {
+    const input = makeValidResponse({
+      review: {
+        ...makeValidResponse().review,
+        issues: [{ severity: "major" }],
+      },
+    });
+    expect(() => parseLlmResponse(JSON.stringify(input))).toThrow(
+      "Each issue must have a 'description' string",
+    );
   });
 });