@company-semantics/contracts 51.0.0 → 51.2.0

package/src/comments/__tests__/resolve.test.ts

@@ -0,0 +1,391 @@
+/**
+ * The published resolver, held to the corpus it must agree with.
+ *
+ * WHAT THIS SUITE EXISTS TO KILL. The plausible-looking wrong resolver returns
+ * the FIRST match. It passes every "the quote is still there" test, it never
+ * throws, and it is wrong precisely when the document is repetitive — which is
+ * when comments matter most. Its symptom is not a broken highlight but a
+ * confident one, on a paragraph the comment's author never saw. Every
+ * `orphaned` expectation below is a case where that resolver returns a
+ * well-formed range, so a suite that only asserted the happy path would sit
+ * green over it.
+ *
+ * The second wrong resolver collapses `document` into `orphaned` — a thread on
+ * the subject AS A WHOLE draws no highlight either way, so the bug is invisible
+ * until the rail files it behind "this text is gone".
+ *
+ * THE TEXT-INSERTION BLOCK IS DRIVEN BY THE PINNED CORPUS, not by hand-copied
+ * cases. `./fixtures/comment-anchors.json` carries a `document` and an
+ * `expectedResolution` on each text-insertion accept row: ground truth for
+ * exactly this module, recorded contracts-first in PRD-00933. `anchor-corpus`
+ * re-derives those outcomes with its own seam scan; this suite drives the
+ * SHIPPED resolver over the same rows, which is what turns that hand-rolled
+ * cross-check into a check of the implementation rather than of itself. The
+ * corpus is read, never edited — its digest is pinned beside it.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+import { ANCHOR_CONTEXT_CHARS } from "../anchor-constants.js";
+import { CommentAnchorSchema } from "../anchor.js";
+import {
+  contextAfter,
+  contextBefore,
+  contextsMatchAt,
+  findSoleOccurrence,
+  resolveAnchorFromText,
+} from "../resolve.js";
+
+/** One named case from the corpus. */
+interface AnchorCase {
+  name: string;
+  anchor: unknown;
+}
+
+/** The additive fields the text-insertion rows carry beside `anchor`. */
+interface InsertionFixture extends AnchorCase {
+  anchor: { type: "text-insertion" };
+  document: string;
+  expectedResolution:
+    { outcome: "resolved"; offset: number } | { outcome: "orphaned" };
+}
+
+const isInsertionFixture = (c: AnchorCase): c is InsertionFixture => {
+  const anchor = c.anchor as { type?: unknown } | null;
+  return anchor !== null && anchor?.type === "text-insertion";
+};
+
+/**
+ * Read from disk rather than imported: `src/tsconfig.json` sets no
+ * `resolveJsonModule`, so a JSON import would fail the build the moment
+ * anything the typechecker reaches loaded it.
+ */
+const CORPUS_PATH = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "fixtures",
+  "comment-anchors.json",
+);
+const corpus = JSON.parse(readFileSync(CORPUS_PATH, "utf8")) as {
+  accept: AnchorCase[];
+  reject: AnchorCase[];
+};
+
+/** Parse through the published schema, so no fixture reaches the resolver
+ * having skipped the boundary a real anchor cannot skip. */
+const parsed = (anchor: unknown) => CommentAnchorSchema.parse(anchor);
+
+const textAnchor = (fields: {
+  quote: string;
+  prefix: string;
+  suffix: string;
+}) => parsed({ type: "text", v: 1, ...fields });
+
+const insertionAnchor = (fields: {
+  leftContext: string;
+  rightContext: string;
+}) => parsed({ type: "text-insertion", v: 1, ...fields });
+
+describe("resolveAnchorFromText against the pinned insertion corpus", () => {
+  const insertionCases = corpus.accept.filter(isInsertionFixture);
+
+  it("has the four recorded insertion fixtures, so the loop cannot pass vacuously", () => {
+    // An empty array iterates cleanly and reports as a passing suite. Position
+    // 0, document end, ambiguous repeated seam, surrogate-pair flanked.
+    expect(insertionCases.length).toBeGreaterThanOrEqual(4);
+  });
+
+  for (const { name, anchor, document, expectedResolution } of insertionCases) {
+    it(`resolves ${name} exactly as the corpus records`, () => {
+      const resolution = resolveAnchorFromText(parsed(anchor), document);
+
+      if (expectedResolution.outcome === "resolved") {
+        // Whole-object, including the rung: a rung-2 answer reported as rung 1
+        // is the bug, and an insertion resolution is always zero-width.
+        expect(resolution).toEqual({
+          status: "resolved",
+          start: expectedResolution.offset,
+          end: expectedResolution.offset,
+          rung: 2,
+        });
+      } else {
+        expect(resolution).toEqual({ status: "orphaned" });
+      }
+    });
+  }
+
+  it("resolves the surrogate-flanked seam between the pairs, not inside one", () => {
+    // The corpus row carries a `relPos` encoded against another document. This
+    // module has no Y.Text in reach and correctly ignores it, so the seam has
+    // to carry the anchor on its own — and 11 is a UTF-16 code-unit offset
+    // BETWEEN two astral pairs, where a code-point walk would land on 9.
+    const document = "Q3 goals 🎯🚀 shipped early";
+    const anchor = parsed({
+      type: "text-insertion",
+      v: 1,
+      relPos: "AQLmzsvNAgA=",
+      leftContext: "goals 🎯",
+      rightContext: "🚀 shipped",
+    });
+
+    expect(resolveAnchorFromText(anchor, document)).toEqual({
+      status: "resolved",
+      start: 11,
+      end: 11,
+      rung: 2,
+    });
+    expect(document.slice(0, 11)).toBe("Q3 goals 🎯");
+  });
+});
+
+describe("resolveAnchorFromText — ambiguity resolves orphaned, never the first match", () => {
+  it("orphans an anchor whose quote occurs ambiguously", () => {
+    // No context to disambiguate with, and the quote repeats. A first-match
+    // implementation returns index 3 here and is silently wrong half the time.
+    const anchor = textAnchor({ quote: "the plan", prefix: "", suffix: "" });
+    const text = "Is the plan agreed? We ship the plan on Friday.";
+
+    expect(resolveAnchorFromText(anchor, text)).toEqual({ status: "orphaned" });
+  });
+
+  it("orphans when even the context-qualified match is ambiguous", () => {
+    const anchor = textAnchor({
+      quote: "beta",
+      prefix: "alpha ",
+      suffix: " gamma",
+    });
+    const text = "alpha beta gamma / alpha beta gamma";
+
+    // Two context matches mean the CONTEXT failed to identify a candidate.
+    // Binding to the first occurrence — or quietly retrying the bare quote,
+    // which is equally ambiguous — is the shortcut this ladder forbids.
+    expect(resolveAnchorFromText(anchor, text)).toEqual({ status: "orphaned" });
+  });
+
+  it("resolves via context when the bare quote alone would be ambiguous", () => {
+    const anchor = textAnchor({ quote: "beta", prefix: "alpha ", suffix: "" });
+    const text = "zeta beta gamma / alpha beta gamma";
+
+    // The SECOND "beta" — the one the context identifies. This is the positive
+    // twin of the rule above: context DISAMBIGUATES, it does not merely veto.
+    expect(resolveAnchorFromText(anchor, text)).toEqual({
+      status: "resolved",
+      start: text.lastIndexOf("beta"),
+      end: text.lastIndexOf("beta") + "beta".length,
+      rung: 2,
+    });
+  });
+
+  it("falls back to the bare quote when the surrounding sentence was rewritten", () => {
+    const anchor = textAnchor({
+      quote: "materially understated",
+      prefix: "Q3 revenue was ",
+      suffix: " in the board pack.",
+    });
+    const text = "The figure was materially understated, we now believe.";
+
+    // Context ABSENT is not context AMBIGUOUS: the sentence moved, the quote
+    // survived, and a unique bare quote is still evidence enough.
+    expect(resolveAnchorFromText(anchor, text)).toEqual({
+      status: "resolved",
+      start: text.indexOf("materially understated"),
+      end:
+        text.indexOf("materially understated") +
+        "materially understated".length,
+      rung: 2,
+    });
+  });
+
+  it("counts overlapping occurrences as ambiguous", () => {
+    // "aa" occurs at 0 AND at 1. Resuming the second search at
+    // `first + needle.length` would miss the overlap and call this unique.
+    const anchor = textAnchor({ quote: "aa", prefix: "", suffix: "" });
+
+    expect(resolveAnchorFromText(anchor, "aaa")).toEqual({
+      status: "orphaned",
+    });
+  });
+
+  it("orphans when the quote is gone entirely", () => {
+    const anchor = textAnchor({
+      quote: "the original wording",
+      prefix: "before ",
+      suffix: " after",
+    });
+
+    expect(
+      resolveAnchorFromText(anchor, "Nothing of the sort remains."),
+    ).toEqual({ status: "orphaned" });
+  });
+});
+
+describe("resolveAnchorFromText — the insertion seam refuses ambiguity", () => {
+  it("orphans a repeated seam rather than taking the first row", () => {
+    const document = "item done, item done, item done";
+    const anchor = insertionAnchor({
+      leftContext: "item ",
+      rightContext: "done",
+    });
+
+    // A first-match resolver returns a perfectly well-formed caret at 5 here,
+    // two rows away from where the suggestion was written.
+    expect(document.indexOf("item done")).toBe(0);
+    expect(resolveAnchorFromText(anchor, document)).toEqual({
+      status: "orphaned",
+    });
+  });
+
+  it("orphans when the seam is gone entirely", () => {
+    const anchor = insertionAnchor({
+      leftContext: "approved ",
+      rightContext: "the plan.",
+    });
+
+    expect(
+      resolveAnchorFromText(anchor, "Nothing here resembles that sentence."),
+    ).toEqual({ status: "orphaned" });
+  });
+
+  it("resolves the empty seam on an empty document and orphans it once there is text", () => {
+    const anchor = insertionAnchor({ leftContext: "", rightContext: "" });
+
+    // On the empty document the anchor is complete and 0 is the only answer —
+    // the one case an empty seam is authorable at all.
+    expect(resolveAnchorFromText(anchor, "")).toEqual({
+      status: "resolved",
+      start: 0,
+      end: 0,
+      rung: 2,
+    });
+    // Once there is text it says nothing about WHERE among it the caret goes.
+    expect(
+      resolveAnchorFromText(anchor, "The board approved the plan."),
+    ).toEqual({ status: "orphaned" });
+  });
+
+  it("always resolves zero-width", () => {
+    const document = "We agreed to ship the quarterly goals.";
+    const anchor = insertionAnchor({
+      leftContext: "ship ",
+      rightContext: "the quarterly",
+    });
+
+    const resolution = resolveAnchorFromText(anchor, document);
+    expect(resolution.status).toBe("resolved");
+    if (resolution.status !== "resolved") return;
+    // A zero-width point that resolved to a RANGE would paint a highlight over
+    // text the suggestion never claimed.
+    expect(resolution.start).toBe(resolution.end);
+  });
+});
+
+describe("resolveAnchorFromText — the document anchor", () => {
+  it("reports a document anchor as document, never orphaned", () => {
+    const anchor = parsed({ type: "document", v: 1 });
+
+    // A thread on the subject AS A WHOLE draws no highlight, but it is
+    // correctly anchored — calling it orphaned would put it behind the rail's
+    // "this text is gone" affordance.
+    expect(resolveAnchorFromText(anchor, "any text at all")).toEqual({
+      status: "document",
+    });
+    expect(resolveAnchorFromText(anchor, "")).toEqual({ status: "document" });
+  });
+});
+
+describe("findSoleOccurrence", () => {
+  it("reports a lone occurrence with its index", () => {
+    expect(findSoleOccurrence("the plan is agreed", "plan")).toEqual({
+      kind: "unique",
+      index: 4,
+    });
+  });
+
+  it("reports an absent needle as absent, distinctly from ambiguous", () => {
+    // The resolver treats these two differently at the context level: absent
+    // falls through to the bare quote, ambiguous orphans immediately.
+    expect(findSoleOccurrence("the plan", "budget")).toEqual({
+      kind: "absent",
+    });
+  });
+
+  it("treats an empty needle as ambiguous, never as a match at 0", () => {
+    // `indexOf("")` is 0 on every string, so an implementation without this
+    // guard reports a confident unique match at the start of the document.
+    expect(findSoleOccurrence("the plan", "")).toEqual({ kind: "ambiguous" });
+    expect(findSoleOccurrence("", "")).toEqual({ kind: "ambiguous" });
+  });
+});
+
+describe("contextsMatchAt", () => {
+  const text = "The board approved the plan.";
+
+  it("confirms the contexts that actually surround the point", () => {
+    expect(contextsMatchAt(text, 19, "approved ", "the plan.")).toBe(true);
+  });
+
+  it("refuses a context that cannot FIT before the point", () => {
+    // THE LOAD-BEARING GUARD. `slice` reads a negative start from the END of
+    // the string, so without it "approved " would be compared against a
+    // substring taken from the far end and could answer true.
+    expect(contextsMatchAt(text, 2, "approved ", "e board")).toBe(false);
+  });
+
+  it("refuses a context that cannot FIT after the point", () => {
+    // The mirror case: `slice` CLAMPS a long end rather than failing.
+    expect(contextsMatchAt(text, text.length - 2, "n.", "the plan.")).toBe(
+      false,
+    );
+  });
+
+  it("refuses an out-of-bounds point outright", () => {
+    expect(contextsMatchAt(text, -1, "", "")).toBe(false);
+    expect(contextsMatchAt(text, text.length + 1, "", "")).toBe(false);
+  });
+
+  it("answers true at every in-bounds point for two empty contexts", () => {
+    // Not a bug — a fact about the question. It is why a consumer's
+    // relative-position rung must refuse an anchor with no contexts BEFORE it
+    // decodes anything, rather than treating this check as evidence.
+    expect(contextsMatchAt(text, 0, "", "")).toBe(true);
+    expect(contextsMatchAt(text, 7, "", "")).toBe(true);
+  });
+});
+
+describe("contextBefore / contextAfter", () => {
+  it("captures at most ANCHOR_CONTEXT_CHARS, the capture width", () => {
+    const text = "x".repeat(200);
+
+    // The CAPTURE width, deliberately narrower than what the schema ACCEPTS —
+    // capturing to the accept bound would leave a constructor no headroom.
+    expect(contextBefore(text, 150)).toHaveLength(ANCHOR_CONTEXT_CHARS);
+    expect(contextAfter(text, 50)).toHaveLength(ANCHOR_CONTEXT_CHARS);
+  });
+
+  it("clamps at the document edges instead of running off them", () => {
+    expect(contextBefore("short", 3)).toBe("sho");
+    expect(contextAfter("short", 3)).toBe("rt");
+    expect(contextBefore("short", 0)).toBe("");
+    expect(contextAfter("short", 5)).toBe("");
+  });
+
+  it("never opens on half a character", () => {
+    // The fixed-width slice would start exactly between the pair's two code
+    // units; the lone low surrogate that results is ill-formed on the wire.
+    const text = "🎯" + "a".repeat(ANCHOR_CONTEXT_CHARS - 1);
+    const before = contextBefore(text, text.length);
+
+    expect(before).toBe("a".repeat(ANCHOR_CONTEXT_CHARS - 1));
+    expect(before.charCodeAt(0)).toBeLessThan(0xd800);
+  });
+
+  it("never closes on half a character", () => {
+    const text = "a".repeat(ANCHOR_CONTEXT_CHARS - 1) + "🎯tail";
+    const after = contextAfter(text, 0);
+
+    // Trimming costs one code unit of context and changes nothing about
+    // matching — the document holds the same code units either way.
+    expect(after).toBe("a".repeat(ANCHOR_CONTEXT_CHARS - 1));
+  });
+});

package/src/comments/__tests__/schemas.test.ts

@@ -17,6 +17,7 @@ import {
   CommentThreadListResponseSchema,
   CommentThreadSchema,
   CommentThreadStatusSchema,
+  CommentThreadSummarySchema,
   MentionableResponseSchema,
 } from "../schemas.js";
 
@@ -68,6 +69,7 @@ function makeThread(over: Record<string, unknown> = {}) {
     createdByUserId: USER_ID,
     resolvedByUserId: null,
     resolvedAt: null,
+    lastAnchoredOffset: null,
     createdAt: "2026-08-01T12:00:00.000Z",
     updatedAt: "2026-08-01T12:00:00.000Z",
     comments: [makeComment()],
@@ -224,7 +226,13 @@ describe("CommentThreadSchema", () => {
     ).toBe(false);
   });
 
-  it("keeps tombstones in the comment list rather than filtering them", () => {
+  it("parses a redacted comment inside a thread — the schema still admits one", () => {
+    // This test once asserted that a reader SEES tombstones in a conversation.
+    // ADR-BE-545 ended that: the list read omits deleted comments outright. What
+    // survives is the SHAPE — the redacted projection is still a legal
+    // `CommentProjection`, because it is what the DELETE acknowledgement returns
+    // to the caller who performed the delete. So this pins the parse, not a read
+    // behaviour the server no longer has.
     const thread = CommentThreadSchema.parse(
       makeThread({
         comments: [
@@ -243,6 +251,26 @@ describe("CommentThreadSchema", () => {
 });
 
 describe("CommentThreadSummarySchema kind and suggestion", () => {
+  it("carries a lastAnchoredOffset, and null is the ordinary answer", () => {
+    // An ORDERING HINT and nothing else (ADR-BE-548): where an orphaned thread's
+    // passage used to be, so a client can keep the card in the reader's list
+    // rather than piling every orphan at the top. It must never yield a range.
+    expect(
+      CommentThreadSummarySchema.parse(makeThread()).lastAnchoredOffset,
+      "a thread nobody has watched lose its passage carries null",
+    ).toBeNull();
+    expect(
+      CommentThreadSummarySchema.parse(makeThread({ lastAnchoredOffset: 412 }))
+        .lastAnchoredOffset,
+    ).toBe(412);
+    expect(
+      CommentThreadSummarySchema.safeParse(
+        makeThread({ lastAnchoredOffset: 3.5 }),
+      ).success,
+      "a fractional offset is not a source position",
+    ).toBe(false);
+  });
+
   it("a zero-comment suggestion thread parses through both response shapes", () => {
     // The full suggestion projection: kind `suggestion`, a v1 payload, a
     // zero-width text-insertion anchor, and NO comments. The backend creates a