@company-semantics/contracts 51.0.0 → 51.2.0

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

@@ -0,0 +1,262 @@
+/**
+ * The two total functions the acceptance path runs before it writes.
+ *
+ * WHAT THIS SUITE EXISTS TO KILL. The plausible-looking wrong `plannedEdit`
+ * returns a well-formed edit for the no-op cases — `{ at, deleteLength: 0,
+ * insert: "" }` is a perfectly valid mutation, it applies without error, and it
+ * changes not one character. Its symptom is not a crash but a thread reported
+ * as `accepted` over a document that never received the proposal: the receipt
+ * says the edit landed, the body says it did not, and nothing anywhere throws.
+ * Every `toBeNull()` below is a case where that implementation returns an
+ * object, so a suite asserting only the three happy ops would sit green over it.
+ *
+ * The second wrong implementation is an `anchorStillReads` that answers `true`
+ * for a `document` anchor — "there is nothing to check, so nothing is wrong".
+ * That turns the whole-document thread, the one variant that names no
+ * characters at all, into a licence to rewrite whichever range the caller
+ * happened to pass.
+ *
+ * The third is an `anchorStillReads` that trusts the resolution instead of
+ * re-reading the text. It is invisible while the ladder is right and catastrophic
+ * exactly when it is not — which is the case this second assertion exists for.
+ */
+import { describe, expect, it } from "vitest";
+
+import { CommentAnchorSchema } from "../anchor.js";
+import { resolveAnchorFromText } from "../resolve.js";
+import { SuggestionSchema } from "../suggestion.js";
+import { anchorStillReads, plannedEdit } from "../verify.js";
+
+/** Parse through the published schemas, so no fixture reaches these functions
+ * having skipped a boundary a real payload cannot skip. */
+const parsedAnchor = (anchor: unknown) => CommentAnchorSchema.parse(anchor);
+
+const textAnchor = (fields: {
+  quote: string;
+  prefix: string;
+  suffix: string;
+}) => parsedAnchor({ type: "text", v: 1, ...fields });
+
+const insertionAnchor = (fields: {
+  leftContext: string;
+  rightContext: string;
+}) => parsedAnchor({ type: "text-insertion", v: 1, ...fields });
+
+const suggestion = (fields: { op: string; insertedText?: string }) =>
+  SuggestionSchema.parse({ v: 1, status: "open", ...fields });
+
+/** A resolution over `quote` in `text`, obtained from the SHIPPED resolver so
+ * the geometry under test is the geometry the ladder actually produces. */
+const resolveText = (text: string, quote: string) => {
+  const resolution = resolveAnchorFromText(
+    textAnchor({ quote, prefix: "", suffix: "" }),
+    text,
+  );
+  if (resolution.status !== "resolved") throw new Error("fixture unresolved");
+  return resolution;
+};
+
+describe("anchorStillReads — the second assertion, not the ladder's word", () => {
+  const text = "The board approved the plan on Friday.";
+
+  it("confirms a text anchor whose slice is still exactly the quote", () => {
+    const anchor = textAnchor({ quote: "the plan", prefix: "", suffix: "" });
+
+    expect(anchorStillReads(anchor, text, resolveText(text, "the plan"))).toBe(
+      true,
+    );
+  });
+
+  it("refuses a resolution whose slice no longer equals the quote", () => {
+    // The one-field mutation: the same well-formed resolution, shifted by one.
+    // An implementation that trusted the finder answers true here and rewrites
+    // a range off by a character from the one the author selected.
+    const anchor = textAnchor({ quote: "the plan", prefix: "", suffix: "" });
+    const resolution = resolveText(text, "the plan");
+
+    expect(
+      anchorStillReads(anchor, text, {
+        ...resolution,
+        start: resolution.start + 1,
+        end: resolution.end + 1,
+      }),
+    ).toBe(false);
+  });
+
+  it("refuses a slice that merely CONTAINS the quote", () => {
+    const anchor = textAnchor({ quote: "the plan", prefix: "", suffix: "" });
+    const resolution = resolveText(text, "the plan");
+
+    expect(
+      anchorStillReads(anchor, text, {
+        ...resolution,
+        end: resolution.end + 3,
+      }),
+    ).toBe(false);
+  });
+
+  it("confirms an insertion point whose two contexts still meet there", () => {
+    const anchor = insertionAnchor({
+      leftContext: "approved ",
+      rightContext: "the plan",
+    });
+    const resolution = resolveAnchorFromText(anchor, text);
+    expect(resolution.status).toBe("resolved");
+    if (resolution.status !== "resolved") return;
+
+    expect(anchorStillReads(anchor, text, resolution)).toBe(true);
+  });
+
+  it("refuses an insertion resolution that is not zero-width", () => {
+    // A zero-width anchor handed a RANGE means whoever produced it lost the
+    // distinction between a caret and a selection — and the edit that follows
+    // would delete text no suggestion claimed.
+    const anchor = insertionAnchor({
+      leftContext: "approved ",
+      rightContext: "the plan",
+    });
+    const resolution = resolveAnchorFromText(anchor, text);
+    if (resolution.status !== "resolved") throw new Error("fixture unresolved");
+
+    expect(
+      anchorStillReads(anchor, text, {
+        ...resolution,
+        end: resolution.end + 4,
+      }),
+    ).toBe(false);
+  });
+
+  it("refuses an insertion point whose contexts no longer surround it", () => {
+    const anchor = insertionAnchor({
+      leftContext: "approved ",
+      rightContext: "the plan",
+    });
+
+    expect(
+      anchorStillReads(anchor, text, {
+        status: "resolved",
+        start: 4,
+        end: 4,
+        rung: 2,
+      }),
+    ).toBe(false);
+  });
+
+  it("refuses a document anchor, which vouches for no range at all", () => {
+    // Unreachable through the shipped ladder — it answers { status: "document" }
+    // for this variant — so the resolution is built by hand, exactly as a
+    // consumer's own rung could hand one in. The refusal is what makes that
+    // harmless rather than a licence to rewrite an arbitrary range.
+    const anchor = parsedAnchor({ type: "document", v: 1 });
+
+    expect(
+      anchorStillReads(anchor, text, {
+        status: "resolved",
+        start: 0,
+        end: text.length,
+        rung: 2,
+      }),
+    ).toBe(false);
+    expect(resolveAnchorFromText(anchor, text)).toEqual({ status: "document" });
+  });
+});
+
+describe("plannedEdit — the mutation each op makes of the resolved range", () => {
+  const text = "The board approved the plan on Friday.";
+  const resolution = resolveText(text, "the plan");
+
+  it("inserts at END, where the redline draws the proposed text", () => {
+    // At `start` the inserted text would land BEFORE the quote, on the other
+    // side of the seam from the one the accepting user was shown.
+    expect(
+      plannedEdit(
+        suggestion({ op: "insert", insertedText: " urgently" }),
+        resolution,
+      ),
+    ).toEqual({ at: resolution.end, deleteLength: 0, insert: " urgently" });
+  });
+
+  it("deletes exactly the resolved span and inserts nothing", () => {
+    expect(plannedEdit(suggestion({ op: "delete" }), resolution)).toEqual({
+      at: resolution.start,
+      deleteLength: resolution.end - resolution.start,
+      insert: "",
+    });
+  });
+
+  it("replaces the resolved span with the payload's text", () => {
+    expect(
+      plannedEdit(
+        suggestion({ op: "replace", insertedText: "the revised plan" }),
+        resolution,
+      ),
+    ).toEqual({
+      at: resolution.start,
+      deleteLength: resolution.end - resolution.start,
+      insert: "the revised plan",
+    });
+  });
+
+  it("derives the span from the resolution, never from the quote's length", () => {
+    // A zero-width insertion resolution: `end - start` is 0, and the arithmetic
+    // must come from the position it was actually given.
+    const point = { status: "resolved", end: 9, start: 9, rung: 2 } as const;
+
+    expect(
+      plannedEdit(suggestion({ op: "insert", insertedText: "duly " }), point),
+    ).toEqual({ at: 9, deleteLength: 0, insert: "duly " });
+  });
+});
+
+describe("plannedEdit — a no-op is a refusal, not a cheap success", () => {
+  const text = "The board approved the plan on Friday.";
+  const span = resolveText(text, "the plan");
+  const collapsed = {
+    status: "resolved",
+    start: 19,
+    end: 19,
+    rung: 2,
+  } as const;
+
+  it("refuses an insert whose payload carries no text", () => {
+    // The READ schema keeps `insertedText` optional so a delete payload parses
+    // without it, which means an insert payload missing it arrives intact and
+    // reaches here. It proposes nothing; accepting it would mark the thread
+    // applied over a body that never changed.
+    expect(plannedEdit(suggestion({ op: "insert" }), span)).toBeNull();
+  });
+
+  it("refuses an insert whose payload carries an empty string", () => {
+    // One field of a well-formed payload, emptied. The schema refuses this at
+    // the boundary (min(1)); this function refuses it again, because the
+    // boundary is not the only door into an applier.
+    const emptied = {
+      ...suggestion({ op: "insert", insertedText: "x" }),
+      insertedText: "",
+    };
+
+    expect(plannedEdit(emptied, span)).toBeNull();
+  });
+
+  it("refuses a delete over a collapsed range", () => {
+    // The wrong implementation returns { at: 19, deleteLength: 0, insert: "" }
+    // here — a valid mutation that removes nothing.
+    expect(plannedEdit(suggestion({ op: "delete" }), collapsed)).toBeNull();
+  });
+
+  it("refuses a replace over a collapsed range", () => {
+    expect(
+      plannedEdit(
+        suggestion({ op: "replace", insertedText: "something" }),
+        collapsed,
+      ),
+    ).toBeNull();
+  });
+
+  it("refuses a replace whose payload carries no text", () => {
+    // Not a delete in disguise: the payload and the anchor disagree about what
+    // kind of edit this is, and settling that disagreement is not this
+    // function's job.
+    expect(plannedEdit(suggestion({ op: "replace" }), span)).toBeNull();
+  });
+});

package/src/comments/anchor-constants.ts

@@ -0,0 +1,61 @@
+/**
+ * The anchor size bounds, published once.
+ *
+ * CAPTURE AND ACCEPT ARE DIFFERENT NUMBERS AND MUST STAY THAT WAY. A
+ * constructor captures ANCHOR_CONTEXT_CHARS of surrounding text; the schema
+ * ACCEPTS up to ANCHOR_AFFIX_MAX_CHARS, because an anchor written by an older
+ * client (or a future one with a wider capture) must still parse. Collapsing
+ * them would silently reject valid stored anchors.
+ *
+ * These are the SAME numbers `CommentAnchorSchema` reads — that schema carries
+ * no inline size literal, so a bound can no longer be changed in one of the two
+ * places. They are published rather than kept file-local because the writing
+ * client and the resolving client are independent implementations with no
+ * server-side arbiter between them (ADR-CONTRACTS-116): a constructor that
+ * captures more than the schema accepts composes an anchor the route boundary
+ * then refuses, losing a comment after it was written.
+ *
+ * Measured in UTF-16 code units (plain JavaScript `String#length`), like every
+ * other offset on the comment path. No Unicode normalization happens anywhere
+ * here, so a two-unit emoji costs two.
+ */
+
+/**
+ * How much surrounding text a CONSTRUCTOR captures either side of a range —
+ * `prefix`/`suffix` on a text anchor, `leftContext`/`rightContext` on a
+ * text-insertion point.
+ *
+ * Deliberately SMALLER than {@link ANCHOR_AFFIX_MAX_CHARS}, and the gap is the
+ * point: this is a write-side choice that may change, while the accept bound is
+ * a promise made to every anchor already in storage.
+ */
+export const ANCHOR_CONTEXT_CHARS = 32;
+
+/**
+ * The largest affix `CommentAnchorSchema` will ACCEPT — `prefix`, `suffix`,
+ * `leftContext` and `rightContext` alike.
+ *
+ * Not redundant with {@link ANCHOR_CONTEXT_CHARS}: narrowing this to the
+ * capture width would refuse anchors written by a client that captured more,
+ * and those anchors are already durable jsonb the server never re-validates.
+ */
+export const ANCHOR_AFFIX_MAX_CHARS = 64;
+
+/**
+ * The largest `quote` a text anchor may carry.
+ *
+ * The quote is the durable fallback the passage is re-found by, so it is bounded
+ * generously — but bounded, because an anchor must never become a second copy of
+ * the document in a column nothing on the server reads.
+ */
+export const QUOTE_MAX_CHARS = 2000;
+
+/**
+ * Cap on ONE encoded `Y.RelativePosition` payload, in base64 chars — `relStart`,
+ * `relEnd` and `relPos` alike.
+ *
+ * The backend never decodes these; the bound and the base64 charset are the only
+ * things anyone checks, which is why both have to be checked at the boundary or
+ * a client can write a position no other client can decode.
+ */
+export const RELATIVE_POSITION_MAX_CHARS = 512;

package/src/comments/anchor.ts

@@ -19,7 +19,9 @@
  * Zod-canonical: the schema is the source of truth, the type is inferred.
  *
  * MIRRORED, NOT INVENTED. Every bound below is the backend route boundary's
- * (`src/api/http/routes/comments/comments.schemas.ts`), and the accept/reject
+ * (`src/api/http/routes/comments/comments.schemas.ts`) — they are named in
+ * `./anchor-constants` and read from there, so this file carries no size
+ * literal a constructor could drift away from. The accept/reject
  * corpus at `./__tests__/fixtures/comment-anchors.json` is copied byte-for-byte
  * from that suite's fixtures. Editing that copy HERE fails the anchor suite —
  * its digest is pinned beside it. A change made at the BOUNDARY is not caught
@@ -29,6 +31,12 @@
  */
 import { z } from "zod";
 
+import {
+  ANCHOR_AFFIX_MAX_CHARS,
+  QUOTE_MAX_CHARS,
+  RELATIVE_POSITION_MAX_CHARS,
+} from "./anchor-constants";
+
 /**
  * A base64 `Y.RelativePosition` payload, encoded by the client.
  *
@@ -40,7 +48,7 @@ import { z } from "zod";
 const RelativePositionSchema = z
   .string()
   .min(1)
-  .max(512)
+  .max(RELATIVE_POSITION_MAX_CHARS)
   .regex(/^[A-Za-z0-9+/]+={0,2}$/, "must be base64");
 
 /**
@@ -90,9 +98,9 @@ const TextAnchorSchema = z.strictObject({
   v: z.literal(1),
   relStart: RelativePositionSchema.optional(),
   relEnd: RelativePositionSchema.optional(),
-  quote: z.string().min(1).max(2000),
-  prefix: z.string().max(64),
-  suffix: z.string().max(64),
+  quote: z.string().min(1).max(QUOTE_MAX_CHARS),
+  prefix: z.string().max(ANCHOR_AFFIX_MAX_CHARS),
+  suffix: z.string().max(ANCHOR_AFFIX_MAX_CHARS),
 });
 
 /**
@@ -110,10 +118,11 @@ const TextAnchorSchema = z.strictObject({
  *
  * `leftContext`/`rightContext` are the durable fallback — the text
  * immediately before and after the point. They are required-but-may-be-empty
- * (max 64 UTF-16 code units each, like `prefix`/`suffix`): either may be
- * empty or short at a document edge, and an empty string means "there is
- * nothing on that side", which must stay distinguishable from "this client
- * forgot to send it". No Unicode normalization happens anywhere on this path.
+ * (max {@link ANCHOR_AFFIX_MAX_CHARS} UTF-16 code units each, like
+ * `prefix`/`suffix`): either may be empty or short at a document edge, and an
+ * empty string means "there is nothing on that side", which must stay
+ * distinguishable from "this client forgot to send it". No Unicode
+ * normalization happens anywhere on this path.
  *
  * RESOLUTION SEMANTICS (implemented client-side in the app; the backend is a
  * passthrough that interprets nothing):
@@ -144,8 +153,8 @@ const TextInsertionAnchorSchema = z.strictObject({
   type: z.literal("text-insertion"),
   v: z.literal(1),
   relPos: RelativePositionSchema.optional(),
-  leftContext: z.string().max(64),
-  rightContext: z.string().max(64),
+  leftContext: z.string().max(ANCHOR_AFFIX_MAX_CHARS),
+  rightContext: z.string().max(ANCHOR_AFFIX_MAX_CHARS),
 });
 
 /**

package/src/comments/create.ts

@@ -0,0 +1,128 @@
+/**
+ * Composing the anchor — the WRITE half of the contract `./resolve` reads
+ * (ADR-CONTRACTS-116, ADR-CONTRACTS-127).
+ *
+ * WHY BOTH DIRECTIONS ARE PUBLISHED, NOT JUST ONE. Publishing anchor → text
+ * while leaving text → anchor browser-only would be half an extraction: the
+ * side that COMPOSES an anchor is the side that decides how much context to
+ * capture and what counts as a quote, and a second description of that is the
+ * same silent-drift hazard the resolver was published to end. A constructor
+ * that captured more context than {@link CommentAnchorSchema} accepts composes
+ * an anchor the route boundary then refuses — a comment lost after it was
+ * written — and one that captured a DIFFERENT amount composes an anchor that
+ * parses and then resolves somewhere else.
+ *
+ * REFUSE RATHER THAN GUESS, in the same direction as the ladder. Range → anchor
+ * is a write capability and inherits the ladder's discipline exactly: every
+ * degenerate input returns `null` rather than a plausible anchor. Truncating an
+ * over-long quote is the sharpest case — the resulting anchor is well-formed,
+ * parses, resolves, and highlights a range the caller never selected. `null`
+ * means "compose no comment", which the caller can report; a truncated quote
+ * means "compose a comment about something else", which nobody can.
+ *
+ * VALIDATED BEFORE IT IS RETURNED. Both constructors run the object they built
+ * through the PUBLISHED schema rather than asserting the shape, so the only
+ * anchors this module can emit are anchors the route boundary will accept. The
+ * bounds come from `./anchor-constants` for the same reason: a literal here
+ * would be a fifth copy of a number whose whole point is having one.
+ *
+ * NO YJS HERE, DELIBERATELY — the same seam `./resolve` holds. `relStart`,
+ * `relEnd` and `relPos` are NOT produced: encoding a `Y.RelativePosition` needs
+ * `yjs`, which the vocabulary-guard forbids this package from importing, and it
+ * needs a live replica besides. A consumer that holds a `Y.Text` merges the
+ * encoded pair onto the anchor returned here; the anchor is useful without it,
+ * because the quote and the contexts are the durable fallback anyway.
+ *
+ * All arithmetic is in UTF-16 code units (plain JavaScript string coordinates),
+ * like every other offset on the comment path, and no Unicode normalization
+ * happens anywhere here.
+ *
+ * SPELLING DEVIATION FROM THE AUTHORITATIVE REFERENCE (PRD-00941, must_log).
+ * Nothing semantic. The reference writes
+ * `export function createTextAnchorFromRange(range: TextRange): CommentAnchor | null {`
+ * on one line, which is 82 columns against this repo's `printWidth: 80`, so
+ * `pnpm format:check` reflows the signature onto three lines. Same precedent as
+ * the notes in `./anchor.ts`: a different spelling of the same function, and
+ * nothing about what is accepted or refused changed.
+ */
+import { CommentAnchorSchema, type CommentAnchor } from "./anchor";
+import { QUOTE_MAX_CHARS } from "./anchor-constants";
+import { contextAfter, contextBefore } from "./resolve";
+
+/**
+ * A selected range, in the coordinate space of the text it was selected in.
+ *
+ * `text` travels WITH the offsets rather than being passed separately, because
+ * a start/end pair means nothing without the string it indexes — and a caller
+ * holding the pair from one revision and the string from another is the bug
+ * this shape makes hard to write.
+ */
+export interface TextRange {
+  readonly text: string;
+  readonly start: number;
+  readonly end: number;
+}
+
+/**
+ * range → anchor, headlessly. The mirror of `resolveAnchorFromText`, and a
+ * WRITE capability, so it refuses rather than guesses on every degenerate
+ * input.
+ *
+ * Returns `null` for: a non-integer offset, an out-of-order or EMPTY range
+ * (`end <= start` — the zero-width case has its own constructor below, and
+ * silently promoting one here would produce a text anchor whose quote is the
+ * empty string), a range reaching past the end of `text`, or a quote longer
+ * than {@link QUOTE_MAX_CHARS}.
+ *
+ * The relative-position pair is NOT produced here: it needs `yjs`, which this
+ * package may not import. A consumer holding a `Y.Text` merges it onto the
+ * result.
+ */
+export function createTextAnchorFromRange(
+  range: TextRange,
+): CommentAnchor | null {
+  const { text, start, end } = range;
+  if (!Number.isInteger(start) || !Number.isInteger(end)) return null;
+  if (start < 0 || end <= start || end > text.length) return null;
+
+  const quote = text.slice(start, end);
+  // Refusing beats truncating: a truncated quote anchors a range nobody chose.
+  if (quote.length === 0 || quote.length > QUOTE_MAX_CHARS) return null;
+
+  const parsed = CommentAnchorSchema.safeParse({
+    type: "text",
+    v: 1,
+    quote,
+    prefix: contextBefore(text, start),
+    suffix: contextAfter(text, end),
+  });
+  return parsed.success ? parsed.data : null;
+}
+
+/**
+ * The zero-width variant: a point BETWEEN two characters.
+ *
+ * Refuses two empty contexts on a non-empty document — that anchor identifies
+ * nothing, and `resolveInsertionBySeam` would (correctly) orphan it, so
+ * composing it at all would only defer the loss until after the suggestion was
+ * written. On an EMPTY document both contexts are empty and that is the one
+ * point there is, so it is allowed.
+ */
+export function createTextInsertionAnchorAt(
+  text: string,
+  point: number,
+): CommentAnchor | null {
+  if (!Number.isInteger(point) || point < 0 || point > text.length) return null;
+  const leftContext = contextBefore(text, point);
+  const rightContext = contextAfter(text, point);
+  // Two empty contexts identify nothing on a non-empty document.
+  if (leftContext === "" && rightContext === "" && text.length > 0) return null;
+
+  const parsed = CommentAnchorSchema.safeParse({
+    type: "text-insertion",
+    v: 1,
+    leftContext,
+    rightContext,
+  });
+  return parsed.success ? parsed.data : null;
+}

package/src/comments/index.ts

@@ -8,6 +8,13 @@
  * bodies, per ADR-CONT-029).
  */
 
+export {
+  ANCHOR_AFFIX_MAX_CHARS,
+  ANCHOR_CONTEXT_CHARS,
+  QUOTE_MAX_CHARS,
+  RELATIVE_POSITION_MAX_CHARS,
+} from "./anchor-constants";
+
 export {
   COMMENT_ANCHOR_TYPES,
   CommentAnchorTypeSchema,
@@ -16,6 +23,16 @@ export {
 
 export type { CommentAnchor, CommentAnchorType } from "./anchor";
 
+export {
+  contextAfter,
+  contextBefore,
+  contextsMatchAt,
+  findSoleOccurrence,
+  resolveAnchorFromText,
+} from "./resolve";
+
+export type { AnchorResolution, Occurrence } from "./resolve";
+
 export {
   COMMENT_SUBJECT_TYPES,
   COMMENT_THREAD_STATUSES,
@@ -55,3 +72,22 @@ export type {
   SuggestionOp,
   SuggestionStatus,
 } from "./suggestion";
+
+export { anchorStillReads, plannedEdit } from "./verify";
+
+export type { PlannedEdit } from "./verify";
+
+export {
+  createTextAnchorFromRange,
+  createTextInsertionAnchorAt,
+} from "./create";
+
+export type { TextRange } from "./create";
+
+export {
+  SUGGESTION_RECEIPTS_MAP,
+  SuggestionReceiptSchema,
+  readSuggestionReceipt,
+} from "./receipt";
+
+export type { SuggestionReceipt } from "./receipt";