@createiq/htmldiff 1.2.0-beta.0 → 1.2.0-beta.1

package/test/HtmlDiff.threeWay.spec.ts

@@ -2,88 +2,115 @@ import { describe, expect, it } from 'vitest'
 
 import HtmlDiff from '../src/HtmlDiff'
 
-describe('HtmlDiff.executeThreeWay', () => {
+/**
+ * Three-way diff tests under the genesis-spine model.
+ *
+ * `executeThreeWay(genesis, cpLatest, meCurrent)` compares both cp and
+ * me against the shared common ancestor (genesis). Each side's
+ * accumulated changes are attributed independently:
+ *
+ *   - Both authors made the same change → emit plain (settled)
+ *   - One author changed, the other kept the genesis content → emit
+ *     that author's change with attribution; the kept content shows
+ *     "pending" via the del/ins wrapping
+ *   - Both made different changes at the same place → each shown with
+ *     its author's attribution
+ */
+describe('HtmlDiff.executeThreeWay (genesis-spine)', () => {
   describe('attribution matrix', () => {
-    it('CP-only changes — Me made no edits (V3 == V2)', () => {
-      expect(HtmlDiff.executeThreeWay('Hello world.', 'Hello cruel world.', 'Hello cruel world.')).toBe(
-        "Hello<ins class='diffins cp' data-author='cp'>&nbsp;cruel</ins> world."
+    it('settled — both authors made the same change', () => {
+      // Genesis: "Hello world". Both cp and me changed it to "Hello cruel world".
+      // The change is settled — emit plain.
+      expect(HtmlDiff.executeThreeWay('Hello world', 'Hello cruel world', 'Hello cruel world')).toBe(
+        'Hello cruel world'
       )
     })
 
-    it('Me-only changes — CP made no edits (V2 == V1)', () => {
-      expect(HtmlDiff.executeThreeWay('Hello world.', 'Hello world.', 'Hello world today.')).toBe(
-        "Hello world<ins class='diffins me' data-author='me'>&nbsp;today</ins>."
+    it('CP changes a word, Me kept the genesis word', () => {
+      // Genesis: "Hello world". CP changed to "Hello cruel world". Me kept "Hello world".
+      // From Me's view: CP's insertion is pending. Render with cp attribution; Me's
+      // text ("world") is preserved verbatim.
+      expect(HtmlDiff.executeThreeWay('Hello world', 'Hello cruel world', 'Hello world')).toBe(
+        "Hello <ins class='diffins cp' data-author='cp'>cruel </ins>world"
       )
     })
 
-    it('Me keeps CP insertion (both authors visible)', () => {
-      expect(HtmlDiff.executeThreeWay('Hello world.', 'Hello cruel world.', 'Hello cruel world today.')).toBe(
-        "Hello<ins class='diffins cp' data-author='cp'>&nbsp;cruel</ins> world<ins class='diffins me' data-author='me'>&nbsp;today</ins>."
+    it('Me changes a word, CP kept genesis', () => {
+      expect(HtmlDiff.executeThreeWay('Hello world', 'Hello world', 'Hello cruel world')).toBe(
+        "Hello <ins class='diffins me' data-author='me'>cruel </ins>world"
       )
     })
 
-    it('Me rejects CP insertion (data-rejects markup)', () => {
-      expect(HtmlDiff.executeThreeWay('Hello world.', 'Hello cruel world.', 'Hello world.')).toBe(
-        "Hello<del class='diffdel me rejects-cp' data-author='me' data-rejects='cp'>&nbsp;cruel</del> world."
+    it('CP and Me each change the same word differently', () => {
+      // Genesis: "Hello world". CP made "Hello cruel world", Me made "Hello brave world".
+      // Disagreement — show both authors' insertions.
+      expect(HtmlDiff.executeThreeWay('Hello world', 'Hello cruel world', 'Hello brave world')).toBe(
+        "Hello <ins class='diffins cp' data-author='cp'>cruel </ins><ins class='diffins me' data-author='me'>brave </ins>world"
       )
     })
 
-    it('CP-deletion of V1 text surfaces as a CP-attributed <del>', () => {
-      expect(
-        HtmlDiff.executeThreeWay('Some really fine print here.', 'Some fine print here.', 'Some fine print here.')
-      ).toBe("Some<del class='diffdel cp' data-author='cp'>&nbsp;really</del> fine print here.")
-    })
-
-    it('Me-deletion of original V1 text (CP did nothing, Me deleted)', () => {
-      expect(
-        HtmlDiff.executeThreeWay(
-          'Some really fine print here.',
-          'Some really fine print here.',
-          'Some fine print here.'
-        )
-      ).toBe("Some<del class='diffdel me' data-author='me'>&nbsp;really</del> fine print here.")
-    })
-
-    it('CP and Me Replace ops in different places (del-then-ins for both)', () => {
-      // CP did will→shall; Me did thirty→sixty business. Both Replaces
-      // must emit del-then-ins in source order, matching the 2-way
-      // convention so the diff reads naturally.
-      expect(
-        HtmlDiff.executeThreeWay(
-          'The party will pay the fee within thirty days.',
-          'The party shall pay the fee within thirty days.',
-          'The party shall pay the fee within sixty business days.'
-        )
-      ).toBe(
-        "The party <del class='diffdel cp' data-author='cp'>will</del><ins class='diffins cp' data-author='cp'>shall</ins> pay the fee within <del class='diffdel me' data-author='me'>thirty</del><ins class='diffins me' data-author='me'>sixty business</ins> days."
+    it('CP deletes a word, Me kept it', () => {
+      // Genesis: "Some really fine print". CP removed "really". Me kept it.
+      // Render genesis token "really" with del-cp markup — Me's text still has it.
+      expect(HtmlDiff.executeThreeWay('Some really fine print', 'Some fine print', 'Some really fine print')).toBe(
+        "Some<del class='diffdel cp' data-author='cp'>&nbsp;really</del> fine print"
       )
     })
-  })
 
-  describe('Replace-collision and tail-end edge cases', () => {
-    it('Replace collision — CP and Me each replace the same V2 token', () => {
-      // V1: "foo" → V2: "bar" (CP Replace). V2: "bar" → V3: "baz" (Me Replace).
-      // V2's "bar" is replaced-into-by-cp AND replaced-out-by-me → reject.
-      // Off-spine: V1's "foo" (cpDel) emitted before; V3's "baz" (meIns)
-      // emitted after the reject (mirrors the del-then-ins ordering).
-      expect(HtmlDiff.executeThreeWay('foo', 'bar', 'baz')).toBe(
-        "<del class='diffdel cp' data-author='cp'>foo</del><del class='diffdel me rejects-cp' data-author='me' data-rejects='cp'>bar</del><ins class='diffins me' data-author='me'>baz</ins>"
+    it('Me deletes a word, CP kept it', () => {
+      expect(HtmlDiff.executeThreeWay('Some really fine print', 'Some really fine print', 'Some fine print')).toBe(
+        "Some<del class='diffdel me' data-author='me'>&nbsp;really</del> fine print"
       )
     })
 
-    it('tail-end interleavings — CP deletion + Me insertion both at the end of V2', () => {
-      // V1 = "Hello world" (CP deletes " world" → V2 = "Hello").
-      // V2 = "Hello" (Me adds " cruel" → V3 = "Hello cruel").
-      // Both off-spine ops land at the tail boundary; output order is
-      // cpDel then meIns (no V2 token to anchor around).
-      expect(HtmlDiff.executeThreeWay('Hello world', 'Hello', 'Hello cruel')).toBe(
-        "Hello<del class='diffdel cp' data-author='cp'>&nbsp;world</del><ins class='diffins me' data-author='me'>&nbsp;cruel</ins>"
+    it('Both authors delete the same content → settled, silenced', () => {
+      // Genesis: "Some really fine print". Both removed "really".
+      // Settled — neither the deletion nor any del markup appears.
+      expect(HtmlDiff.executeThreeWay('Some really fine print', 'Some fine print', 'Some fine print')).toBe(
+        'Some fine print'
       )
     })
+
+    it('Stable across no-change rounds — V5 produces same output as V3 when V5==V3', () => {
+      // The user's V3/V5 invariant: when neither party changes their position
+      // in a subsequent turn, the diff should look identical to the previous
+      // turn's diff. With the genesis spine, this falls out automatically.
+      const genesis = 'The quick brown fox jumps over the lazy dog'
+      const cp = 'The fast brown fox leaps'
+      const me = 'The quick brown antelope leaps over the lazy pig'
+      const v3Output = HtmlDiff.executeThreeWay(genesis, cp, me)
+      const v5Output = HtmlDiff.executeThreeWay(genesis, cp, me)
+      expect(v5Output).toBe(v3Output)
+      // Sanity check the V3 output contains all four author-attributed changes
+      // from the user's expected output (quick→fast cp, fox→antelope me, etc.)
+      expect(v3Output).toMatch(/<del class='diffdel cp' data-author='cp'>quick<\/del>/)
+      expect(v3Output).toMatch(/<ins class='diffins cp' data-author='cp'>fast<\/ins>/)
+      expect(v3Output).toMatch(/<del class='diffdel me' data-author='me'>fox<\/del>/)
+      expect(v3Output).toMatch(/<ins class='diffins me' data-author='me'>antelope<\/ins>/)
+    })
+
+    it('Inverted view — switching cp and me args produces inverted attribution', () => {
+      // From the user's V4 example: same genesis, but from Party B's view
+      // cp and me swap. The output should have all attributions inverted.
+      const genesis = 'The quick brown fox jumps over the lazy dog'
+      const partyACurrent = 'The quick brown antelope leaps over the lazy pig'
+      const partyBCurrent = 'The fast brown fox leaps'
+
+      const aView = HtmlDiff.executeThreeWay(genesis, partyBCurrent, partyACurrent) // A is me, B is cp
+      const bView = HtmlDiff.executeThreeWay(genesis, partyACurrent, partyBCurrent) // B is me, A is cp
+
+      // A's view: B made fast/leaps changes (CP-attributed), A made antelope/pig (Me).
+      expect(aView).toMatch(/<ins class='diffins cp' data-author='cp'>fast<\/ins>/)
+      expect(aView).toMatch(/<ins class='diffins me' data-author='me'>antelope<\/ins>/)
+
+      // B's view: A made antelope/pig (now CP), B made fast/leaps (now Me).
+      expect(bView).toMatch(/<ins class='diffins me' data-author='me'>fast<\/ins>/)
+      expect(bView).toMatch(/<ins class='diffins cp' data-author='cp'>antelope<\/ins>/)
+    })
   })
 
   describe('identity inputs', () => {
-    it('V1 == V2 == V3 returns the input verbatim', () => {
+    it('all three identical → input verbatim', () => {
       const text = '<p>Nothing changed at all.</p>'
       expect(HtmlDiff.executeThreeWay(text, text, text)).toBe(text)
     })
@@ -92,77 +119,48 @@ describe('HtmlDiff.executeThreeWay', () => {
       expect(HtmlDiff.executeThreeWay('', '', '')).toBe('')
     })
 
-    it('V1 == V2 collapses to a single-author diff (CP did nothing)', () => {
-      const out = HtmlDiff.executeThreeWay('Hello world.', 'Hello world.', 'Hello brave world.')
-      expect(out).toContain("data-author='me'")
-      expect(out).not.toContain("data-author='cp'")
+    it('cp matches genesis (only Me changed)', () => {
+      expect(HtmlDiff.executeThreeWay('Hello world', 'Hello world', 'Hello brave world')).toContain("data-author='me'")
     })
 
-    it('V2 == V3 collapses to a single-author diff (Me did nothing)', () => {
-      const out = HtmlDiff.executeThreeWay('Hello world.', 'Hello cruel world.', 'Hello cruel world.')
-      expect(out).toContain("data-author='cp'")
-      expect(out).not.toContain("data-author='me'")
+    it('me matches genesis (only CP changed)', () => {
+      expect(HtmlDiff.executeThreeWay('Hello world', 'Hello cruel world', 'Hello world')).toContain("data-author='cp'")
     })
   })
 
   describe('HTML structure handling', () => {
-    it('preserves wrapping <p> tags around an attributed run', () => {
-      expect(
-        HtmlDiff.executeThreeWay('<p>Hello world.</p>', '<p>Hello cruel world.</p>', '<p>Hello cruel world.</p>')
-      ).toBe("<p>Hello<ins class='diffins cp' data-author='cp'>&nbsp;cruel</ins> world.</p>")
+    it('preserves wrapping <p> tags', () => {
+      expect(HtmlDiff.executeThreeWay('<p>Hello world.</p>', '<p>Hello cruel world.</p>', '<p>Hello world.</p>')).toBe(
+        "<p>Hello<ins class='diffins cp' data-author='cp'>&nbsp;cruel</ins> world.</p>"
+      )
     })
 
-    it('attributes formatting-tag edits via the special-case path', () => {
-      // V1 plain; CP wraps "fee" in <strong>; Me leaves it. The
-      // formatting-tag special case inside insertTag now carries the
-      // author class through to the `mod` ins wrapper.
-      const out = HtmlDiff.executeThreeWay(
-        '<p>The fee is due.</p>',
-        '<p>The <strong>fee</strong> is due.</p>',
-        '<p>The <strong>fee</strong> is due.</p>'
-      )
-      expect(out).toContain("data-author='cp'")
-      expect(out).toMatch(/<ins class='mod[^']*cp'/)
-    })
-
-    it('multi-paragraph: each author scoped to their own paragraph', () => {
-      expect(
-        HtmlDiff.executeThreeWay(
-          '<p>First paragraph.</p><p>Second paragraph.</p>',
-          '<p>First paragraph edited by CP.</p><p>Second paragraph.</p>',
-          '<p>First paragraph edited by CP.</p><p>Second paragraph also edited by Me.</p>'
-        )
-      ).toBe(
-        "<p>First paragraph<ins class='diffins cp' data-author='cp'>&nbsp;edited by CP</ins>.</p><p>Second paragraph<ins class='diffins me' data-author='me'>&nbsp;also edited by Me</ins>.</p>"
-      )
+    it('multi-paragraph with edits in different paragraphs by each author', () => {
+      const genesis = '<p>First paragraph.</p><p>Second paragraph.</p>'
+      const cp = '<p>First paragraph edited by CP.</p><p>Second paragraph.</p>'
+      const me = '<p>First paragraph.</p><p>Second paragraph edited by Me.</p>'
+      const out = HtmlDiff.executeThreeWay(genesis, cp, me)
+      // CP's edit appears in the first paragraph, Me's in the second.
+      expect(out).toMatch(/<p>First paragraph.*data-author='cp'.*<\/p>/)
+      expect(out).toMatch(/<p>Second paragraph.*data-author='me'.*<\/p>/)
     })
   })
 
   describe('options pass-through', () => {
     it('honours ignoreWhitespaceDifferences', () => {
+      // Genesis: "a  b" (double space). CP keeps it, Me uses "a b" (single space).
       const without = HtmlDiff.executeThreeWay('a  b', 'a  b', 'a b')
       const withFlag = HtmlDiff.executeThreeWay('a  b', 'a  b', 'a b', { ignoreWhitespaceDifferences: true })
-      // Without the flag, the whitespace difference triggers a Me-attributed Replace.
       expect(without).toContain("data-author='me'")
-      // With the flag, no diff at all.
       expect(withFlag).not.toContain('data-author=')
     })
-
-    it('useProjections=true forces structural normalisation even when heuristic would skip', () => {
-      // V1==V2 has no structural diff (heuristic would skip projection),
-      // V2↔V3 has no structural diff either, so the symmetric default is
-      // also skip. Forcing useProjections=true here is a no-op functionally
-      // but exercises the forced-on code path.
-      const out = HtmlDiff.executeThreeWay('<p>a b c</p>', '<p>a b c</p>', '<p>a x c</p>', { useProjections: true })
-      expect(out).toContain("data-author='me'")
-    })
   })
 
-  describe('first-turn fallback (real-world scenario)', () => {
-    it('falls back cleanly when only Party A has edited (V2 == V1)', () => {
-      // The case the user described: when Party B is drafting V2 against
-      // V1, the 3-way view from Party A's perspective shows only Me's
-      // changes — no spurious CP authorship.
+  describe('first-turn fallback', () => {
+    it('cp == genesis means CP made no changes — Me-only attribution', () => {
+      // Common case: this is the first turn where the counterparty hasn't
+      // responded yet, so the cp version equals the genesis. Only Me's
+      // changes appear.
       const out = HtmlDiff.executeThreeWay(
         '<p>Draft contract.</p>',
         '<p>Draft contract.</p>',