@cueloop/client 0.1.0-alpha.7 → 0.1.0-alpha.70

package/src/diff-intraline.test.ts

@@ -0,0 +1,165 @@
+import { describe, expect, test } from "bun:test";
+import { intralineRunsByRow, wordLevelChanges, type IntralineRun } from "./diff-intraline";
+import type { DiffRow } from "./view-diff";
+
+function line(kind: DiffRow["kind"], text: string): DiffRow {
+  return { kind, text, file: "a.ts" };
+}
+
+function joinText(runs: IntralineRun[]): string {
+  return runs.map((run) => run.text).join("");
+}
+
+function changedText(runs: IntralineRun[]): string {
+  return runs
+    .filter((run) => run.changed)
+    .map((run) => run.text)
+    .join("");
+}
+
+describe("wordLevelChanges", () => {
+  test("marks only the changed word and stays whitespace-lossless", () => {
+    // Arrange
+    const oldText = "const foo = 1";
+    const newText = "const foo = 2";
+
+    // Act
+    const changes = wordLevelChanges(oldText, newText);
+
+    // Assert
+    expect(
+      changes
+        .filter((change) => change.kind === "common")
+        .map((change) => change.text)
+        .join(""),
+    ).toBe("const foo = ");
+    expect(
+      changes
+        .filter((change) => change.kind === "removed")
+        .map((change) => change.text)
+        .join(""),
+    ).toBe("1");
+    expect(
+      changes
+        .filter((change) => change.kind === "added")
+        .map((change) => change.text)
+        .join(""),
+    ).toBe("2");
+    // old text reconstructs from common + removed, new text from common + added
+    expect(
+      changes
+        .filter((change) => change.kind !== "added")
+        .map((change) => change.text)
+        .join(""),
+    ).toBe(oldText);
+    expect(
+      changes
+        .filter((change) => change.kind !== "removed")
+        .map((change) => change.text)
+        .join(""),
+    ).toBe(newText);
+  });
+});
+
+describe("intralineRunsByRow", () => {
+  test("pairs a deletion with its addition and highlights the changed word on each side", () => {
+    // Arrange
+    const rows = [
+      line("ctx", "unchanged"),
+      line("del", "const foo = 1"),
+      line("add", "const foo = 2"),
+    ];
+
+    // Act
+    const runsByRow = intralineRunsByRow(rows);
+
+    // Assert
+    const deletionRuns = runsByRow.get(1)!;
+    const additionRuns = runsByRow.get(2)!;
+
+    expect(joinText(deletionRuns)).toBe("const foo = 1");
+    expect(joinText(additionRuns)).toBe("const foo = 2");
+    expect(changedText(deletionRuns)).toBe("1");
+    expect(changedText(additionRuns)).toBe("2");
+  });
+
+  test("omits context rows and rows with no counterpart", () => {
+    // Arrange
+    const rows = [line("ctx", "keep me"), line("add", "brand new line")];
+
+    // Act
+    const runsByRow = intralineRunsByRow(rows);
+
+    // Assert
+    expect(runsByRow.size).toBe(0);
+  });
+
+  test("pairs only min(deletions, additions); the surplus stays a plain row", () => {
+    // Arrange - two deletions, one addition
+    const rows = [line("del", "alpha one"), line("del", "beta two"), line("add", "alpha ONE")];
+
+    // Act
+    const runsByRow = intralineRunsByRow(rows);
+
+    // Assert
+    expect(runsByRow.has(0)).toBe(true); // first deletion pairs with the addition
+    expect(runsByRow.has(1)).toBe(false); // second deletion has no counterpart
+    expect(runsByRow.has(2)).toBe(true);
+    expect(changedText(runsByRow.get(0)!)).toBe("one");
+    expect(changedText(runsByRow.get(2)!)).toBe("ONE");
+  });
+
+  test("a fully rewritten single line marks the whole line changed on both sides", () => {
+    // Arrange - a lone deletion opposite a lone addition is unambiguously one edit
+    const rows = [line("del", "aaa"), line("add", "zzz")];
+
+    // Act
+    const runsByRow = intralineRunsByRow(rows);
+
+    // Assert
+    expect(changedText(runsByRow.get(0)!)).toBe("aaa");
+    expect(changedText(runsByRow.get(1)!)).toBe("zzz");
+  });
+
+  test("in a shifted block, alignment matches the real counterpart, not by position", () => {
+    // Arrange - "beta gamma" is modified and an unrelated line sits at each end;
+    // positional pairing would word-diff "alpha" against "beta gamma delta"
+    const rows = [
+      line("del", "alpha"),
+      line("del", "beta gamma"),
+      line("add", "beta gamma delta"),
+      line("add", "zulu"),
+    ];
+
+    // Act
+    const runsByRow = intralineRunsByRow(rows);
+
+    // Assert
+    // the modified pair is found and word-diffed
+    expect(runsByRow.has(1)).toBe(true); // "beta gamma"
+    expect(runsByRow.has(2)).toBe(true); // "beta gamma delta"
+    expect(changedText(runsByRow.get(2)!).trim()).toBe("delta");
+    // the genuinely unrelated lines stay whole-line
+    expect(runsByRow.has(0)).toBe(false); // "alpha"
+    expect(runsByRow.has(3)).toBe(false); // "zulu"
+  });
+
+  test("in a multi-line block, related positional pairs still highlight the changed word", () => {
+    // Arrange - a same-shape 2x2 edit: each row lines up with its counterpart
+    const rows = [
+      line("del", "one two"),
+      line("del", "three four"),
+      line("add", "one TWO"),
+      line("add", "three FOUR"),
+    ];
+
+    // Act
+    const runsByRow = intralineRunsByRow(rows);
+
+    // Assert
+    expect(changedText(runsByRow.get(0)!)).toBe("two");
+    expect(changedText(runsByRow.get(1)!)).toBe("four");
+    expect(changedText(runsByRow.get(2)!)).toBe("TWO");
+    expect(changedText(runsByRow.get(3)!)).toBe("FOUR");
+  });
+});

package/src/diff-intraline.ts

@@ -0,0 +1,146 @@
+/**
+ * Intra-line word diff: the char-precise "what changed within this line" engine
+ * shared by the plan tracked-changes view and the diff review sheet. Backed by
+ * jsdiff diffWordsWithSpace, so it is punctuation-aware and whitespace-lossless:
+ * the run values always concatenate back to the exact inputs, which keeps quote
+ * anchors intact. Supersedes the coarse LCS wordDiff.
+ */
+
+import { diffWordsWithSpace } from "diff";
+import { lcsDiff } from "@cueloop/schema";
+import type { DiffRow } from "./view-diff";
+
+export type WordChangeKind = "common" | "added" | "removed";
+
+/** One word-level change between two strings; text is verbatim (lossless). */
+export interface WordChange {
+  text: string;
+  kind: WordChangeKind;
+}
+
+/** Word-level changes between two strings, whitespace-lossless and ordered. */
+export function wordLevelChanges(oldText: string, newText: string): WordChange[] {
+  return diffWordsWithSpace(oldText, newText).map((change) => ({
+    text: change.value,
+    kind: change.added ? "added" : change.removed ? "removed" : "common",
+  }));
+}
+
+/** One rendered segment of a diff row: changed marks the intra-line change. */
+export interface IntralineRun {
+  text: string;
+  changed: boolean;
+}
+
+function stripTrailingNewline(text: string): string {
+  return text.replace(/\n$/, "");
+}
+
+/**
+ * Char-precise intra-line runs for modified diff rows. Within a change block - a
+ * run of deletions immediately followed by additions - lines are aligned to their
+ * real counterpart (see alignedPairs) and each matched pair is word-diffed so the
+ * removed/added words are marked changed. Rows with no counterpart (pure add, pure
+ * delete, or an unmatched line in a shifted block) are omitted, so the caller
+ * renders those as a single run. Each row's runs concatenate back to that row's text.
+ */
+export function intralineRunsByRow(rows: DiffRow[]): Map<number, IntralineRun[]> {
+  const runsByRow = new Map<number, IntralineRun[]>();
+  let index = 0;
+
+  while (index < rows.length) {
+    if (rows[index]!.kind !== "del") {
+      index++;
+      continue;
+    }
+    const deletionStart = index;
+
+    while (index < rows.length && rows[index]!.kind === "del") index++;
+    const additionStart = index;
+
+    while (index < rows.length && rows[index]!.kind === "add") index++;
+    const deletionTexts = rows
+      .slice(deletionStart, additionStart)
+      .map((row) => stripTrailingNewline(row.text));
+    const additionTexts = rows
+      .slice(additionStart, index)
+      .map((row) => stripTrailingNewline(row.text));
+
+    for (const [deletionOffset, additionOffset] of alignedPairs(deletionTexts, additionTexts)) {
+      const changes = wordLevelChanges(
+        deletionTexts[deletionOffset]!,
+        additionTexts[additionOffset]!,
+      );
+
+      runsByRow.set(deletionStart + deletionOffset, sideRuns(changes, "removed"));
+      runsByRow.set(additionStart + additionOffset, sideRuns(changes, "added"));
+    }
+  }
+
+  return runsByRow;
+}
+
+/** Lines this similar (word-set overlap) are treated as the same line edited. */
+const SIMILAR_MIN_WORD_OVERLAP = 0.3;
+
+/** Whether two lines are the same line edited, by case-insensitive word-set
+ *  overlap - the matching gate, distinct from the case-sensitive word diff. */
+function linesSimilar(oldText: string, newText: string): boolean {
+  const words = (text: string) => new Set(text.toLowerCase().split(/\s+/).filter(Boolean));
+  const oldWords = words(oldText);
+  const newWords = words(newText);
+
+  if (oldWords.size === 0 && newWords.size === 0) return true;
+  let intersection = 0;
+
+  for (const word of oldWords) if (newWords.has(word)) intersection++;
+  const union = oldWords.size + newWords.size - intersection;
+
+  return union === 0 ? true : intersection / union >= SIMILAR_MIN_WORD_OVERLAP;
+}
+
+/**
+ * Pair each modified line with the addition it became. A lone deletion opposite
+ * a lone addition is one edit (always paired). Otherwise align the lines by
+ * similarity, order-preserving (LCS over `linesSimilar`), so an inserted, removed,
+ * or shifted line finds its real counterpart instead of mispairing by position -
+ * unmatched lines get no pair and render whole-line. Returns [deletionOffset,
+ * additionOffset] pairs into the block.
+ */
+function alignedPairs(deletionTexts: string[], additionTexts: string[]): Array<[number, number]> {
+  if (deletionTexts.length === 1 && additionTexts.length === 1) return [[0, 0]];
+  const pairs: Array<[number, number]> = [];
+  let deletionOffset = 0;
+  let additionOffset = 0;
+
+  for (const op of lcsDiff(deletionTexts, additionTexts, linesSimilar)) {
+    if (op.kind === "ctx") {
+      pairs.push([deletionOffset, additionOffset]);
+      deletionOffset++;
+      additionOffset++;
+    } else if (op.kind === "del") {
+      deletionOffset++;
+    } else {
+      additionOffset++;
+    }
+  }
+
+  return pairs;
+}
+
+/** Runs for one side of a word diff: common plus this side's changes, adjacent
+ *  runs of equal changed-ness coalesced so highlighting stays as few spans. */
+function sideRuns(changes: WordChange[], side: "added" | "removed"): IntralineRun[] {
+  const runs: IntralineRun[] = [];
+
+  for (const change of changes) {
+    if (change.kind !== "common" && change.kind !== side) continue;
+    const changed = change.kind === side;
+    const last = runs[runs.length - 1];
+
+    if (last && last.changed === changed) last.text += change.text;
+    else runs.push({ text: change.text, changed });
+  }
+
+  return runs;
+}

package/src/diff-syntax.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, test } from "bun:test";
+import { highlightJobs, spansByLine } from "./diff-syntax";
+import type { DiffRow } from "./view-diff";
+import type { SimpleHighlight } from "@opentui/core";
+
+function row(kind: DiffRow["kind"], text: string, file = "src/x.ts"): DiffRow {
+  return { kind, text, file };
+}
+
+describe("spansByLine", () => {
+  test("maps absolute offsets to line-relative spans", () => {
+    // Arrange
+    const source = "const x = 1;\nfoo";
+    const highlights: SimpleHighlight[] = [
+      [0, 5, "keyword"],
+      [6, 7, "variable"],
+      [13, 16, "variable"],
+    ];
+
+    // Act
+    const lineSpans = spansByLine(source, highlights);
+
+    // Assert
+    expect(lineSpans[0]).toEqual([
+      { start: 0, end: 5, group: "keyword" },
+      { start: 6, end: 7, group: "variable" },
+    ]);
+    expect(lineSpans[1]).toEqual([{ start: 0, end: 3, group: "variable" }]);
+  });
+
+  test("spreads a capture that crosses newlines onto every line it covers", () => {
+    // Arrange - one capture spanning both lines, as a block comment would
+    const source = "aa\nbb";
+    const highlights: SimpleHighlight[] = [[0, 5, "comment"]];
+
+    // Act
+    const lineSpans = spansByLine(source, highlights);
+
+    // Assert
+    expect(lineSpans[0]).toEqual([{ start: 0, end: 2, group: "comment" }]);
+    expect(lineSpans[1]).toEqual([{ start: 0, end: 2, group: "comment" }]);
+  });
+
+  test("a capture ending past the source clamps to its end instead of walking forever", () => {
+    // Arrange - offsets past the string, as byte offsets over a multi-byte line report
+    const source = "a│b\ncc";
+    const highlights: SimpleHighlight[] = [
+      [0, 9, "string"],
+      [12, 20, "comment"],
+    ];
+
+    // Act
+    const lineSpans = spansByLine(source, highlights);
+
+    // Assert - the covered text is colored to the end and the second capture paints nothing
+    expect(lineSpans[0]).toEqual([{ start: 0, end: 3, group: "string" }]);
+    expect(lineSpans[1]).toEqual([{ start: 0, end: 2, group: "string" }]);
+  });
+
+  test("resolves overlapping captures with later winning", () => {
+    // Arrange
+    const source = "foo";
+    const highlights: SimpleHighlight[] = [
+      [0, 3, "variable"],
+      [0, 3, "type"],
+    ];
+
+    // Act
+    const lineSpans = spansByLine(source, highlights);
+
+    // Assert
+    expect(lineSpans[0]).toEqual([{ start: 0, end: 3, group: "type" }]);
+  });
+});
+
+describe("highlightJobs", () => {
+  test("reconstructs old and new sides of a hunk with row indices", () => {
+    // Arrange
+    const rows = [
+      row("file", "src/x.ts", "src/x.ts"),
+      row("hunk", "@@ -1,2 +1,2 @@"),
+      row("ctx", "const a = 1;"),
+      row("del", "const b = 2;"),
+      row("add", "const b = 3;"),
+    ];
+
+    // Act
+    const jobs = highlightJobs(rows);
+
+    // Assert
+    // old side = context + deletion; new side = context + addition
+    expect(jobs).toEqual([
+      { filetype: "typescript", source: "const a = 1;\nconst b = 2;", rowIndexByLine: [2, 3] },
+      { filetype: "typescript", source: "const a = 1;\nconst b = 3;", rowIndexByLine: [2, 4] },
+    ]);
+  });
+
+  test("skips files with no known filetype", () => {
+    // Arrange
+    const rows = [
+      row("file", "notes/thing.unknownext", "notes/thing.unknownext"),
+      row("hunk", "@@"),
+      row("add", "whatever"),
+    ];
+
+    // Act
+    const jobs = highlightJobs(rows);
+
+    // Assert
+    expect(jobs).toEqual([]);
+  });
+});

package/src/diff-syntax.ts

@@ -0,0 +1,179 @@
+/**
+ * Syntax highlighting for diff rows: tree-sitter token colors mapped onto the
+ * diff sheet's hand-rolled rows, so annotation cards still interleave. A hunk is
+ * highlighted as a contiguous fragment (its context+addition lines as the new
+ * side, context+deletion lines as the old side) - never per single line, which
+ * would lose the multi-line grammar context - and the resulting token spans are
+ * mapped back to each row in line-relative columns. Async: the shared tree-sitter
+ * client resolves off the render path, so callers draw unstyled first.
+ */
+
+import { getTreeSitterClient, type SimpleHighlight } from "@opentui/core";
+import type { DiffRow } from "./view-diff";
+import { filetypeForPath } from "./components/syntax-highlight";
+
+/** A syntax-colored run within one row, in line-relative columns [start, end). */
+export interface SyntaxSpan {
+  start: number;
+  end: number;
+  group: string;
+}
+
+function stripTrailingNewline(text: string): string {
+  return text.replace(/\n$/, "");
+}
+
+interface HighlightJob {
+  filetype: string;
+  source: string;
+  /** Row index for each line of `source`, in order. */
+  rowIndexByLine: number[];
+}
+
+/**
+ * Split diff rows into per-hunk highlight jobs, one per side. A hunk's rows are
+ * contiguous file lines, so each side reconstructs to valid code; file/hunk
+ * header rows and files without a known filetype are skipped.
+ */
+export function highlightJobs(rows: DiffRow[]): HighlightJob[] {
+  const jobs: HighlightJob[] = [];
+  let oldLines: string[] = [];
+  let newLines: string[] = [];
+  let oldRowIndexByLine: number[] = [];
+  let newRowIndexByLine: number[] = [];
+  let filetype: string | undefined;
+
+  const flush = (): void => {
+    if (filetype) {
+      if (oldLines.length)
+        jobs.push({ filetype, source: oldLines.join("\n"), rowIndexByLine: oldRowIndexByLine });
+      if (newLines.length)
+        jobs.push({ filetype, source: newLines.join("\n"), rowIndexByLine: newRowIndexByLine });
+    }
+    oldLines = [];
+    newLines = [];
+    oldRowIndexByLine = [];
+    newRowIndexByLine = [];
+  };
+
+  for (let rowIndex = 0; rowIndex < rows.length; rowIndex++) {
+    const row = rows[rowIndex]!;
+
+    if (row.kind === "file" || row.kind === "hunk") {
+      flush();
+      filetype = row.kind === "file" ? filetypeForPath(row.file) : filetype;
+      continue;
+    }
+    const text = stripTrailingNewline(row.text);
+
+    if (row.kind === "ctx" || row.kind === "del") {
+      oldLines.push(text);
+      oldRowIndexByLine.push(rowIndex);
+    }
+    if (row.kind === "ctx" || row.kind === "add") {
+      newLines.push(text);
+      newRowIndexByLine.push(rowIndex);
+    }
+  }
+  flush();
+
+  return jobs;
+}
+
+/**
+ * Resolve one source's flat, possibly-overlapping token highlights into
+ * per-line spans. Offsets are absolute into `source`; later highlights win on
+ * overlap, and a highlight is clamped to the line its start falls on.
+ */
+export function spansByLine(source: string, highlights: SimpleHighlight[]): SyntaxSpan[][] {
+  const lineStarts: number[] = [0];
+
+  for (let index = 0; index < source.length; index++) {
+    if (source[index] === "\n") lineStarts.push(index + 1);
+  }
+  const lineOf = (offset: number): number => {
+    let low = 0;
+    let high = lineStarts.length - 1;
+
+    while (low < high) {
+      const mid = (low + high + 1) >> 1;
+
+      if (lineStarts[mid]! <= offset) low = mid;
+      else high = mid - 1;
+    }
+
+    return low;
+  };
+  // Per-line char->group, later highlights overriding, then coalesce into spans.
+  const groupsByLine: Array<Array<string | undefined>> = lineStarts.map((start, line) => {
+    const end = line + 1 < lineStarts.length ? lineStarts[line + 1]! - 1 : source.length;
+
+    return Array.from({ length: Math.max(0, end - start) }, () => undefined);
+  });
+
+  for (const [start, rawEnd, group] of highlights) {
+    // A capture can span newlines (block comments, template literals); color the
+    // covered columns on every line it crosses, not just the starting line. Offsets
+    // past the source (byte offsets from a multi-byte line) clamp to its end, or the
+    // walk below would sit on the last line forever.
+    const end = Math.min(rawEnd, source.length);
+    let cursor = Math.max(0, start);
+
+    while (cursor < end) {
+      const line = lineOf(cursor);
+      const lineStart = lineStarts[line]!;
+      const lineEnd = line + 1 < lineStarts.length ? lineStarts[line + 1]! - 1 : source.length;
+      const chars = groupsByLine[line]!;
+      const to = Math.min(end, lineEnd) - lineStart;
+
+      for (let column = cursor - lineStart; column < to; column++) chars[column] = group;
+      cursor = lineEnd + 1;
+    }
+  }
+
+  return groupsByLine.map((chars) => {
+    const spans: SyntaxSpan[] = [];
+
+    for (let column = 0; column < chars.length; column++) {
+      const group = chars[column];
+
+      if (group === undefined) continue;
+      const previous = spans[spans.length - 1];
+
+      if (previous && previous.group === group && previous.end === column)
+        previous.end = column + 1;
+      else spans.push({ start: column, end: column + 1, group });
+    }
+
+    return spans;
+  });
+}
+
+/**
+ * Highlight the diff's rows and return the token spans per row index. Rows in a
+ * file with no known filetype, and any row while highlighting is still resolving,
+ * are absent - the caller renders those unstyled.
+ */
+export async function highlightDiffRows(rows: DiffRow[]): Promise<Map<number, SyntaxSpan[]>> {
+  const spansByRow = new Map<number, SyntaxSpan[]>();
+  const jobs = highlightJobs(rows);
+
+  if (!jobs.length) return spansByRow;
+  const client = getTreeSitterClient();
+
+  await client.initialize();
+  for (const job of jobs) {
+    const result = await client.highlightOnce(job.source, job.filetype);
+
+    if (!result.highlights) continue;
+    const lineSpans = spansByLine(job.source, result.highlights);
+
+    job.rowIndexByLine.forEach((rowIndex, line) => {
+      const spans = lineSpans[line];
+
+      if (spans && spans.length) spansByRow.set(rowIndex, spans);
+    });
+  }
+
+  return spansByRow;
+}

package/src/discussions.ts

@@ -0,0 +1,79 @@
+/**
+ * Discussions: the conversations an annotated surface hosts inline. A root
+ * annotation, its replies, and the span they mark, grouped so two roots on the
+ * very same text read as one conversation. Pure over the resolved marks, so the
+ * plan thread view and the diff sheet group the same way.
+ */
+
+import type { Annotation, Thread } from "@cueloop/schema";
+import type { Mark } from "./view-plan";
+import { comparePositions, type TextSpan } from "./thread-selection";
+
+/** One conversation: a root annotation, its replies, and the span they mark. */
+export interface Discussion {
+  key: string;
+  /** The annotation replies attach to. */
+  rootId: string;
+  /** The block the card renders under: where the span ends. */
+  blockIndex: number;
+  span: TextSpan;
+  annotations: Annotation[];
+}
+
+export function spanKey(span: TextSpan): string {
+  return `${span.start.blockIndex}:${span.start.char}:${span.end.blockIndex}:${span.end.char}`;
+}
+
+/**
+ * Roots group by the span they resolved to (two roots on the very same text
+ * read as one conversation); replies join the discussion their replyTo names, or
+ * stand as roots when that root is gone.
+ */
+export function discussionsFrom(session: Thread, marks: Map<number, Mark[]>): Discussion[] {
+  const byId = new Map(session.annotations.map((annotation) => [annotation.id, annotation]));
+  const spanOf = new Map<string, TextSpan>();
+
+  for (const [displayIndex, blockMarks] of marks) {
+    for (const mark of blockMarks) {
+      if (!mark.annotationId || spanOf.has(mark.annotationId)) continue;
+      spanOf.set(
+        mark.annotationId,
+        mark.span ?? {
+          start: { blockIndex: displayIndex, char: mark.start },
+          end: { blockIndex: displayIndex, char: mark.end },
+        },
+      );
+    }
+  }
+  const resolved = [...spanOf.keys()].map((id) => byId.get(id)!).filter(Boolean);
+  const isRoot = (annotation: Annotation): boolean =>
+    annotation.replyTo === undefined || !spanOf.has(annotation.replyTo);
+  const grouped = new Map<string, Discussion>();
+  const discussionOfRoot = new Map<string, Discussion>();
+
+  for (const annotation of resolved.filter(isRoot)) {
+    const span = spanOf.get(annotation.id)!;
+    const key = spanKey(span);
+    const discussion = grouped.get(key) ?? {
+      key,
+      rootId: annotation.id,
+      blockIndex: span.end.blockIndex,
+      span,
+      annotations: [],
+    };
+
+    discussion.annotations.push(annotation);
+    grouped.set(key, discussion);
+    discussionOfRoot.set(annotation.id, discussion);
+  }
+  for (const annotation of resolved.filter((candidate) => !isRoot(candidate))) {
+    discussionOfRoot.get(annotation.replyTo!)?.annotations.push(annotation);
+  }
+  for (const discussion of grouped.values()) {
+    discussion.annotations.sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+  }
+
+  return [...grouped.values()].toSorted((left, right) =>
+    comparePositions(left.span.start, right.span.start),
+  );
+}