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

package/src/anchor.ts

@@ -1,74 +1,409 @@
 /**
- * Anchor resolution: the quote-primary cascade (map #2, #22, verified in the
- * edit-mode deep-dive). Anchors resolve against the current block list:
- *   1. exact quote in a block (prefix/suffix selectors break ties,
- *      position hint breaks remaining ties)
- *   2. trimmed quote
- *   3. orphan - keep the quote for display, drop the highlight.
- * Never silently bind to the wrong text.
+ * Anchor resolution: the quote-primary cascade. Anchors resolve against the
+ * current block list, each tier tried only when the one above it misses:
+ *   1. exact      - the quote appears verbatim in a block
+ *   2. trimmed    - the quote appears once surrounding whitespace is dropped
+ *   3. normalized - the quote appears once a leading markdown block marker
+ *                   (bullet, heading, ordered, quote) is stripped, matching how
+ *                   the parser strips block text
+ *   4. fuzzy      - the quote was lightly edited but is still recognizably there
+ *   5. orphan     - none matched; keep the quote for display, drop the highlight
+ * Prefix/suffix selectors and the recorded position break ties within a tier.
+ * Never silently bind to the wrong text: fuzzy needs a high similarity floor.
+ *
+ * A quote may span consecutive blocks: its text is the blocks' text joined by
+ * BLOCK_SEPARATOR, and it resolves against the document joined the same way,
+ * so one comment can cover the tail of a paragraph and the bullets under it.
  */
 
 import type { Anchor } from "./types";
-import type { Block } from "./markdown";
+import { type Block, stripLeadingBlockMarker } from "./markdown";
+import { fuzzyFindBestMatch, newFuzzyBudget } from "./fuzzy";
 
-const CONTEXT = 24;
+/** Characters of surrounding text captured as prefix/suffix selectors. */
+const ANCHOR_CONTEXT_CHARS = 24;
+
+/** Minimum similarity a fuzzy match needs before the resolver will trust it. */
+const FUZZY_MINIMUM_SIMILARITY = 0.75;
+
+/** Joins block texts in a spanning quote and in the document it resolves against. */
+export const BLOCK_SEPARATOR = "\n\n";
+
+/** How the quote bound to the block text, weakest binding named last. */
+export type AnchorMatchStrategy = "exact" | "trimmed" | "normalized" | "fuzzy";
 
 export interface ResolvedAnchor {
   blockIndex: number;
   start: number;
+  /** Last block of the quote; equals blockIndex unless the quote spans blocks. */
+  endBlockIndex: number;
+  /** Offset within the end block. */
   end: number;
-  /** True when the quote had to be trimmed to bind. */
+  /** True whenever the binding was not an exact quote match. */
   approximate: boolean;
+  /** Which cascade tier bound the quote. */
+  strategy: AnchorMatchStrategy;
 }
 
-export function makeAnchor(blocks: Block[], blockIndex: number, start: number, end: number): Anchor {
-  const t = blocks[blockIndex]?.text ?? "";
-  return {
-    quote: t.slice(start, end),
-    prefix: t.slice(Math.max(0, start - CONTEXT), start),
-    suffix: t.slice(end, end + CONTEXT),
+export function makeAnchor(
+  blocks: Block[],
+  blockIndex: number,
+  start: number,
+  end: number,
+  endBlockIndex: number = blockIndex,
+): Anchor {
+  const startText = blocks[blockIndex]?.text ?? "";
+  const endText = blocks[endBlockIndex]?.text ?? "";
+  const quote = blocks
+    .slice(blockIndex, endBlockIndex + 1)
+    .map((block, offset, spanned) => {
+      const isFirst = offset === 0;
+      const isLast = offset === spanned.length - 1;
+
+      return block.text.slice(isFirst ? start : 0, isLast ? end : block.text.length);
+    })
+    .join(BLOCK_SEPARATOR);
+
+  const anchor: Anchor = {
+    quote,
+    prefix: startText.slice(Math.max(0, start - ANCHOR_CONTEXT_CHARS), start),
+    suffix: endText.slice(end, end + ANCHOR_CONTEXT_CHARS),
     blockIndex,
     start,
     end,
   };
+
+  if (endBlockIndex !== blockIndex) anchor.endBlockIndex = endBlockIndex;
+
+  return anchor;
 }
 
-interface Candidate extends ResolvedAnchor {
+interface Candidate {
+  blockIndex: number;
+  start: number;
+  end: number;
   score: number;
 }
 
-function findCandidates(anchor: Anchor, blocks: Block[], quote: string): Candidate[] {
-  const out: Candidate[] = [];
-  blocks.forEach((b, blockIndex) => {
-    const text = b.text;
-    for (let i = text.indexOf(quote); i !== -1; i = text.indexOf(quote, i + 1)) {
-      const pre = text.slice(Math.max(0, i - CONTEXT), i);
-      const suf = text.slice(i + quote.length, i + quote.length + CONTEXT);
-      let score = 0;
-      if (pre === anchor.prefix) score += 2;
-      if (suf === anchor.suffix) score += 2;
-      if (anchor.blockIndex === blockIndex) score += 1;
-      if (anchor.blockIndex === blockIndex && anchor.start === i) score += 1;
-      out.push({ blockIndex, start: i, end: i + quote.length, approximate: false, score });
+/** Score a candidate window by how well its context and position agree. */
+function contextScore(
+  anchor: Anchor,
+  blockIndex: number,
+  block: Block,
+  start: number,
+  end: number,
+): number {
+  const prefix = block.text.slice(Math.max(0, start - ANCHOR_CONTEXT_CHARS), start);
+  const suffix = block.text.slice(end, end + ANCHOR_CONTEXT_CHARS);
+  let score = 0;
+
+  if (prefix === anchor.prefix) score += 2;
+  if (suffix === anchor.suffix) score += 2;
+  if (anchor.blockIndex === blockIndex) score += 1;
+  if (anchor.blockIndex === blockIndex && anchor.start === start) score += 1;
+
+  return score;
+}
+
+/** Every verbatim occurrence of `quote` across the blocks, scored by context. */
+function findExactCandidates(anchor: Anchor, blocks: Block[], quote: string): Candidate[] {
+  const candidates: Candidate[] = [];
+
+  blocks.forEach((block, blockIndex) => {
+    const text = block.text;
+
+    for (
+      let matchStart = text.indexOf(quote);
+      matchStart !== -1;
+      matchStart = text.indexOf(quote, matchStart + 1)
+    ) {
+      const matchEnd = matchStart + quote.length;
+
+      candidates.push({
+        blockIndex,
+        start: matchStart,
+        end: matchEnd,
+        score: contextScore(anchor, blockIndex, block, matchStart, matchEnd),
+      });
+    }
+  });
+
+  return candidates;
+}
+
+/**
+ * How much a full context agreement (0-6) may nudge the fuzzy ranking. Kept far
+ * below any real similarity gap so text quality always leads and context only
+ * breaks near-ties - a stale position hint must never pull the anchor onto a
+ * meaningfully less-similar passage.
+ */
+const FUZZY_CONTEXT_TIE_BREAK = 0.01;
+
+/** Block indices to scan, spiralling out from the anchor's hinted block: hint, hint+1, hint-1, ... */
+function blockScanOrder(hint: number | undefined, count: number): number[] {
+  if (count <= 0) return [];
+  const first = Number.isInteger(hint) ? Math.min(Math.max(hint!, 0), count - 1) : 0;
+  const order = [first];
+
+  for (const step of Array.from({ length: count - 1 }, (_unused, index) => index + 1)) {
+    if (first + step < count) order.push(first + step);
+    if (first - step >= 0) order.push(first - step);
+  }
+
+  return order;
+}
+
+/**
+ * The best fuzzy window per block, ranked by similarity with context as a tiebreak. One work budget
+ * is shared across every block scan, so a stale anchor costs a single budget total, not one per
+ * block. Blocks are scanned outward from the anchor's hint, so a quote nudged a few blocks by an
+ * edit is reached before the budget runs out; a passage that moved far or is truly gone orphans.
+ */
+function findFuzzyCandidates(
+  anchor: Anchor,
+  blocks: Block[],
+  needle: string,
+  minimumSimilarity: number,
+): Candidate[] {
+  const candidates: Candidate[] = [];
+  const budget = newFuzzyBudget();
+
+  for (const blockIndex of blockScanOrder(anchor.blockIndex, blocks.length)) {
+    const block = blocks[blockIndex]!;
+    const match = fuzzyFindBestMatch(needle, block.text, minimumSimilarity, budget);
+
+    if (match !== null) {
+      const score =
+        match.similarity +
+        contextScore(anchor, blockIndex, block, match.start, match.end) * FUZZY_CONTEXT_TIE_BREAK;
+
+      candidates.push({ blockIndex, start: match.start, end: match.end, score });
     }
+    if (budget.remaining <= 0) break;
+  }
+
+  return candidates;
+}
+
+/** Highest-scoring candidate, or null when there are none. */
+function pickBest(candidates: Candidate[]): Candidate | null {
+  if (candidates.length === 0) return null;
+  candidates.sort((left, right) => right.score - left.score);
+
+  return candidates[0]!;
+}
+
+function resolved(candidate: Candidate, strategy: AnchorMatchStrategy): ResolvedAnchor {
+  return {
+    blockIndex: candidate.blockIndex,
+    start: candidate.start,
+    endBlockIndex: candidate.blockIndex,
+    end: candidate.end,
+    approximate: strategy !== "exact",
+    strategy,
+  };
+}
+
+/* ------------------------------------------------ quotes spanning blocks */
+
+/** The blocks as one document, with where each block's text starts in it. */
+interface JoinedDocument {
+  text: string;
+  starts: number[];
+}
+
+function joinBlocks(blocks: Block[]): JoinedDocument {
+  const starts: number[] = [];
+  let text = "";
+
+  blocks.forEach((block, blockIndex) => {
+    if (blockIndex > 0) text += BLOCK_SEPARATOR;
+    starts.push(text.length);
+    text += block.text;
   });
-  return out;
+
+  return { text, starts };
+}
+
+/**
+ * The block and in-block offset of a document offset. An offset inside a
+ * separator belongs to the block after it when it opens a range and to the
+ * block before it when it closes one, so a span never starts or ends on the
+ * blank line between blocks.
+ */
+interface BlockOffset {
+  blockIndex: number;
+  offset: number;
+}
+
+function locateInBlocks(
+  blocks: Block[],
+  starts: number[],
+  offset: number,
+  edge: "start" | "end",
+): BlockOffset {
+  let blockIndex = starts.findLastIndex((start) => start <= offset);
+
+  if (blockIndex < 0) blockIndex = 0;
+  const blockEnd = starts[blockIndex]! + blocks[blockIndex]!.text.length;
+
+  if (edge === "start" && offset >= blockEnd && blockIndex < blocks.length - 1) {
+    return { blockIndex: blockIndex + 1, offset: 0 };
+  }
+  if (edge === "end" && offset === starts[blockIndex] && blockIndex > 0) {
+    return {
+      blockIndex: blockIndex - 1,
+      offset: blocks[blockIndex - 1]!.text.length,
+    };
+  }
+
+  return {
+    blockIndex,
+    offset: Math.min(offset, blockEnd) - starts[blockIndex]!,
+  };
+}
+
+/** Context agreement plus position hints for a window of the joined document. */
+function documentScore(
+  anchor: Anchor,
+  documentText: string,
+  start: number,
+  end: number,
+  startBlockIndex: number,
+): number {
+  const prefix = documentText.slice(Math.max(0, start - ANCHOR_CONTEXT_CHARS), start);
+  const suffix = documentText.slice(end, end + ANCHOR_CONTEXT_CHARS);
+  let score = 0;
+
+  if (prefix === anchor.prefix) score += 2;
+  if (suffix === anchor.suffix) score += 2;
+  if (anchor.blockIndex === startBlockIndex) score += 1;
+
+  return score;
+}
+
+interface DocumentCandidate {
+  start: number;
+  end: number;
+  score: number;
+}
+
+function findSpanningExact(
+  anchor: Anchor,
+  documentText: string,
+  quote: string,
+  starts: number[],
+  blocks: Block[],
+): DocumentCandidate[] {
+  const candidates: DocumentCandidate[] = [];
+
+  for (
+    let matchStart = documentText.indexOf(quote);
+    matchStart !== -1;
+    matchStart = documentText.indexOf(quote, matchStart + 1)
+  ) {
+    const matchEnd = matchStart + quote.length;
+    const startBlockIndex = locateInBlocks(blocks, starts, matchStart, "start").blockIndex;
+
+    candidates.push({
+      start: matchStart,
+      end: matchEnd,
+      score: documentScore(anchor, documentText, matchStart, matchEnd, startBlockIndex),
+    });
+  }
+
+  return candidates;
+}
+
+function resolvedSpan(
+  blocks: Block[],
+  starts: number[],
+  candidate: DocumentCandidate,
+  strategy: AnchorMatchStrategy,
+): ResolvedAnchor {
+  const startPosition = locateInBlocks(blocks, starts, candidate.start, "start");
+  const endPosition = locateInBlocks(blocks, starts, candidate.end, "end");
+
+  return {
+    blockIndex: startPosition.blockIndex,
+    start: startPosition.offset,
+    endBlockIndex: endPosition.blockIndex,
+    end: endPosition.offset,
+    approximate: strategy !== "exact",
+    strategy,
+  };
+}
+
+/** The cascade for a quote that spans blocks, run over the joined document. */
+function resolveSpanningAnchor(anchor: Anchor, blocks: Block[]): ResolvedAnchor | null {
+  const document = joinBlocks(blocks);
+  const best = (candidates: DocumentCandidate[]): DocumentCandidate | null =>
+    candidates.toSorted((left, right) => right.score - left.score)[0] ?? null;
+
+  const exact = best(
+    findSpanningExact(anchor, document.text, anchor.quote, document.starts, blocks),
+  );
+
+  if (exact) return resolvedSpan(blocks, document.starts, exact, "exact");
+
+  const trimmedQuote = anchor.quote.trim();
+
+  if (trimmedQuote !== anchor.quote) {
+    const trimmed = best(
+      findSpanningExact(anchor, document.text, trimmedQuote, document.starts, blocks),
+    );
+
+    if (trimmed) return resolvedSpan(blocks, document.starts, trimmed, "trimmed");
+  }
+
+  const fuzzy = fuzzyFindBestMatch(trimmedQuote, document.text, FUZZY_MINIMUM_SIMILARITY);
+
+  if (fuzzy) {
+    return resolvedSpan(
+      blocks,
+      document.starts,
+      { start: fuzzy.start, end: fuzzy.end, score: 0 },
+      "fuzzy",
+    );
+  }
+
+  return null;
 }
 
 /** Resolve an anchor against the current blocks, or null when orphaned. */
 export function resolveAnchor(anchor: Anchor, blocks: Block[]): ResolvedAnchor | null {
   if (anchor.quote === "") return null;
-  let candidates = findCandidates(anchor, blocks, anchor.quote);
-  let approximate = false;
-  if (candidates.length === 0) {
-    const trimmed = anchor.quote.trim();
-    if (trimmed !== "" && trimmed !== anchor.quote) {
-      candidates = findCandidates(anchor, blocks, trimmed);
-      approximate = true;
-    }
+  if (anchor.quote.includes(BLOCK_SEPARATOR)) return resolveSpanningAnchor(anchor, blocks);
+
+  const exact = pickBest(findExactCandidates(anchor, blocks, anchor.quote));
+
+  if (exact) return resolved(exact, "exact");
+
+  const trimmedQuote = anchor.quote.trim();
+
+  if (trimmedQuote !== "" && trimmedQuote !== anchor.quote) {
+    const trimmed = pickBest(findExactCandidates(anchor, blocks, trimmedQuote));
+
+    if (trimmed) return resolved(trimmed, "trimmed");
   }
-  if (candidates.length === 0) return null;
-  candidates.sort((a, b) => b.score - a.score);
-  const best = candidates[0]!;
-  return { ...best, approximate };
+
+  const normalizedQuote = stripLeadingBlockMarker(anchor.quote).trim();
+
+  if (normalizedQuote !== "" && normalizedQuote !== trimmedQuote) {
+    const normalized = pickBest(findExactCandidates(anchor, blocks, normalizedQuote));
+
+    if (normalized) return resolved(normalized, "normalized");
+  }
+
+  const fuzzyNeedle = normalizedQuote !== "" ? normalizedQuote : trimmedQuote;
+
+  if (fuzzyNeedle !== "") {
+    const fuzzy = pickBest(
+      findFuzzyCandidates(anchor, blocks, fuzzyNeedle, FUZZY_MINIMUM_SIMILARITY),
+    );
+
+    if (fuzzy) return resolved(fuzzy, "fuzzy");
+  }
+
+  return null;
 }

package/src/diff.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { lcsDiff, unifiedDiff, unifiedDiffText, editStats, wordDiff } from "./diff";
+import { lcsDiff, unifiedDiff, unifiedDiffText, editStats } from "./diff";
 
 describe("unifiedDiff", () => {
   test("equal inputs return null, not an empty diff", () => {
@@ -7,12 +7,17 @@ describe("unifiedDiff", () => {
   });
 
   test("produces hunk headers with correct line numbers", () => {
+    // Arrange
     const oldText = ["l1", "l2", "l3", "l4", "l5", "l6", "l7", "l8"].join("\n");
     const newText = ["l1", "l2", "l3", "CHANGED", "l5", "l6", "l7", "l8"].join("\n");
-    const d = unifiedDiff(oldText, newText, 1)!;
-    expect(d[0]!.t).toBe("hunk");
-    expect(d[0]!.text).toBe("@@ -3,3 +3,3 @@");
-    expect(d.map((l) => l.text)).toEqual([
+
+    // Act
+    const diffLines = unifiedDiff(oldText, newText, 1)!;
+
+    // Assert
+    expect(diffLines[0]!.kind).toBe("hunk");
+    expect(diffLines[0]!.text).toBe("@@ -3,3 +3,3 @@");
+    expect(diffLines.map((line) => line.text)).toEqual([
       "@@ -3,3 +3,3 @@",
       " l3",
       "-l4",
@@ -22,29 +27,44 @@ describe("unifiedDiff", () => {
   });
 
   test("distant changes split into separate hunks", () => {
+    // Arrange
     const oldLines = Array.from({ length: 30 }, (_, i) => `line ${i + 1}`);
     const newLines = [...oldLines];
+
     newLines[1] = "first change";
     newLines[27] = "second change";
-    const d = unifiedDiff(oldLines.join("\n"), newLines.join("\n"), 2)!;
-    expect(d.filter((l) => l.t === "hunk").length).toBe(2);
+
+    // Act
+    const diffLines = unifiedDiff(oldLines.join("\n"), newLines.join("\n"), 2)!;
+
+    // Assert
+    expect(diffLines.filter((line) => line.kind === "hunk").length).toBe(2);
   });
 
   test("applies cleanly: reconstructing new text from old + diff", () => {
+    // Arrange
     const oldText = "keep\ndrop\nkeep2\nkeep3";
     const newText = "keep\nadded\nkeep2\nkeep3\ntail";
-    const d = unifiedDiff(oldText, newText, 50)!;
+
+    // Act
+    const diffLines = unifiedDiff(oldText, newText, 50)!;
+
+    // Assert
     const rebuilt: string[] = [];
-    for (const l of d) {
-      if (l.t === "hunk") continue;
-      if (l.t === "ctx" || l.t === "add") rebuilt.push(l.text.slice(1));
+
+    for (const line of diffLines) {
+      if (line.kind === "hunk") continue;
+      if (line.kind === "ctx" || line.kind === "add") rebuilt.push(line.text.slice(1));
     }
     expect(rebuilt.join("\n")).toBe(newText);
   });
 
   test("unifiedDiffText carries file headers and path", () => {
-    const t = unifiedDiffText("a", "b", "docs/plan.md")!;
-    expect(t.startsWith("--- a/docs/plan.md\n+++ b/docs/plan.md\n@@")).toBe(true);
+    // Act
+    const diffText = unifiedDiffText("a", "b", "docs/plan.md")!;
+
+    // Assert
+    expect(diffText.startsWith("--- a/docs/plan.md\n+++ b/docs/plan.md\n@@")).toBe(true);
   });
 });
 
@@ -54,19 +74,16 @@ describe("editStats", () => {
   });
 });
 
-describe("wordDiff", () => {
-  test("preserves whitespace tokens and reconstructs both sides", () => {
-    const ops = wordDiff("the quick brown fox", "the slow brown foxes");
-    const oldSide = ops.filter((o) => o.t !== "add").map((o) => o.a).join("");
-    const newSide = ops.filter((o) => o.t !== "del").map((o) => o.b).join("");
-    expect(oldSide).toBe("the quick brown fox");
-    expect(newSide).toBe("the slow brown foxes");
-  });
-});
-
 describe("lcsDiff", () => {
   test("custom equality", () => {
-    const ops = lcsDiff([{ v: 1 }, { v: 2 }], [{ v: 2 }, { v: 3 }], (x, y) => x.v === y.v);
-    expect(ops.map((o) => o.t)).toEqual(["del", "ctx", "add"]);
+    // Act
+    const ops = lcsDiff(
+      [{ v: 1 }, { v: 2 }],
+      [{ v: 2 }, { v: 3 }],
+      (oldItem, newItem) => oldItem.v === newItem.v,
+    );
+
+    // Assert
+    expect(ops.map((op) => op.kind)).toEqual(["del", "ctx", "add"]);
   });
 });