@cueloop/client 0.1.0-alpha.4 → 0.1.0-alpha.41

package/src/view-plan.ts

@@ -0,0 +1,408 @@
+/**
+ * The plan projection pipeline: parse → display blocks (base vs working
+ * copy reconciled) → styled runs. Pure functions - the TUI renders the runs
+ * (the native text primitive wraps them), tests assert on them directly.
+ * One planning layer: rendering, navigation, and selection all derive from
+ * this module; the rendered/work offset mappings keep the native selection
+ * addressable over word-diffed blocks.
+ */
+
+import {
+  isAddressed,
+  lcsDiff,
+  parseBlocks,
+  resolveAnchor,
+  type Annotation,
+  type Block,
+} from "@cueloop/schema";
+import { wordLevelChanges } from "./diff-intraline";
+
+// ── display model ─────────────────────────────
+
+export type DisplayType = "same" | "mod" | "del" | "add";
+
+export interface DisplayBlock {
+  type: DisplayType;
+  kind: Block["kind"];
+  /** Block in the working copy (absent for del). */
+  work?: Block;
+  /** Block in the submitted revision (absent for add). */
+  base?: Block;
+  orderedItemNumber?: number;
+}
+
+export function displayText(block: DisplayBlock): string {
+  return (block.work ?? block.base)!.text;
+}
+
+/** Word-overlap similarity gate: an unrelated cut + insert must not merge. */
+function similar(baseBlock: Block, workBlock: Block): boolean {
+  if (baseBlock.kind !== workBlock.kind) return false;
+  const words = (text: string) => new Set(text.toLowerCase().split(/\s+/).filter(Boolean));
+  const baseWords = words(baseBlock.text);
+  const workWords = words(workBlock.text);
+  let intersection = 0;
+  for (const word of baseWords) if (workWords.has(word)) intersection++;
+  const union = baseWords.size + workWords.size - intersection;
+  return union === 0 ? true : intersection / union >= 0.3;
+}
+
+/** Reconcile base blocks vs working blocks into the display list. */
+export function buildDisplay(baseContent: string, workingContent?: string): DisplayBlock[] {
+  const baseBlocks = parseBlocks(baseContent);
+  if (workingContent === undefined) {
+    const display: DisplayBlock[] = baseBlocks.map((block) => ({
+      type: "same",
+      kind: block.kind,
+      work: block,
+      base: block,
+    }));
+    numberOrderedListItems(display);
+    return display;
+  }
+  const workBlocks = parseBlocks(workingContent);
+  const signature = (block: Block) => block.kind + "\0" + block.text;
+  const ops = lcsDiff(
+    baseBlocks,
+    workBlocks,
+    (baseBlock, workBlock) => signature(baseBlock) === signature(workBlock),
+  );
+  const display: DisplayBlock[] = [];
+  let opIndex = 0;
+  while (opIndex < ops.length) {
+    const op = ops[opIndex]!;
+    if (op.kind === "ctx") {
+      display.push({ type: "same", kind: op.newValue!.kind, work: op.newValue, base: op.oldValue });
+      opIndex++;
+      continue;
+    }
+    const deletedBlocks: Block[] = [];
+    const addedBlocks: Block[] = [];
+    while (opIndex < ops.length && ops[opIndex]!.kind !== "ctx") {
+      const changeOp = ops[opIndex]!;
+      if (changeOp.kind === "del") deletedBlocks.push(changeOp.oldValue!);
+      else addedBlocks.push(changeOp.newValue!);
+      opIndex++;
+    }
+    let deletedIndex = 0;
+    let addedIndex = 0;
+    while (deletedIndex < deletedBlocks.length && addedIndex < addedBlocks.length) {
+      if (similar(deletedBlocks[deletedIndex]!, addedBlocks[addedIndex]!)) {
+        display.push({
+          type: "mod",
+          kind: addedBlocks[addedIndex]!.kind,
+          base: deletedBlocks[deletedIndex]!,
+          work: addedBlocks[addedIndex]!,
+        });
+        deletedIndex++;
+        addedIndex++;
+      } else if (deletedBlocks.length - deletedIndex >= addedBlocks.length - addedIndex) {
+        display.push({
+          type: "del",
+          kind: deletedBlocks[deletedIndex]!.kind,
+          base: deletedBlocks[deletedIndex]!,
+        });
+        deletedIndex++;
+      } else {
+        display.push({
+          type: "add",
+          kind: addedBlocks[addedIndex]!.kind,
+          work: addedBlocks[addedIndex]!,
+        });
+        addedIndex++;
+      }
+    }
+    while (deletedIndex < deletedBlocks.length) {
+      display.push({
+        type: "del",
+        kind: deletedBlocks[deletedIndex]!.kind,
+        base: deletedBlocks[deletedIndex++]!,
+      });
+    }
+    while (addedIndex < addedBlocks.length) {
+      display.push({
+        type: "add",
+        kind: addedBlocks[addedIndex]!.kind,
+        work: addedBlocks[addedIndex++]!,
+      });
+    }
+  }
+  numberOrderedListItems(display);
+  return display;
+}
+
+function numberOrderedListItems(display: DisplayBlock[]): void {
+  let runLength = 0;
+  for (const block of display) {
+    if (block.kind === "oli") block.orderedItemNumber = ++runLength;
+    else runLength = 0;
+  }
+}
+
+// ── marks (annotation highlights + keyboard span) ──
+
+export type RunRole = "plain" | "ins" | "del" | "mark-comment" | "kspan" | "mark-focus";
+
+export interface StyleRun {
+  text: string;
+  role: RunRole;
+  /** Offset of this run in the block's working text; null for del runs. */
+  start: number | null;
+  annotationId?: string;
+}
+
+export interface Mark {
+  start: number;
+  end: number;
+  role: RunRole;
+  annotationId?: string;
+}
+
+/**
+ * Resolve annotations against the working blocks and group marks per display
+ * index. Working blocks are the blocks of (workingCopy ?? artifact) - the
+ * same list buildDisplay derived work entries from.
+ */
+export function marksByDisplay(
+  annotations: Annotation[],
+  display: DisplayBlock[],
+  focusedId?: string,
+): Map<number, Mark[]> {
+  // block list in "work space": display entries that carry a work block, in order
+  const workEntries = display
+    .map((block, displayIndex) => ({ block, displayIndex }))
+    .filter((entry) => entry.block.work !== undefined);
+  const workBlocks = workEntries.map((entry) => entry.block.work!);
+  const marksByIndex = new Map<number, Mark[]>();
+  for (const annotation of annotations) {
+    // an addressed annotation keeps its record but paints no highlight
+    if (isAddressed(annotation)) continue;
+    const resolved = resolveAnchor(annotation.anchor, workBlocks);
+    if (!resolved) continue;
+    const entry = workEntries[resolved.blockIndex];
+    if (!entry) continue;
+    const marks = marksByIndex.get(entry.displayIndex) ?? [];
+    marks.push({
+      start: resolved.start,
+      end: resolved.end,
+      role: annotation.id === focusedId ? "mark-focus" : "mark-comment",
+      annotationId: annotation.id,
+    });
+    marksByIndex.set(entry.displayIndex, marks);
+  }
+  return marksByIndex;
+}
+
+/** Base runs for a display block: plain text, or word-diff for mod blocks. */
+export function blockRuns(block: DisplayBlock, markup: boolean): StyleRun[] {
+  if (block.type === "mod" && markup) {
+    const changes = wordLevelChanges(block.base!.text, block.work!.text);
+    const runs: StyleRun[] = [];
+    let workOffset = 0;
+    for (const change of changes) {
+      if (change.kind === "removed") {
+        runs.push({ text: change.text, role: "del", start: null });
+      } else {
+        runs.push({
+          text: change.text,
+          role: change.kind === "added" ? "ins" : "plain",
+          start: workOffset,
+        });
+        workOffset += change.text.length;
+      }
+    }
+    return runs;
+  }
+  return [{ text: displayText(block), role: "plain", start: 0 }];
+}
+
+/** Split runs at mark boundaries; marks only bind to runs with offsets. */
+export function overlayMarks(runs: StyleRun[], marks: Mark[]): StyleRun[] {
+  if (!marks.length) return runs;
+  const splitRuns: StyleRun[] = [];
+  for (const run of runs) {
+    if (run.start === null) {
+      splitRuns.push(run);
+      continue;
+    }
+    const bounds = new Set<number>([0, run.text.length]);
+    for (const mark of marks) {
+      const boundStart = Math.max(0, mark.start - run.start);
+      const boundEnd = Math.min(run.text.length, mark.end - run.start);
+      if (boundStart < boundEnd) {
+        bounds.add(boundStart);
+        bounds.add(boundEnd);
+      }
+    }
+    const runStart = run.start;
+    const boundaries = [...bounds].sort((left, right) => left - right);
+    for (let boundaryIndex = 0; boundaryIndex < boundaries.length - 1; boundaryIndex++) {
+      const sliceStart = boundaries[boundaryIndex]!;
+      const sliceEnd = boundaries[boundaryIndex + 1]!;
+      if (sliceStart >= sliceEnd) continue;
+      const absoluteStart = runStart + sliceStart;
+      const mark = marks.find(
+        (candidate) => candidate.start <= absoluteStart && runStart + sliceEnd <= candidate.end,
+      );
+      splitRuns.push({
+        text: run.text.slice(sliceStart, sliceEnd),
+        // a mark never overrides ins/del emphasis; it rides on plain text
+        role: mark && run.role === "plain" ? mark.role : run.role,
+        start: absoluteStart,
+        annotationId: mark?.annotationId ?? run.annotationId,
+      });
+    }
+  }
+  return splitRuns;
+}
+
+/**
+ * Rendered-text offset of a work-text offset within a block's runs. The
+ * rendered text is every run's text in order (inline del runs included);
+ * only positioned runs carry work offsets. Drives the renderer's native
+ * selection from keyboard span offsets - the quote-anchor path depends on
+ * this mapping staying exact.
+ */
+export function renderedOffsetFor(runs: StyleRun[], workOffset: number): number | null {
+  let rendered = 0;
+  for (const run of runs) {
+    if (run.start !== null && workOffset >= run.start && workOffset < run.start + run.text.length) {
+      return rendered + (workOffset - run.start);
+    }
+    rendered += run.text.length;
+  }
+  return null;
+}
+
+/**
+ * Work-text range covered by a rendered-text selection [start, end). Del runs
+ * and other unpositioned text inside the selection contribute nothing; the
+ * result is the tightest work range whose text the selection touched.
+ */
+export function workRangeForRendered(
+  runs: StyleRun[],
+  renderedStart: number,
+  renderedEnd: number,
+): { start: number; end: number } | null {
+  let rendered = 0;
+  let range: { start: number; end: number } | null = null;
+  for (const run of runs) {
+    const runRenderedStart = rendered;
+    const runRenderedEnd = rendered + run.text.length;
+    rendered = runRenderedEnd;
+    if (run.start === null) continue;
+    const overlapStart = Math.max(renderedStart, runRenderedStart);
+    const overlapEnd = Math.min(renderedEnd, runRenderedEnd);
+    if (overlapEnd <= overlapStart) continue;
+    const workStart = run.start + (overlapStart - runRenderedStart);
+    const workEnd = run.start + (overlapEnd - runRenderedStart);
+    if (!range) range = { start: workStart, end: workEnd };
+    else {
+      range.start = Math.min(range.start, workStart);
+      range.end = Math.max(range.end, workEnd);
+    }
+  }
+  return range;
+}
+
+/** Line delta between two revision contents, for the sheet-header summary. */
+export function revisionDelta(
+  previousContent: string,
+  nextContent: string,
+): { added: number; removed: number } {
+  const ops = lcsDiff(previousContent.split("\n"), nextContent.split("\n"));
+  let added = 0;
+  let removed = 0;
+  for (const op of ops) {
+    if (op.kind === "add") added++;
+    else if (op.kind === "del") removed++;
+  }
+  return { added, removed };
+}
+
+// ── keyboard span mode ────────────────────────
+
+export interface SpanState {
+  displayIndex: number;
+  wordIndex: number;
+  wordEnd: number;
+  start: number;
+  end: number;
+}
+
+export function wordRanges(text: string): [number, number][] {
+  const ranges: [number, number][] = [];
+  const wordPattern = /\S+/g;
+  let match: RegExpExecArray | null;
+  while ((match = wordPattern.exec(text)))
+    ranges.push([match.index, match.index + match[0]!.length]);
+  return ranges;
+}
+
+export function startSpan(displayIndex: number, text: string): SpanState | null {
+  const words = wordRanges(text);
+  if (!words.length) return null;
+  return { displayIndex, wordIndex: 0, wordEnd: 0, start: words[0]![0], end: words[0]![1] };
+}
+
+/**
+ * Build a word-granular span from a raw char range (a mouse drag-selection),
+ * snapping to every word the range overlaps so w/b/l/h keep working after. Null
+ * when the range covers no word.
+ */
+export function spanFromRange(
+  displayIndex: number,
+  text: string,
+  start: number,
+  end: number,
+): SpanState | null {
+  const words = wordRanges(text);
+  const wordIndex = words.findIndex((word) => word[1] > start);
+  if (wordIndex === -1) return null;
+  let wordEnd = wordIndex;
+  for (let index = wordIndex; index < words.length && words[index]![0] < end; index++) {
+    wordEnd = index;
+  }
+  return {
+    displayIndex,
+    wordIndex,
+    wordEnd,
+    start: words[wordIndex]![0],
+    end: words[wordEnd]![1],
+  };
+}
+
+export function spanKey(span: SpanState, key: string, text: string): SpanState {
+  const words = wordRanges(text);
+  const nextSpan = { ...span };
+  const width = nextSpan.wordEnd - nextSpan.wordIndex;
+  if (key === "l") nextSpan.wordEnd = Math.min(words.length - 1, nextSpan.wordEnd + 1);
+  else if (key === "h") nextSpan.wordEnd = Math.max(nextSpan.wordIndex, nextSpan.wordEnd - 1);
+  else if (key === "w") {
+    const slidTo = Math.min(words.length - 1 - width, nextSpan.wordIndex + 1);
+    nextSpan.wordIndex = slidTo;
+    nextSpan.wordEnd = slidTo + width;
+  } else if (key === "b") {
+    const slidTo = Math.max(0, nextSpan.wordIndex - 1);
+    nextSpan.wordIndex = slidTo;
+    nextSpan.wordEnd = slidTo + width;
+  } else if (key === "$") nextSpan.wordEnd = words.length - 1;
+  else if (key === "0") {
+    nextSpan.wordEnd = width;
+    nextSpan.wordIndex = 0;
+  } else return span;
+  nextSpan.start = words[nextSpan.wordIndex]![0];
+  nextSpan.end = words[nextSpan.wordEnd]![1];
+  return nextSpan;
+}
+
+// ── working-copy block operations ─────────────
+
+/** The next work block after a display index (a del block re-enters before it). */
+export function nextWorkBlock(display: DisplayBlock[], displayIndex: number): Block | undefined {
+  for (let candidateIndex = displayIndex + 1; candidateIndex < display.length; candidateIndex++) {
+    const workBlock = display[candidateIndex]!.work;
+    if (workBlock) return workBlock;
+  }
+  return undefined;
+}

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,70 @@
+/**
+ * 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;
+}