@company-semantics/contracts 51.0.0 → 51.2.0

package/src/comments/__tests__/anchor-constants.test.ts

@@ -0,0 +1,161 @@
+/**
+ * The published anchor size bounds, and the proof that `CommentAnchorSchema`
+ * actually reads them.
+ *
+ * WHY THIS SUITE EXISTS. The bounds used to be inline literals in `../anchor`,
+ * duplicated by hand in the app's constructor. Naming them removes the
+ * duplication only if two things stay true, and neither is mechanically
+ * enforced: the VALUES must not have moved during the extraction, and the
+ * schema must be reading the named constant rather than a leftover literal
+ * that happens to agree with it today.
+ *
+ * The mirrored corpus in `./fixtures/comment-anchors.json` proves the 64
+ * affix bound from both sides (its `oversized-prefix`/`oversized-suffix` rows
+ * are 65 chars), but NOTHING anywhere exercised the quote bound at 2000 or a
+ * relative position at 512 — a typo in either would have shipped green. Each
+ * boundary case below is that missing tripwire: accept at exactly the bound,
+ * refuse one code unit past it, phrased in terms of the constant so the test
+ * moves with the value it is protecting rather than re-pinning it a third time.
+ *
+ * The bare value assertions are the other half: they are what catches a bound
+ * being CHANGED (as opposed to being read from the wrong place), which no
+ * schema-relative assertion can see.
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+  ANCHOR_AFFIX_MAX_CHARS,
+  ANCHOR_CONTEXT_CHARS,
+  QUOTE_MAX_CHARS,
+  RELATIVE_POSITION_MAX_CHARS,
+} from "../anchor-constants.js";
+import { CommentAnchorSchema } from "../anchor.js";
+
+/** A well-formed text anchor; override one field per boundary test. */
+const makeTextAnchor = (over: Record<string, unknown> = {}) => ({
+  type: "text",
+  v: 1,
+  quote: "the quarterly goals",
+  prefix: "we restated ",
+  suffix: " last week",
+  ...over,
+});
+
+/** A well-formed insertion anchor; override one field per boundary test. */
+const makeInsertionAnchor = (over: Record<string, unknown> = {}) => ({
+  type: "text-insertion",
+  v: 1,
+  leftContext: "the quarterly ",
+  rightContext: " goals",
+  ...over,
+});
+
+describe("the published anchor size bounds", () => {
+  it("holds the values the wire contract was published with", () => {
+    // These are durable promises, not knobs: anchors already in storage were
+    // written against them, and the backend route boundary declares the same
+    // numbers independently. Changing one here is a wire change.
+    expect(ANCHOR_CONTEXT_CHARS).toBe(32);
+    expect(ANCHOR_AFFIX_MAX_CHARS).toBe(64);
+    expect(QUOTE_MAX_CHARS).toBe(2000);
+    expect(RELATIVE_POSITION_MAX_CHARS).toBe(512);
+  });
+
+  it("keeps capture strictly narrower than accept", () => {
+    // The two "context" numbers are NOT a duplication waiting to be collapsed.
+    // A constructor captures ANCHOR_CONTEXT_CHARS; the schema accepts up to
+    // ANCHOR_AFFIX_MAX_CHARS, so an anchor written by a client with a wider
+    // capture still parses. Narrowing accept to capture would refuse durable
+    // jsonb the server never re-validates.
+    expect(ANCHOR_CONTEXT_CHARS).toBeLessThan(ANCHOR_AFFIX_MAX_CHARS);
+  });
+});
+
+describe("CommentAnchorSchema reads the published bounds", () => {
+  it("accepts a quote of exactly QUOTE_MAX_CHARS and refuses one more", () => {
+    // The quote is the durable fallback the passage is re-found by, so it is
+    // bounded generously — but bounded, or an anchor becomes a second copy of
+    // the document in a column nothing on the server reads.
+    const atBound = "q".repeat(QUOTE_MAX_CHARS);
+    expect(
+      CommentAnchorSchema.safeParse(makeTextAnchor({ quote: atBound })).success,
+    ).toBe(true);
+    expect(
+      CommentAnchorSchema.safeParse(makeTextAnchor({ quote: `${atBound}q` }))
+        .success,
+    ).toBe(false);
+  });
+
+  it("refuses an empty quote", () => {
+    // `quote` is required AND non-empty: an anchor with no quote is unplaceable
+    // the first time the document is edited.
+    expect(
+      CommentAnchorSchema.safeParse(makeTextAnchor({ quote: "" })).success,
+    ).toBe(false);
+  });
+
+  it("bounds prefix and suffix at ANCHOR_AFFIX_MAX_CHARS", () => {
+    const atBound = "x".repeat(ANCHOR_AFFIX_MAX_CHARS);
+    expect(
+      CommentAnchorSchema.safeParse(
+        makeTextAnchor({ prefix: atBound, suffix: atBound }),
+      ).success,
+    ).toBe(true);
+    expect(
+      CommentAnchorSchema.safeParse(makeTextAnchor({ prefix: `${atBound}x` }))
+        .success,
+    ).toBe(false);
+    expect(
+      CommentAnchorSchema.safeParse(makeTextAnchor({ suffix: `${atBound}x` }))
+        .success,
+    ).toBe(false);
+  });
+
+  it("bounds leftContext and rightContext at the SAME affix bound", () => {
+    // One constant, four fields: the insertion seam is context in the same
+    // sense prefix/suffix are, and a reader must not have to check whether the
+    // two variants drifted apart.
+    const atBound = "x".repeat(ANCHOR_AFFIX_MAX_CHARS);
+    expect(
+      CommentAnchorSchema.safeParse(
+        makeInsertionAnchor({ leftContext: atBound, rightContext: atBound }),
+      ).success,
+    ).toBe(true);
+    expect(
+      CommentAnchorSchema.safeParse(
+        makeInsertionAnchor({ rightContext: `${atBound}x` }),
+      ).success,
+    ).toBe(false);
+  });
+
+  it("bounds every relative position at RELATIVE_POSITION_MAX_CHARS", () => {
+    // relStart/relEnd/relPos are opaque base64 the backend never decodes, so
+    // the length and the charset are the ONLY things anyone checks. Applied to
+    // all three fields because a position that is bounded on one path and
+    // unbounded on another is not bounded.
+    const atBound = "A".repeat(RELATIVE_POSITION_MAX_CHARS);
+    const overBound = `${atBound}A`;
+
+    expect(
+      CommentAnchorSchema.safeParse(
+        makeTextAnchor({ relStart: atBound, relEnd: atBound }),
+      ).success,
+    ).toBe(true);
+    expect(
+      CommentAnchorSchema.safeParse(makeTextAnchor({ relStart: overBound }))
+        .success,
+    ).toBe(false);
+    expect(
+      CommentAnchorSchema.safeParse(makeTextAnchor({ relEnd: overBound }))
+        .success,
+    ).toBe(false);
+    expect(
+      CommentAnchorSchema.safeParse(makeInsertionAnchor({ relPos: atBound }))
+        .success,
+    ).toBe(true);
+    expect(
+      CommentAnchorSchema.safeParse(makeInsertionAnchor({ relPos: overBound }))
+        .success,
+    ).toBe(false);
+  });
+});

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

@@ -0,0 +1,300 @@
+/**
+ * The construction half — range → anchor, and back again.
+ *
+ * WHAT THIS SUITE EXISTS TO KILL. The plausible-looking wrong constructor
+ * TRUNCATES an over-long quote instead of refusing it. Its output is a
+ * well-formed anchor: it parses, it passes the route boundary, and it resolves
+ * — onto a range the caller never selected. Nothing throws, and the comment
+ * reads as a considered remark about the first `QUOTE_MAX_CHARS` characters of
+ * a passage its author selected all of. `null` means "compose no comment",
+ * which a caller can report; a truncated quote means "compose a comment about
+ * something else", which nobody can. Every `toBeNull()` below is a case where
+ * that implementation returns an object and looks entirely healthy.
+ *
+ * The second wrong implementation returns an unvalidated object literal that
+ * the route boundary later rejects — a comment lost AFTER it was composed,
+ * which is the worst moment to lose one. `every constructed anchor parses
+ * through the published schema` is the standing assertion against it.
+ *
+ * The third silently promotes an empty range to a text anchor with an empty
+ * quote, rather than refusing it. That anchor is unplaceable the first time the
+ * document is edited, and the zero-width case has its own constructor.
+ *
+ * The round-trip cases run the construction half against the SHIPPED resolver
+ * rather than against a restatement of it. That is the property that actually
+ * matters: the two halves have to agree about the same geometry, and a suite
+ * asserting only the anchor's FIELDS would sit green over a capture width that
+ * disagreed with what the resolver searches for.
+ */
+import { describe, expect, it } from "vitest";
+
+import { CommentAnchorSchema, type CommentAnchor } from "../anchor.js";
+import { ANCHOR_CONTEXT_CHARS, QUOTE_MAX_CHARS } from "../anchor-constants.js";
+import {
+  createTextAnchorFromRange,
+  createTextInsertionAnchorAt,
+  type TextRange,
+} from "../create.js";
+import { resolveAnchorFromText } from "../resolve.js";
+
+/** A range named by its quote, so no offset in this file is hand-counted. */
+const rangeOf = (text: string, quote: string): TextRange => {
+  const start = text.indexOf(quote);
+  if (start === -1) throw new Error("fixture quote absent from fixture text");
+  return { text, start, end: start + quote.length };
+};
+
+/** Construct, refusing to continue on a refusal — a `null` here is a broken
+ * fixture, not the behaviour under test, and `expect(x).not.toBeNull()` would
+ * leave the rest of the case running against `null`. */
+const constructed = (range: TextRange): CommentAnchor => {
+  const anchor = createTextAnchorFromRange(range);
+  if (anchor === null) throw new Error("fixture range refused");
+  return anchor;
+};
+
+const insertionAt = (text: string, point: number): CommentAnchor => {
+  const anchor = createTextInsertionAnchorAt(text, point);
+  if (anchor === null) throw new Error("fixture point refused");
+  return anchor;
+};
+
+const doc = "The board approved the revised plan on Friday, then adjourned.";
+
+describe("createTextAnchorFromRange — range to anchor", () => {
+  it("captures the quote and both contexts from the surrounding text", () => {
+    const anchor = constructed(rangeOf(doc, "revised plan"));
+
+    expect(anchor).toEqual({
+      type: "text",
+      v: 1,
+      quote: "revised plan",
+      prefix: "The board approved the ",
+      suffix: " on Friday, then adjourned.",
+    });
+  });
+
+  it("produces no relative positions — that seam stays in consumers", () => {
+    const anchor = constructed(rangeOf(doc, "revised plan"));
+
+    // `yjs` cannot be imported here (vocabulary-guard), and a consumer holding
+    // a Y.Text merges the encoded pair on. Absent must mean "this side could
+    // not produce one", never "this side produced an empty one".
+    expect(anchor).not.toHaveProperty("relStart");
+    expect(anchor).not.toHaveProperty("relEnd");
+  });
+
+  it("captures at most ANCHOR_CONTEXT_CHARS of context on each side", () => {
+    const long = "x".repeat(200) + "MIDDLE" + "y".repeat(200);
+    const anchor = constructed(rangeOf(long, "MIDDLE"));
+
+    expect(anchor).toMatchObject({
+      prefix: "x".repeat(ANCHOR_CONTEXT_CHARS),
+      suffix: "y".repeat(ANCHOR_CONTEXT_CHARS),
+    });
+  });
+
+  it("refuses an EMPTY range — the zero-width case has its own constructor", () => {
+    const start = doc.indexOf("revised");
+
+    expect(
+      createTextAnchorFromRange({ text: doc, start, end: start }),
+    ).toBeNull();
+  });
+
+  it("refuses an out-of-order range", () => {
+    expect(
+      createTextAnchorFromRange({ text: doc, start: 12, end: 4 }),
+    ).toBeNull();
+  });
+
+  it("refuses a range reaching past the end of the text", () => {
+    expect(
+      createTextAnchorFromRange({ text: doc, start: 4, end: doc.length + 1 }),
+    ).toBeNull();
+  });
+
+  it("refuses a negative start", () => {
+    expect(
+      createTextAnchorFromRange({ text: doc, start: -1, end: 4 }),
+    ).toBeNull();
+  });
+
+  it("refuses non-integer offsets", () => {
+    expect(
+      createTextAnchorFromRange({ text: doc, start: 1.5, end: 6 }),
+    ).toBeNull();
+    expect(
+      createTextAnchorFromRange({ text: doc, start: 1, end: 6.5 }),
+    ).toBeNull();
+    expect(
+      createTextAnchorFromRange({ text: doc, start: 1, end: NaN }),
+    ).toBeNull();
+  });
+
+  it("accepts a quote of exactly QUOTE_MAX_CHARS", () => {
+    const text = "z".repeat(QUOTE_MAX_CHARS);
+
+    expect(
+      createTextAnchorFromRange({ text, start: 0, end: text.length }),
+    ).toMatchObject({ type: "text", quote: text });
+  });
+
+  it("refuses an over-long quote rather than truncating it", () => {
+    const text = "z".repeat(QUOTE_MAX_CHARS + 1);
+
+    // Truncating here yields an anchor that parses, resolves, and highlights a
+    // range the caller never selected. Refusal is the only legible outcome.
+    expect(
+      createTextAnchorFromRange({ text, start: 0, end: text.length }),
+    ).toBeNull();
+  });
+});
+
+describe("createTextInsertionAnchorAt — the zero-width point", () => {
+  const text = "Hello world";
+
+  it("captures a bilateral context at a point between two characters", () => {
+    expect(insertionAt(text, 5)).toEqual({
+      type: "text-insertion",
+      v: 1,
+      leftContext: "Hello",
+      rightContext: " world",
+    });
+  });
+
+  it("allows position 0 — the left context is legitimately empty there", () => {
+    expect(insertionAt(text, 0)).toEqual({
+      type: "text-insertion",
+      v: 1,
+      leftContext: "",
+      rightContext: "Hello world",
+    });
+  });
+
+  it("allows the document end — the right context is legitimately empty", () => {
+    expect(insertionAt(text, text.length)).toEqual({
+      type: "text-insertion",
+      v: 1,
+      leftContext: "Hello world",
+      rightContext: "",
+    });
+  });
+
+  it("allows position 0 of an EMPTY document — the one point there is", () => {
+    expect(insertionAt("", 0)).toEqual({
+      type: "text-insertion",
+      v: 1,
+      leftContext: "",
+      rightContext: "",
+    });
+  });
+
+  it("refuses a point outside the text", () => {
+    expect(createTextInsertionAnchorAt(text, -1)).toBeNull();
+    expect(createTextInsertionAnchorAt(text, text.length + 1)).toBeNull();
+  });
+
+  it("refuses a non-integer point", () => {
+    expect(createTextInsertionAnchorAt(text, 2.5)).toBeNull();
+    expect(createTextInsertionAnchorAt(text, NaN)).toBeNull();
+  });
+
+  it("produces no relative position — that seam stays in consumers", () => {
+    expect(insertionAt(text, 5)).not.toHaveProperty("relPos");
+  });
+});
+
+describe("the two halves agree about the same geometry", () => {
+  it("constructed anchors round-trip through resolveAnchorFromText", () => {
+    for (const quote of ["The board", "revised plan", "adjourned."]) {
+      const range = rangeOf(doc, quote);
+
+      expect(resolveAnchorFromText(constructed(range), doc)).toEqual({
+        status: "resolved",
+        start: range.start,
+        end: range.end,
+        rung: 2,
+      });
+    }
+  });
+
+  it("round-trips a range flanked by surrogate pairs on both sides", () => {
+    // Both context windows land INSIDE an astral character: the prefix window
+    // opens on the low half of 🎯 and the suffix window closes on the high half
+    // of 🚀. A constructor that sliced blindly would emit a lone surrogate,
+    // which is ill-formed once the anchor is encoded for the wire.
+    const text =
+      "🎯" +
+      "a".repeat(ANCHOR_CONTEXT_CHARS - 1) +
+      "SELECTED" +
+      "b".repeat(ANCHOR_CONTEXT_CHARS - 1) +
+      "🚀tail";
+    const range = rangeOf(text, "SELECTED");
+    const anchor = constructed(range);
+
+    expect(anchor).toMatchObject({
+      prefix: "a".repeat(ANCHOR_CONTEXT_CHARS - 1),
+      suffix: "b".repeat(ANCHOR_CONTEXT_CHARS - 1),
+    });
+    expect(resolveAnchorFromText(anchor, text)).toEqual({
+      status: "resolved",
+      start: range.start,
+      end: range.end,
+      rung: 2,
+    });
+  });
+
+  it("round-trips an insertion point through the seam rung", () => {
+    const text = "Ship it on Friday.";
+
+    for (const point of [0, 4, text.length]) {
+      expect(resolveAnchorFromText(insertionAt(text, point), text)).toEqual({
+        status: "resolved",
+        start: point,
+        end: point,
+        rung: 2,
+      });
+    }
+  });
+
+  it("round-trips the sole point of an empty document", () => {
+    expect(resolveAnchorFromText(insertionAt("", 0), "")).toEqual({
+      status: "resolved",
+      start: 0,
+      end: 0,
+      rung: 2,
+    });
+  });
+
+  it("captured context disambiguates a quote that repeats", () => {
+    // The bare quote is ambiguous here; the constructor's prefix is what makes
+    // the SECOND occurrence identifiable. This is the capture width earning its
+    // keep, not an incidental pass.
+    const rows = "item done\nitem done";
+    const second = rows.lastIndexOf("item done");
+
+    expect(
+      resolveAnchorFromText(
+        constructed({ text: rows, start: second, end: rows.length }),
+        rows,
+      ),
+    ).toEqual({ status: "resolved", start: second, end: rows.length, rung: 2 });
+  });
+
+  it("every constructed anchor parses through the published schema", () => {
+    const anchors = [
+      constructed(rangeOf(doc, "revised plan")),
+      insertionAt(doc, 0),
+      insertionAt(doc, doc.length),
+      insertionAt("", 0),
+    ];
+
+    // An anchor the route boundary rejects is a comment lost after it was
+    // composed, so the constructors validate before returning rather than
+    // asserting the shape they just built.
+    for (const anchor of anchors) {
+      expect(() => CommentAnchorSchema.parse(anchor)).not.toThrow();
+    }
+  });
+});

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

@@ -0,0 +1,143 @@
+/**
+ * The application receipt: one published key, one closed shape, one parser.
+ *
+ * WHAT THIS SUITE EXISTS TO KILL. The first wrong implementation returns the
+ * raw map value unvalidated — `readSuggestionReceipt = (v) => v as
+ * SuggestionReceipt`. It compiles, it is green against every well-formed row,
+ * and it never throws. Its symptom appears only when a peer writes something
+ * else into the map: a receipt whose `claimToken` is `undefined` is still
+ * TRUTHY-SHAPED enough to read as "this edit already landed", so the accept
+ * control is withdrawn from a live suggestion with no way back, and the token
+ * that gets posted is garbage. Every `toBeNull()` below is a row that
+ * implementation hands back as an object.
+ *
+ * The second is a parser that accepts an EMPTY `claimToken` or an empty
+ * `byUserId` — "it is a string, so it parsed". An empty token is not a lease;
+ * it is the absence of one wearing the right type, and it completes nothing.
+ *
+ * The third accepts a stringified `appliedAt`, or a `NaN` one. This is not a
+ * theoretical row: a CRDT map replicates raw JavaScript values with no schema
+ * of its own, so a peer can literally put `NaN` there.
+ *
+ * The fourth is a rename. `SUGGESTION_RECEIPTS_MAP` is the wire name of a root
+ * map, so a receipt written under any other spelling lands where nobody reads
+ * and the reader watches where nobody writes — with nothing anywhere throwing.
+ * The constant is therefore tested by restating its literal, so a rename is a
+ * red test rather than a silent second name.
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+  SUGGESTION_RECEIPTS_MAP,
+  SuggestionReceiptSchema,
+  readSuggestionReceipt,
+} from "../receipt.js";
+
+/**
+ * A well-formed row. Every negative case below mutates exactly ONE field of
+ * this, because a hand-built broken object can pass for the wrong reason — it
+ * fails because of the field nobody was testing.
+ */
+const makeReceipt = (
+  overrides: Record<string, unknown> = {},
+): Record<string, unknown> => ({
+  claimToken: "a".repeat(64),
+  appliedAt: 1_760_000_000_000,
+  byUserId: "user_01JQ",
+  ...overrides,
+});
+
+/** The same row with one field removed rather than replaced. */
+const withoutField = (field: string): Record<string, unknown> => {
+  const row = makeReceipt();
+  delete row[field];
+  return row;
+};
+
+describe("SUGGESTION_RECEIPTS_MAP — the key is the contract", () => {
+  it("names the root map receipts are written into", () => {
+    expect(SUGGESTION_RECEIPTS_MAP).toBe("suggestionReceipts");
+  });
+});
+
+describe("a receipt is parsed, not trusted", () => {
+  it("accepts a well-formed row and returns it field for field", () => {
+    const row = makeReceipt();
+
+    expect(readSuggestionReceipt(row)).toEqual({
+      claimToken: "a".repeat(64),
+      appliedAt: 1_760_000_000_000,
+      byUserId: "user_01JQ",
+    });
+  });
+
+  it("returns a parsed value, not the caller's object", () => {
+    // The pass-through implementation returns the input by reference. It is
+    // green on the assertion above and wrong on every assertion below it.
+    const row = makeReceipt();
+
+    expect(readSuggestionReceipt(row)).not.toBe(row);
+  });
+
+  it.each(["claimToken", "appliedAt", "byUserId"])(
+    "drops a row missing %s rather than returning a partial receipt",
+    (field) => {
+      expect(readSuggestionReceipt(withoutField(field))).toBeNull();
+    },
+  );
+
+  it("drops a row whose claimToken is empty", () => {
+    // An empty token is the absence of a lease wearing the right type. It
+    // completes nothing, and a receipt carrying one proves nothing landed.
+    expect(readSuggestionReceipt(makeReceipt({ claimToken: "" }))).toBeNull();
+  });
+
+  it("drops a row whose byUserId is empty", () => {
+    expect(readSuggestionReceipt(makeReceipt({ byUserId: "" }))).toBeNull();
+  });
+
+  it("drops a row whose appliedAt is a string", () => {
+    expect(
+      readSuggestionReceipt(makeReceipt({ appliedAt: "1760000000000" })),
+    ).toBeNull();
+  });
+
+  it.each([Number.NaN, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY])(
+    "drops a row whose appliedAt is %p — a CRDT replicates raw values",
+    (appliedAt) => {
+      expect(readSuggestionReceipt(makeReceipt({ appliedAt }))).toBeNull();
+    },
+  );
+
+  it("drops a row carrying a field outside the shape", () => {
+    // Strict, and the drop direction is why that is safe: an unrecognised row
+    // reads as "no receipt is known here", which every consumer must already
+    // handle, because a reader with no replica sees exactly the same thing.
+    expect(
+      readSuggestionReceipt(makeReceipt({ appliedBySomethingElse: true })),
+    ).toBeNull();
+  });
+
+  it.each([null, undefined, "suggestionReceipts", 7, []])(
+    "drops %p, which is not a row at all",
+    (value) => {
+      expect(readSuggestionReceipt(value)).toBeNull();
+    },
+  );
+
+  it("never throws, whatever the peer wrote", () => {
+    expect(() => readSuggestionReceipt(Symbol("nonsense"))).not.toThrow();
+  });
+});
+
+describe("SuggestionReceiptSchema", () => {
+  it("is the schema the parser reads, not a second description of it", () => {
+    // A parser hand-rolling its own checks beside the schema is how the two
+    // drift; this asserts they agree on a row the schema accepts.
+    const row = makeReceipt();
+
+    expect(readSuggestionReceipt(row)).toEqual(
+      SuggestionReceiptSchema.parse(row),
+    );
+  });
+});