@cueloop/client 0.1.0-alpha.9 → 0.1.0-alpha.91

package/src/visual/contrast.test.ts

@@ -0,0 +1,35 @@
+import { expect, test } from "bun:test";
+import { themeForName } from "../theme-presets";
+import { contrastRatio, relativeLuminance, rgbColorFromHex } from "./contrast";
+
+test("relativeLuminance ranks black below white", () => {
+  expect(relativeLuminance([0, 0, 0])).toBe(0);
+  expect(relativeLuminance([255, 255, 255])).toBeCloseTo(1, 5);
+});
+
+test("contrastRatio is symmetric and peaks at black on white", () => {
+  expect(contrastRatio([0, 0, 0], [255, 255, 255])).toBeCloseTo(21, 0);
+  expect(contrastRatio([255, 255, 255], [0, 0, 0])).toBeCloseTo(21, 0);
+  expect(contrastRatio([100, 100, 100], [100, 100, 100])).toBeCloseTo(1, 5);
+});
+
+// The branded theme is terminal-through, so text sits on a real terminal background, not pure black or
+// white; gate each theme against a representative one so a low-contrast token cannot hide behind an extreme.
+const TERMINAL_BACKGROUND = {
+  dark: rgbColorFromHex("#1e1e2e"),
+  light: rgbColorFromHex("#f0f0f0"),
+} as const;
+const MIN_NORMAL_TEXT_CONTRAST = 4.5;
+
+for (const mode of ["dark", "light"] as const) {
+  test(`${mode} theme keeps text, muted text, and accent legible on its terminal`, () => {
+    const theme = themeForName("cueloop", mode);
+    const background = TERMINAL_BACKGROUND[mode];
+
+    for (const token of [theme.text, theme.textMuted, theme.accent]) {
+      expect(contrastRatio(rgbColorFromHex(token), background)).toBeGreaterThanOrEqual(
+        MIN_NORMAL_TEXT_CONTRAST,
+      );
+    }
+  });
+}

package/src/visual/contrast.ts

@@ -0,0 +1,33 @@
+/** WCAG relative luminance and contrast ratio for the visual-regression accessibility gate. */
+
+export type RgbColor = readonly [number, number, number];
+
+/** Parse a `#rrggbb` hexadecimal colour into an sRGB triple (channels 0-255). */
+export function rgbColorFromHex(hex: string): RgbColor {
+  const value = hex.replace("#", "");
+
+  return [
+    Number.parseInt(value.slice(0, 2), 16),
+    Number.parseInt(value.slice(2, 4), 16),
+    Number.parseInt(value.slice(4, 6), 16),
+  ];
+}
+
+/** WCAG relative luminance of an sRGB colour, 0 (black) to 1 (white). */
+export function relativeLuminance(rgb: RgbColor): number {
+  const linear = rgb.map((channel) => {
+    const ratio = channel / 255;
+
+    return ratio <= 0.03928 ? ratio / 12.92 : ((ratio + 0.055) / 1.055) ** 2.4;
+  });
+
+  return 0.2126 * linear[0]! + 0.7152 * linear[1]! + 0.0722 * linear[2]!;
+}
+
+/** WCAG contrast ratio between two sRGB colours, 1 (identical) to 21 (black on white). */
+export function contrastRatio(foreground: RgbColor, background: RgbColor): number {
+  const lighter = Math.max(relativeLuminance(foreground), relativeLuminance(background));
+  const darker = Math.min(relativeLuminance(foreground), relativeLuminance(background));
+
+  return (lighter + 0.05) / (darker + 0.05);
+}

package/src/walk.test.ts

@@ -0,0 +1,121 @@
+/** Pure walk projections: file steps, resume index, viewed counts, notes. */
+
+import { describe, expect, test } from "bun:test";
+import type { Annotation } from "@cueloop/schema";
+import { diffRows } from "./view-diff";
+import { firstUnviewedIndex, noteForFile, viewedCount, walkFiles, WALK_PREVIEW_ROWS } from "./walk";
+
+const PATCH = `diff --git a/src/a.ts b/src/a.ts
+index 111..222 100644
+--- a/src/a.ts
++++ b/src/a.ts
+@@ -1,3 +1,4 @@
+ export const a = 1;
+-export const b = 2;
++export const b = 3;
++export const c = 4;
+diff --git a/src/b.ts b/src/b.ts
+index 333..444 100644
+--- a/src/b.ts
++++ b/src/b.ts
+@@ -1,2 +1,2 @@
+ // header
+-old line
++new line
+diff --git a/src/c.ts b/src/c.ts
+index 555..666 100644
+--- a/src/c.ts
++++ b/src/c.ts
+@@ -1,1 +1,8 @@
+-gone
++one
++two
++three
++four
++five
++six
++seven
+`;
+
+const rows = diffRows(PATCH);
+const files = walkFiles(rows);
+
+describe("walkFiles", () => {
+  test("one step per changed file, in patch order, with counted stats", () => {
+    expect(files.map((file) => file.path)).toEqual(["src/a.ts", "src/b.ts", "src/c.ts"]);
+    expect(files[0]).toMatchObject({ added: 2, removed: 1 });
+    expect(files[1]).toMatchObject({ added: 1, removed: 1 });
+    expect(files[2]).toMatchObject({ added: 7, removed: 1 });
+  });
+
+  test("previews carry signed changed lines and cap at the preview budget", () => {
+    expect(files[0]!.preview).toEqual([
+      { sign: "-", text: "export const b = 2;" },
+      { sign: "+", text: "export const b = 3;" },
+      { sign: "+", text: "export const c = 4;" },
+    ]);
+    expect(files[2]!.preview.length).toBe(WALK_PREVIEW_ROWS);
+    expect(files[2]!.preview[0]).toEqual({ sign: "-", text: "gone" });
+  });
+});
+
+describe("firstUnviewedIndex", () => {
+  test("starts at the first file when nothing is viewed", () => {
+    expect(firstUnviewedIndex(files, new Set())).toBe(0);
+  });
+
+  test("skips viewed files - a resumed review lands on its first gap", () => {
+    expect(firstUnviewedIndex(files, new Set(["src/a.ts"]))).toBe(1);
+    expect(firstUnviewedIndex(files, new Set(["src/a.ts", "src/b.ts"]))).toBe(2);
+    // a viewed file later in the list does not block the earlier gap
+    expect(firstUnviewedIndex(files, new Set(["src/c.ts"]))).toBe(0);
+  });
+
+  test("all viewed resumes on the end card, not the first file", () => {
+    expect(firstUnviewedIndex(files, new Set(["src/a.ts", "src/b.ts", "src/c.ts"]))).toBe(
+      files.length,
+    );
+  });
+});
+
+describe("viewedCount", () => {
+  test("counts only paths present in the current file set", () => {
+    expect(viewedCount(files, new Set(["src/a.ts", "src/gone-in-rev-2.ts"]))).toBe(1);
+  });
+});
+
+describe("noteForFile", () => {
+  const note = (path: string, body: string): Annotation => ({
+    id: `a_${path}`,
+    kind: "note",
+    anchor: { quote: path, prefix: "", suffix: "" },
+    body,
+    createdAt: "now",
+  });
+
+  test("finds the note anchored at the file path", () => {
+    // Arrange
+    const annotations = [
+      note("src/a.ts", "Renames b and adds c."),
+      note("src/b.ts", "Swaps the line."),
+    ];
+
+    // Assert
+    expect(noteForFile(annotations, "src/b.ts")).toBe("Swaps the line.");
+    expect(noteForFile(annotations, "src/c.ts")).toBeUndefined();
+  });
+
+  test("ignores non-note annotations that happen to quote the path", () => {
+    // Arrange
+    const comment: Annotation = {
+      id: "a_1",
+      kind: "comment",
+      anchor: { quote: "src/a.ts", prefix: "", suffix: "" },
+      body: "not a note",
+      createdAt: "now",
+    };
+
+    // Assert
+    expect(noteForFile([comment], "src/a.ts")).toBeUndefined();
+  });
+});

package/src/walk.ts

@@ -0,0 +1,74 @@
+/**
+ * Guided-walk projections: pure helpers over the diff row model - no
+ * IO, no React. The walk steps through the changed files in patch order;
+ * which files were seen lives on the session record (viewedPaths), which
+ * file is on screen is view state in the session controller.
+ */
+
+import type { Annotation } from "@cueloop/schema";
+import type { DiffRow } from "./view-diff";
+
+/** One wizard step: a changed file with its stats and a short diff preview. */
+export interface WalkFile {
+  path: string;
+  added: number;
+  removed: number;
+  /** The first changed lines, signed (+/-), for the card's diff preview. */
+  preview: { sign: "+" | "-"; text: string }[];
+}
+
+/** Preview lines per card: enough to recognize the change, never a full diff. */
+export const WALK_PREVIEW_ROWS = 5;
+
+/** Collapse the diff rows into one walk step per changed file, in patch order. */
+export function walkFiles(rows: DiffRow[]): WalkFile[] {
+  const files: WalkFile[] = [];
+  const byPath = new Map<string, WalkFile>();
+
+  for (const row of rows) {
+    let file = byPath.get(row.file);
+
+    if (!file) {
+      file = { path: row.file, added: 0, removed: 0, preview: [] };
+      byPath.set(row.file, file);
+      files.push(file);
+    }
+    if (row.kind !== "add" && row.kind !== "del") continue;
+    if (row.kind === "add") file.added += 1;
+    else file.removed += 1;
+    if (file.preview.length < WALK_PREVIEW_ROWS) {
+      file.preview.push({
+        sign: row.kind === "add" ? "+" : "-",
+        text: row.text.replace(/\n$/, ""),
+      });
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Where the walk resumes: the first file not yet marked viewed. All files
+ * viewed = the end card (index === files.length), so a finished walk reopens
+ * on its summary instead of restarting.
+ */
+export function firstUnviewedIndex(files: WalkFile[], viewedPaths: ReadonlySet<string>): number {
+  const index = files.findIndex((file) => !viewedPaths.has(file.path));
+
+  return index === -1 ? files.length : index;
+}
+
+/** Viewed count against the CURRENT file set - stale paths never inflate it. */
+export function viewedCount(files: WalkFile[], viewedPaths: ReadonlySet<string>): number {
+  return files.filter((file) => viewedPaths.has(file.path)).length;
+}
+
+/**
+ * The agent's note for a file: an annotation with kind "note" whose anchor
+ * quote is the file path (the note contract in the shared review core).
+ */
+export function noteForFile(annotations: Annotation[], path: string): string | undefined {
+  return annotations.find(
+    (annotation) => annotation.kind === "note" && annotation.anchor.quote === path,
+  )?.body;
+}

package/src/workbench-snapshot.test.ts

@@ -0,0 +1,99 @@
+/** Sharing/serving a workbench thread freezes its live working-tree diff into the artifact so a remote
+ * reviewer, who cannot see the owner's tree, reads a stable snapshot; any other thread passes through. */
+
+import { describe, expect, mock, test } from "bun:test";
+import { historyFromLinear, viewFollowing, type Thread } from "@cueloop/schema";
+import { snapshotWorkbench } from "./workbench-snapshot";
+
+const AT = "2026-01-01T00:00:00.000Z";
+
+const STALE_FILES = [
+  { path: "src/a.ts", oldContents: "a\n", newContents: "b\n", status: "modified" as const },
+];
+const LIVE = {
+  patch: "FRESH PATCH",
+  files: [
+    { path: "src/a.ts", oldContents: "a\n", newContents: "c\n", status: "modified" as const },
+  ],
+};
+
+function diffThread(meta: Thread["artifact"]["meta"]): Thread {
+  return {
+    schemaVersion: "1",
+    id: "ses_wb",
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: { type: "diff", content: "STALE PATCH", files: STALE_FILES, meta },
+    revisions: [{ revision: 1, content: "STALE PATCH", submittedAt: AT }],
+    annotations: [
+      {
+        id: "n1",
+        kind: "comment",
+        anchor: { quote: "b", prefix: "", suffix: "" },
+        body: "why?",
+        createdAt: AT,
+      },
+    ],
+    message: null,
+    status: "pending",
+    createdAt: AT,
+  };
+}
+
+describe("snapshotWorkbench", () => {
+  test("freezes a workbench thread's live diff and drops the workbench flag", async () => {
+    const frozen = await snapshotWorkbench(
+      diffThread({ workbench: true, title: "Workbench" }),
+      async () => LIVE,
+    );
+
+    // the live diff is pinned into the artifact
+    expect(frozen.artifact.content).toBe("FRESH PATCH");
+    expect(frozen.artifact.files).toEqual(LIVE.files);
+    // the snapshot marker pins the render; the workbench marker stays so file-targeted feedback still paints
+    expect(frozen.artifact.meta.snapshot).toBe(true);
+    expect(frozen.artifact.meta.workbench).toBe(true);
+    expect(frozen.artifact.meta.title).toBe("Workbench");
+    // the thread is otherwise intact - same id, workspace, and annotations
+    expect(frozen.id).toBe("ses_wb");
+    expect(frozen.annotations).toHaveLength(1);
+  });
+
+  test("recaptures history so the share path rebuilds the fresh content, not the stale head", async () => {
+    // a workbench thread carries branch history whose head is the creation-time capture
+    const base = diffThread({ workbench: true });
+    const withHistory: Thread = { ...base, history: historyFromLinear(base) };
+
+    const frozen = await snapshotWorkbench(withHistory, async () => LIVE);
+
+    // viewFollowing (the share path) rebuilds content from history - it must yield the fresh patch
+    expect(viewFollowing(frozen).artifact.content).toBe("FRESH PATCH");
+  });
+
+  test("pins the captured source and revision in a shared workbench", async () => {
+    const frozen = await snapshotWorkbench(
+      diffThread({ workbench: true, vcs: "jj", vcsRevisionId: "old" }),
+      async () => ({
+        ...LIVE,
+        vcs: "jj",
+        source: { changeId: "change", revisionId: "new" },
+      }),
+    );
+
+    expect(frozen.artifact.meta.vcsRevisionId).toBe("new");
+    expect(frozen.revisions[0]).toMatchObject({
+      content: LIVE.patch,
+      files: LIVE.files,
+      source: { vcs: "jj", changeId: "change", revisionId: "new" },
+    });
+  });
+
+  test("passes a plain diff review through untouched and never queries the tree", async () => {
+    const session = diffThread({ title: "PR #7" });
+    const repoDiff = mock(async () => LIVE);
+
+    const result = await snapshotWorkbench(session, repoDiff);
+
+    expect(result).toBe(session);
+    expect(repoDiff).not.toHaveBeenCalled();
+  });
+});

package/src/workbench-snapshot.ts

@@ -0,0 +1,59 @@
+import {
+  recaptureMainHead,
+  type DiffFileContents,
+  type DiffSource,
+  type Thread,
+} from "@cueloop/schema";
+
+/** Reads the live working-tree diff for a repo root (the daemon's `repo.diff` RPC). */
+export type RepoDiff = (
+  repoRoot: string,
+  vcs?: string,
+) => Promise<{
+  patch: string;
+  files: DiffFileContents[];
+  source?: Omit<DiffSource, "vcs">;
+  vcs?: string;
+}>;
+
+/**
+ * Freeze a workbench thread's live working-tree diff into its artifact for a remote reviewer, who cannot
+ * see the owner's tree. The `snapshot` marker pins the render to this captured diff while keeping the
+ * workbench marker, so the reviewer still sees the file-targeted feedback already on the thread. Any other
+ * thread is already stable and passes through; the owner's own session keeps the original live thread.
+ */
+export async function snapshotWorkbench(session: Thread, repoDiff: RepoDiff): Promise<Thread> {
+  if (session.artifact.type !== "diff" || session.artifact.meta.workbench !== true) return session;
+
+  const { patch, files, source, vcs } = await repoDiff(
+    session.workspace.repoRoot,
+    session.artifact.meta.vcs,
+  );
+  const provider = vcs ?? session.artifact.meta.vcs;
+  const artifact = {
+    ...session.artifact,
+    content: patch,
+    files,
+    meta: {
+      ...session.artifact.meta,
+      snapshot: true,
+      vcs: provider,
+      vcsChangeId: source?.changeId,
+      vcsRevisionId: source?.revisionId,
+    },
+  };
+  // the share path rebuilds content from history; recapture the branch head so it matches the fresh patch
+  const history = session.history ? recaptureMainHead(session.history, patch) : session.history;
+  const revisions = session.revisions.map((revision, index) =>
+    index === session.revisions.length - 1
+      ? {
+          ...revision,
+          content: patch,
+          files,
+          source: provider && source ? { vcs: provider, ...source } : undefined,
+        }
+      : revision,
+  );
+
+  return { ...session, artifact, history, revisions };
+}