@cueloop/schema 0.1.0-alpha.5 → 0.1.0-alpha.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/schema",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.7",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from "./types";
 export * from "./markdown";
+export * from "./working-copy";
 export * from "./diff";
 export * from "./anchor";
 export * from "./feedback";

package/src/types.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, test } from "bun:test";
+import { newAnnotationId, verdictAllows } from "./types";
+
+describe("verdictAllows", () => {
+  test("only approve maps to allow", () => {
+    expect(verdictAllows("approve")).toBe(true);
+    expect(verdictAllows("comment")).toBe(false);
+    expect(verdictAllows("request_changes")).toBe(false);
+  });
+});
+
+describe("newAnnotationId", () => {
+  test("unique by construction within a process, even on one millisecond", () => {
+    const ids = new Set(Array.from({ length: 10_000 }, () => newAnnotationId()));
+    expect(ids.size).toBe(10_000);
+    for (const id of ids) expect(id).toMatch(/^a_[0-9a-z]+_[0-9a-z]+$/);
+  });
+});

package/src/types.ts

@@ -23,6 +23,8 @@ export interface ArtifactMeta {
   planPath?: string;
   /** Pull request reference the diff came from, so the verdict can be posted back. */
   pr?: string;
+  /** herdr pane the submitting agent runs in - the review returns focus there. */
+  herdrPane?: string;
   title?: string;
 }
 
@@ -104,3 +106,13 @@ export interface ReviewSession {
 export function verdictAllows(kind: VerdictKind): boolean {
   return kind === "approve";
 }
+
+/**
+ * Annotation ids are minted client-side. The counter makes ids unique within
+ * a process by construction; the random suffix separates concurrent
+ * annotators in different processes on the same millisecond.
+ */
+let annotationSeq = 0;
+export function newAnnotationId(): string {
+  return `a_${Date.now().toString(36)}${(annotationSeq++).toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
+}

package/src/working-copy.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, test } from "bun:test";
+import { cutBlock, restoreBlock, restoreLine, sourceChunk } from "./working-copy";
+import { parseBlocks, type Block } from "./markdown";
+
+const BASE = `# Plan
+
+## Context
+
+A paragraph that
+spans two lines.
+
+- first item
+- second item
+
+\`\`\`ts
+const x = 1;
+const y = 2;
+\`\`\`
+`;
+
+function block(md: string, text: string): Block {
+  return parseBlocks(md).find((b) => b.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.");
+  });
+
+  test("code block chunk includes both fence lines", () => {
+    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", () => {
+    const cut = cutBlock(BASE, block(BASE, "spans two lines"));
+    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", () => {
+    const cut = cutBlock(BASE, block(BASE, "Plan"));
+    expect(cut).not.toContain("# Plan");
+    expect(cut.trimStart().startsWith("## Context")).toBe(true);
+  });
+
+  test("cut at the end of the document keeps the rest intact", () => {
+    const cut = cutBlock(BASE, block(BASE, "const x"));
+    expect(cut).not.toContain("const x");
+    expect(cut).toContain("- second item");
+  });
+});
+
+describe("restoreBlock", () => {
+  test("restoring the only cut returns undefined - back to pristine", () => {
+    const li = block(BASE, "second item");
+    const cut = cutBlock(BASE, li);
+    // 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));
+    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));
+    expect(restored).toContain("- second item");
+    expect(restored).toContain("first item reworded");
+  });
+
+  test("restore at the end of the document (no next block)", () => {
+    const code = block(BASE, "const x");
+    const cut = cutBlock(BASE, code);
+    const restored = restoreBlock(BASE, cut, code, restoreLine(undefined, cut.split("\n").length));
+    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));
+    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");
+    const line = restoreLine(next, cut.split("\n").length);
+    // extra blank lines elsewhere do not block pristine detection
+    expect(restoreBlock(BASE, cut.replace("## Context", "## Context\n"), li, line)).toBeUndefined();
+    // a real text change keeps the working copy alive
+    const changed = restoreBlock(BASE, cut.replace("first", "1st"), li, 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);
+    expect(restoreLine(undefined, 99)).toBe(99);
+  });
+});

package/src/working-copy.ts

@@ -0,0 +1,61 @@
+/**
+ * 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.
+ */
+
+import { parseBlocks, type Block } from "./markdown";
+
+/** 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");
+}
+
+/** Remove a work block's lines from the working source (Cut). */
+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");
+}
+
+/** 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;
+}
+
+/**
+ * Block-structure signature: kind + text of every block, insensitive to
+ * blank-line layout between blocks. NUL separates blocks so no block text
+ * can fake a boundary.
+ */
+function signature(text: string): string {
+  return parseBlocks(text)
+    .map((b) => b.kind + " " + b.text)
+    .join("\0");
+}
+
+/**
+ * Re-insert a cut base block into the working source before `beforeLine`.
+ * Returns undefined when the block structure round-trips to the base content
+ * (restore may differ in blank-line placement only) - the working copy is
+ * back to pristine and should be dropped.
+ */
+export function restoreBlock(
+  base: string,
+  working: string,
+  block: Block,
+  beforeLine: number,
+): string | undefined {
+  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");
+  return signature(restored) === signature(base) ? undefined : restored;
+}