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

package/src/working-copy.test.ts

@@ -1,5 +1,15 @@
 import { describe, expect, test } from "bun:test";
-import { cutBlock, restoreBlock, restoreLine, sourceChunk } from "./working-copy";
+import {
+  applyTextCuts,
+  blockCutSourceRange,
+  cutBlock,
+  cutTextRange,
+  mergeTextCut,
+  restoreTextCut,
+  restoreBlock,
+  restoreLine,
+  sourceChunk,
+} from "./working-copy";
 import { parseBlocks, type Block } from "./markdown";
 
 const BASE = `# Plan
@@ -18,92 +28,267 @@ const y = 2;
 \`\`\`
 `;
 
-function block(md: string, text: string): Block {
-  return parseBlocks(md).find((b) => b.text.includes(text))!;
+function block(markdown: string, text: string): Block {
+  return parseBlocks(markdown).find((block) => block.text.includes(text))!;
 }
 
 describe("sourceChunk", () => {
   test("returns the exact source lines a block occupies", () => {
     expect(sourceChunk(BASE, block(BASE, "first item"))).toBe("- first item");
-    expect(sourceChunk(BASE, block(BASE, "spans two lines"))).toBe("A paragraph that\nspans two lines.");
+    expect(sourceChunk(BASE, block(BASE, "spans two lines"))).toBe(
+      "A paragraph that\nspans two lines.",
+    );
   });
 
   test("code block chunk includes both fence lines", () => {
-    expect(sourceChunk(BASE, block(BASE, "const x"))).toBe("```ts\nconst x = 1;\nconst y = 2;\n```");
+    expect(sourceChunk(BASE, block(BASE, "const x"))).toBe(
+      "```ts\nconst x = 1;\nconst y = 2;\n```",
+    );
   });
 });
 
 describe("cutBlock", () => {
   test("removes the block lines and the blank line before it", () => {
+    // Act
     const cut = cutBlock(BASE, block(BASE, "spans two lines"));
+
+    // Assert
     expect(cut).not.toContain("spans two lines");
     expect(cut).toContain("## Context\n\n- first item");
   });
 
   test("cut at the start of the document leaves the leading blank line", () => {
+    // Act
     const cut = cutBlock(BASE, block(BASE, "Plan"));
+
+    // Assert
     expect(cut).not.toContain("# Plan");
     expect(cut.trimStart().startsWith("## Context")).toBe(true);
   });
 
   test("cut at the end of the document keeps the rest intact", () => {
+    // Act
     const cut = cutBlock(BASE, block(BASE, "const x"));
+
+    // Assert
     expect(cut).not.toContain("const x");
     expect(cut).toContain("- second item");
   });
+
+  test.each(["Plan", "spans two lines", "first item", "const x"])(
+    "reports the exact source interval cut from %s",
+    (text) => {
+      const target = block(BASE, text);
+      const range = blockCutSourceRange(BASE, target);
+
+      expect(BASE.slice(0, range.start) + BASE.slice(range.end)).toBe(cutBlock(BASE, target));
+    },
+  );
+});
+
+describe("cutTextRange", () => {
+  test("cuts only the selected characters inside a block", () => {
+    const paragraph = block(BASE, "spans two lines");
+    const start = paragraph.text.indexOf("paragraph");
+    const cut = cutTextRange(BASE, paragraph, start, paragraph, start + "paragraph".length);
+
+    expect(cut).toContain("A  that\nspans two lines.");
+    expect(cut).toContain("## Context");
+    expect(cut).toContain("- first item");
+  });
+
+  test("preserves a list marker around a partial cut", () => {
+    const item = block(BASE, "first item");
+    const cut = cutTextRange(BASE, item, 0, item, "first ".length);
+
+    expect(cut).toContain("- item");
+    expect(cut).not.toContain("- first item");
+  });
+
+  test.each([
+    ["heading", "# remove keep", "#  keep"],
+    ["ordered list", "12. remove keep", "12.  keep"],
+    ["fenced code", "```ts\nremove keep\n```", "```ts\n keep\n```"],
+    ["frontmatter", "---\nname: remove keep\n---", "---\nname:  keep\n---"],
+    ["table", "| remove | keep |\n| --- | --- |", "|  | keep |\n| --- | --- |"],
+  ])("preserves %s source markers", (_label, source, expected) => {
+    const target = block(source, "remove");
+    const start = target.text.indexOf("remove");
+
+    expect(cutTextRange(source, target, start, target, start + "remove".length)).toBe(expected);
+  });
+
+  test("cuts an exact range across marked quote lines", () => {
+    const source = "> keep alpha\n> remove beta\n> keep gamma";
+    const quote = parseBlocks(source)[0]!;
+    const start = quote.text.indexOf("alpha");
+    const end = quote.text.indexOf("keep gamma");
+
+    const cut = cutTextRange(source, quote, start, quote, end);
+
+    expect(cut).toBe("> keep keep gamma");
+  });
+
+  test("cuts an exact range across separate blocks", () => {
+    const source = "Keep before remove this.\n\n- remove that keep after";
+    const blocks = parseBlocks(source);
+    const first = blocks[0]!;
+    const second = blocks[1]!;
+    const start = first.text.indexOf("remove");
+    const end = second.text.indexOf("keep after");
+
+    const cut = cutTextRange(source, first, start, second, end);
+
+    expect(cut).toBe("Keep before keep after");
+  });
+});
+
+describe("exact text Cuts", () => {
+  test("stores and applies the selected source characters exactly", () => {
+    const source = "It lands under unin Threads then in the sidebar.";
+    const start = source.indexOf("under");
+    const end = source.indexOf(" in the sidebar");
+    const cuts = mergeTextCut(source, [], start, end);
+
+    expect(cuts).toEqual([{ start, end, quote: "under unin Threads then" }]);
+    expect(applyTextCuts(source, cuts)).toBe("It lands  in the sidebar.");
+  });
+
+  test("merges overlapping and adjacent ranges in one linear source interval", () => {
+    const source = "alpha beta gamma delta";
+    const first = mergeTextCut(source, [], 6, 10);
+    const merged = mergeTextCut(source, first, 10, 16);
+
+    expect(merged).toEqual([{ start: 6, end: 16, quote: "beta gamma" }]);
+    expect(applyTextCuts(source, merged)).toBe("alpha  delta");
+  });
+
+  test("returns the original references for no-op ranges", () => {
+    const source = "unchanged";
+    const cuts = [{ start: 0, end: 2, quote: "un" }];
+
+    expect(mergeTextCut(source, cuts, 4, 4)).toBe(cuts);
+    expect(applyTextCuts(source, [])).toBe(source);
+  });
+
+  test("applies out-of-order Cuts and ignores stale or overlapping records", () => {
+    const source = "alpha beta gamma";
+
+    expect(
+      applyTextCuts(source, [
+        { start: 11, end: 16, quote: "gamma" },
+        { start: 0, end: 5, quote: "alpha" },
+        { start: 2, end: 8, quote: "stale" },
+        { start: 6, end: 10, quote: "beta" },
+      ]),
+    ).toBe("  ");
+  });
+
+  test("restores an exact subrange without disturbing the rest of its Cut", () => {
+    const source = "alpha beta gamma delta";
+    const cuts = mergeTextCut(source, [], 6, 16);
+    const restored = restoreTextCut(source, cuts, 11, 16);
+
+    expect(restored).toEqual([{ start: 6, end: 11, quote: "beta " }]);
+    expect(applyTextCuts(source, restored ?? [])).toBe("alpha gamma delta");
+  });
+
+  test("does not restore across separate Cuts", () => {
+    const source = "alpha beta gamma delta";
+    const cuts = [
+      { start: 6, end: 10, quote: "beta" },
+      { start: 11, end: 16, quote: "gamma" },
+    ];
+
+    expect(restoreTextCut(source, cuts, 6, 16)).toBeNull();
+  });
 });
 
 describe("restoreBlock", () => {
   test("restoring the only cut returns undefined - back to pristine", () => {
-    const li = block(BASE, "second item");
-    const cut = cutBlock(BASE, li);
+    // Arrange
+    const listItem = block(BASE, "second item");
+    const cut = cutBlock(BASE, listItem);
     // the cut block re-enters before the code fence, the next surviving block
-    const next = parseBlocks(cut).find((b) => b.kind === "code");
-    const restored = restoreBlock(BASE, cut, li, restoreLine(next, cut.split("\n").length));
+    const next = parseBlocks(cut).find((candidate) => candidate.kind === "code");
+
+    // Act
+    const restored = restoreBlock(BASE, cut, listItem, restoreLine(next, cut.split("\n").length));
+
+    // Assert
     expect(restored).toBeUndefined();
   });
 
   test("restore after another edit returns the merged working copy", () => {
-    const li = block(BASE, "second item");
-    const edited = cutBlock(BASE, li).replace("first item", "first item reworded");
-    const next = parseBlocks(edited).find((b) => b.kind === "code");
-    const restored = restoreBlock(BASE, edited, li, restoreLine(next, edited.split("\n").length));
+    // Arrange
+    const listItem = block(BASE, "second item");
+    const edited = cutBlock(BASE, listItem).replace("first item", "first item reworded");
+    const next = parseBlocks(edited).find((candidate) => candidate.kind === "code");
+
+    // Act
+    const restored = restoreBlock(
+      BASE,
+      edited,
+      listItem,
+      restoreLine(next, edited.split("\n").length),
+    );
+
+    // Assert
     expect(restored).toContain("- second item");
     expect(restored).toContain("first item reworded");
   });
 
   test("restore at the end of the document (no next block)", () => {
+    // Arrange
     const code = block(BASE, "const x");
     const cut = cutBlock(BASE, code);
+
+    // Act
     const restored = restoreBlock(BASE, cut, code, restoreLine(undefined, cut.split("\n").length));
+
+    // Assert
     expect(restored).toBeUndefined();
   });
 
   test("restore a multi-line block round-trips to pristine", () => {
-    const p = block(BASE, "spans two lines");
-    const cut = cutBlock(BASE, p);
-    const next = parseBlocks(cut).find((b) => b.text === "first item");
-    const restored = restoreBlock(BASE, cut, p, restoreLine(next, cut.split("\n").length));
+    // Arrange
+    const paragraph = block(BASE, "spans two lines");
+    const cut = cutBlock(BASE, paragraph);
+    const next = parseBlocks(cut).find((block) => block.text === "first item");
+
+    // Act
+    const restored = restoreBlock(BASE, cut, paragraph, restoreLine(next, cut.split("\n").length));
+
+    // Assert
     expect(restored).toBeUndefined();
   });
 
   test("signature rule ignores blank-line layout but not text changes", () => {
-    const li = block(BASE, "second item");
-    const cut = cutBlock(BASE, li);
-    const next = parseBlocks(cut).find((b) => b.kind === "code");
+    // Arrange
+    const listItem = block(BASE, "second item");
+    const cut = cutBlock(BASE, listItem);
+    const next = parseBlocks(cut).find((candidate) => candidate.kind === "code");
     const line = restoreLine(next, cut.split("\n").length);
+
+    // Assert
     // extra blank lines elsewhere do not block pristine detection
-    expect(restoreBlock(BASE, cut.replace("## Context", "## Context\n"), li, line)).toBeUndefined();
+    expect(
+      restoreBlock(BASE, cut.replace("## Context", "## Context\n"), listItem, line),
+    ).toBeUndefined();
     // a real text change keeps the working copy alive
-    const changed = restoreBlock(BASE, cut.replace("first", "1st"), li, line);
+    const changed = restoreBlock(BASE, cut.replace("first", "1st"), listItem, line);
+
     expect(changed).toContain("1st item");
   });
 });
 
 describe("restoreLine", () => {
   test("next surviving block's start, or the line count at the end", () => {
-    const li = block(BASE, "first item");
-    expect(restoreLine(li, 99)).toBe(li.lineStart);
+    // Arrange
+    const listItem = block(BASE, "first item");
+
+    // Assert
+    expect(restoreLine(listItem, 99)).toBe(listItem.lineStart);
     expect(restoreLine(undefined, 99)).toBe(99);
   });
 });

package/src/working-copy.ts

@@ -1,15 +1,95 @@
-/**
- * Working-copy block surgery: the only module that slices raw source text by
- * Block line ranges. Cut removes a block's lines; restore re-inserts a base
- * block's chunk and reports when the working copy round-trips back to the
- * submitted revision (pristine). Callers never touch lineStart/lineEnd.
- */
+/** Working-copy source surgery for block and character cuts plus block restoration. */
+
+import { parseBlocks, sourceOffsetAt, type Block } from "./markdown";
+import type { TextCut } from "./types";
+
+/** Add one source range and normalize overlaps without copying on a no-op. */
+export function mergeTextCut(
+  source: string,
+  cuts: readonly TextCut[],
+  start: number,
+  end: number,
+): TextCut[] {
+  const boundedStart = Math.max(0, Math.min(start, source.length));
+  const boundedEnd = Math.max(boundedStart, Math.min(end, source.length));
+
+  if (boundedEnd === boundedStart) {
+    // SAFETY: a no-op returns the caller's array unchanged; callers never mutate the result.
+    return cuts as TextCut[];
+  }
+  const ranges = [
+    ...cuts.map((cut) => ({ start: cut.start, end: cut.end })),
+    { start: boundedStart, end: boundedEnd },
+  ]
+    .map((range) => ({
+      start: Math.max(0, Math.min(range.start, source.length)),
+      end: Math.max(0, Math.min(range.end, source.length)),
+    }))
+    .filter((range) => range.end > range.start)
+    .toSorted((left, right) => left.start - right.start || left.end - right.end);
+  const merged: Array<{ start: number; end: number }> = [];
+
+  for (const range of ranges) {
+    const previous = merged.at(-1);
+
+    if (previous && range.start <= previous.end) previous.end = Math.max(previous.end, range.end);
+    else merged.push(range);
+  }
+
+  return merged.map((range) => ({
+    ...range,
+    quote: source.slice(range.start, range.end),
+  }));
+}
+
+/** Restore a selected part of one contiguous character Cut. */
+export function restoreTextCut(
+  source: string,
+  cuts: readonly TextCut[],
+  start: number,
+  end: number,
+): TextCut[] | null {
+  const cutIndex = cuts.findIndex((cut) => cut.start <= start && end <= cut.end);
 
-import { parseBlocks, type Block } from "./markdown";
+  if (cutIndex === -1 || end <= start) return null;
+  const cut = cuts[cutIndex]!;
+  const replacements: TextCut[] = [];
+
+  if (cut.start < start) {
+    replacements.push({ start: cut.start, end: start, quote: source.slice(cut.start, start) });
+  }
+  if (end < cut.end) {
+    replacements.push({ start: end, end: cut.end, quote: source.slice(end, cut.end) });
+  }
+
+  return [...cuts.slice(0, cutIndex), ...replacements, ...cuts.slice(cutIndex + 1)];
+}
+
+/** Apply valid source ranges in source order, ignoring stale or overlapping records. */
+export function applyTextCuts(source: string, cuts: readonly TextCut[]): string {
+  if (cuts.length === 0) return source;
+  let cursor = 0;
+  const pieces: string[] = [];
+
+  for (const cut of cuts.toSorted(
+    (left, right) => left.start - right.start || left.end - right.end,
+  )) {
+    if (cut.start < cursor || cut.start < 0 || cut.end > source.length || cut.end <= cut.start)
+      continue;
+    if (source.slice(cut.start, cut.end) !== cut.quote) continue;
+
+    pieces.push(source.slice(cursor, cut.start));
+    cursor = cut.end;
+  }
+  pieces.push(source.slice(cursor));
+
+  return pieces.join("");
+}
 
 /** Chunk of the base source a block occupies (for restore and display). */
 export function sourceChunk(base: string, block: Block): string {
   const lines = base.split("\n");
+
   return lines.slice(block.lineStart, block.lineEnd + 1).join("\n");
 }
 
@@ -18,10 +98,50 @@ export function cutBlock(working: string, block: Block): string {
   const lines = working.split("\n");
   const before = lines.slice(0, block.lineStart);
   const after = lines.slice(block.lineEnd + 1);
+
   while (before.length && before[before.length - 1]!.trim() === "") before.pop();
+
   return [...before, ...after].join("\n");
 }
 
+/** Source interval removed by a whole-block Cut, including its leading blank-line padding. */
+export function blockCutSourceRange(source: string, block: Block) {
+  const lines = source.split("\n");
+  let startLine = block.lineStart;
+
+  while (startLine > 0 && lines[startLine - 1]!.trim() === "") startLine--;
+  const lineStarts = [0];
+
+  for (let index = 0; index < source.length; index++) {
+    if (source.charCodeAt(index) === 10) lineStarts.push(index + 1);
+  }
+
+  return {
+    start: lineStarts[startLine] ?? source.length,
+    end: lineStarts[block.lineEnd + 1] ?? source.length,
+  };
+}
+
+/**
+ * Remove exactly the selected block-text range while retaining surrounding
+ * Markdown markers. A cross-block range also removes the source between its
+ * endpoint characters.
+ */
+export function cutTextRange(
+  working: string,
+  startBlock: Block,
+  start: number,
+  endBlock: Block,
+  end: number,
+): string {
+  const sourceStart = sourceOffsetAt(working, startBlock, start) ?? -1;
+  const sourceEnd = sourceOffsetAt(working, endBlock, end) ?? -1;
+
+  if (sourceStart < 0 || sourceEnd <= sourceStart) return working;
+
+  return working.slice(0, sourceStart) + working.slice(sourceEnd);
+}
+
 /** The line a restored block re-enters at: the next surviving block's start. */
 export function restoreLine(next: Block | undefined, workingLineCount: number): number {
   return next ? next.lineStart : workingLineCount;
@@ -34,10 +154,24 @@ export function restoreLine(next: Block | undefined, workingLineCount: number):
  */
 function signature(text: string): string {
   return parseBlocks(text)
-    .map((b) => b.kind + " " + b.text)
+    .map((block) => block.kind + " " + block.text)
     .join("\0");
 }
 
+/**
+ * Whether a base block is missing from the working source: the working copy
+ * holds fewer blocks with its kind and text than the base does. Only such a
+ * block can be restored without duplicating content.
+ */
+export function isBlockCut(base: string, working: string, block: Block): boolean {
+  const matches = (text: string) =>
+    parseBlocks(text).filter(
+      (candidate) => candidate.kind === block.kind && candidate.text === block.text,
+    ).length;
+
+  return matches(working) < matches(base);
+}
+
 /**
  * Re-insert a cut base block into the working source before `beforeLine`.
  * Returns undefined when the block structure round-trips to the base content
@@ -53,9 +187,11 @@ export function restoreBlock(
   const lines = working.split("\n");
   const before = lines.slice(0, beforeLine);
   const after = lines.slice(beforeLine);
-  const ins = sourceChunk(base, block).split("\n");
-  if (before.length && before[before.length - 1]!.trim() !== "") ins.unshift("");
-  if (after.length && after[0]!.trim() !== "") ins.push("");
-  const restored = [...before, ...ins, ...after].join("\n");
+  const insertedLines = sourceChunk(base, block).split("\n");
+
+  if (before.length && before[before.length - 1]!.trim() !== "") insertedLines.unshift("");
+  if (after.length && after[0]!.trim() !== "") insertedLines.push("");
+  const restored = [...before, ...insertedLines, ...after].join("\n");
+
   return signature(restored) === signature(base) ? undefined : restored;
 }