@createiq/htmldiff 1.1.0 → 1.2.0-beta.1

package/test/HtmlDiff.analyze.spec.ts

@@ -0,0 +1,152 @@
+import { describe, expect, it } from 'vitest'
+
+import Action from '../src/Action'
+import HtmlDiff from '../src/HtmlDiff'
+
+describe('HtmlDiff.analyze', () => {
+  describe('return shape', () => {
+    it('returns operations indexed into oldDiffWords / newDiffWords', () => {
+      const result = HtmlDiff.analyze('a b c', 'a x c')
+      expect(result.oldDiffWords).toBeInstanceOf(Array)
+      expect(result.newDiffWords).toBeInstanceOf(Array)
+      expect(result.operations).toBeInstanceOf(Array)
+      // Every op's endInOld must be ≤ oldDiffWords.length, etc.
+      for (const op of result.operations) {
+        expect(op.endInOld).toBeLessThanOrEqual(result.oldDiffWords.length)
+        expect(op.endInNew).toBeLessThanOrEqual(result.newDiffWords.length)
+      }
+    })
+
+    it('returns original word arrays alongside the diff arrays', () => {
+      const result = HtmlDiff.analyze('hello world', 'hello there world')
+      expect(result.oldOriginalWords).toBeInstanceOf(Array)
+      expect(result.newOriginalWords).toBeInstanceOf(Array)
+    })
+
+    it('returns null contentToOriginal maps when projections are inactive', () => {
+      // Plain text with no structural tags → projection inactive.
+      const result = HtmlDiff.analyze('a b c', 'a x c')
+      expect(result.oldContentToOriginal).toBeNull()
+      expect(result.newContentToOriginal).toBeNull()
+    })
+
+    it('returns non-null contentToOriginal maps when projections are active', () => {
+      // Different wrapper tags → projection kicks in.
+      const result = HtmlDiff.analyze('<p>hello world</p>', '<div>hello world</div>')
+      expect(result.oldContentToOriginal).not.toBeNull()
+      expect(result.newContentToOriginal).not.toBeNull()
+    })
+  })
+
+  describe('useProjections option', () => {
+    it('honours useProjections=false even when the heuristic would project', () => {
+      const result = HtmlDiff.analyze('<p>hello world</p>', '<div>hello world</div>', { useProjections: false })
+      expect(result.oldContentToOriginal).toBeNull()
+      expect(result.newContentToOriginal).toBeNull()
+      // Structural tags appear as diff tokens — observable consequence.
+      expect(result.oldDiffWords).toContain('<p>')
+      expect(result.newDiffWords).toContain('<div>')
+    })
+
+    it('honours useProjections=true even when the heuristic would skip', () => {
+      // Same structural tags on both sides → heuristic skips projection.
+      // Forcing it should still project (strip the <p> tags from diff space).
+      const result = HtmlDiff.analyze('<p>a b c</p>', '<p>a x c</p>', { useProjections: true })
+      expect(result.oldContentToOriginal).not.toBeNull()
+      expect(result.newContentToOriginal).not.toBeNull()
+      // Structural tags removed from diff arrays.
+      expect(result.oldDiffWords).not.toContain('<p>')
+    })
+
+    it('keeps projections off when useProjections=true but one side has no content', () => {
+      const result = HtmlDiff.analyze('<p></p>', '<p>added</p>', { useProjections: true })
+      // Empty-content side disables the forced projection.
+      expect(result.oldContentToOriginal).toBeNull()
+      expect(result.newContentToOriginal).toBeNull()
+    })
+  })
+
+  describe('symmetric V2 tokenisation', () => {
+    it('produces an identical V2 diff array across two calls when useProjections matches', () => {
+      const v1 = '<p>Hello world.</p>'
+      const v2 = '<p>Hello cruel world.</p>'
+      const v3 = '<p>Hello cruel world today.</p>'
+      const useProjections = false // Force off — both calls agree.
+      const d1 = HtmlDiff.analyze(v1, v2, { useProjections })
+      const d2 = HtmlDiff.analyze(v2, v3, { useProjections })
+      expect(d1.newDiffWords).toEqual(d2.oldDiffWords)
+    })
+
+    it('the V2 arrays diverge when one call projects and the other does not (motivates D1)', () => {
+      // Asymmetric structural patterns: V1 has <p>, V3 has <div>; V2 has <p>.
+      // V1↔V2 heuristic: no structural diff → no projection.
+      // V2↔V3 heuristic: structural diff → project.
+      // Result: d1.newDiffWords (raw V2) ≠ d2.oldDiffWords (projected V2).
+      const v1 = '<p>Hello world.</p>'
+      const v2 = '<p>Hello cruel world.</p>'
+      const v3 = '<div>Hello cruel world today.</div>'
+      const d1 = HtmlDiff.analyze(v1, v2)
+      const d2 = HtmlDiff.analyze(v2, v3)
+      // This is the bug that D1's symmetric-decision design exists to prevent.
+      expect(d1.newDiffWords).not.toEqual(d2.oldDiffWords)
+    })
+  })
+
+  describe('options pass-through', () => {
+    it('respects ignoreWhitespaceDifferences', () => {
+      // With the flag on, the matcher should consider two-space and
+      // single-space as equivalent; without it, they replace.
+      const withoutFlag = HtmlDiff.analyze('a  b', 'a b')
+      const withFlag = HtmlDiff.analyze('a  b', 'a b', { ignoreWhitespaceDifferences: true })
+      const replaceCount = (r: typeof withFlag) => r.operations.filter(op => op.action === Action.Replace).length
+      // Flag off: whitespace difference shows up as a Replace.
+      expect(replaceCount(withoutFlag)).toBeGreaterThan(0)
+      // Flag on: no Replace, only Equals.
+      expect(replaceCount(withFlag)).toBe(0)
+    })
+
+    it('respects blockExpressions', () => {
+      // Without the block expression, "01/01/2026" is split into multiple
+      // tokens; with it, the whole date is one token (per WordSplitter's
+      // BlockFinder contract — uses the `g` flag).
+      const dateExpr = /\d{2}\/\d{2}\/\d{4}/g
+      const without = HtmlDiff.analyze('on 01/01/2026 here', 'on 02/02/2027 here')
+      const withExpr = HtmlDiff.analyze('on 01/01/2026 here', 'on 02/02/2027 here', { blockExpressions: [dateExpr] })
+      expect(withExpr.oldDiffWords.length).toBeLessThan(without.oldDiffWords.length)
+    })
+  })
+})
+
+describe('HtmlDiff.evaluateProjectionApplicability', () => {
+  it('returns false when structures match', () => {
+    expect(HtmlDiff.evaluateProjectionApplicability('<p>a</p>', '<p>b</p>')).toBe(false)
+  })
+
+  it('returns true when structures differ (wrapper rename)', () => {
+    expect(HtmlDiff.evaluateProjectionApplicability('<p>a b c</p>', '<div>a b c</div>')).toBe(true)
+  })
+
+  it('returns false when one side has no structural tags at all', () => {
+    // Plain text vs wrapped HTML: shouldUseContentProjections bails.
+    expect(HtmlDiff.evaluateProjectionApplicability('plain text', '<p>plain text</p>')).toBe(false)
+  })
+
+  it('returns false when projection would empty one side', () => {
+    expect(HtmlDiff.evaluateProjectionApplicability('<p></p>', '<div>content</div>')).toBe(false)
+  })
+
+  it('lets a composer compute a symmetric decision across three inputs', () => {
+    const v1 = '<p>Hello world.</p>'
+    const v2 = '<p>Hello cruel world.</p>'
+    const v3 = '<div>Hello cruel world today.</div>'
+    const proj12 = HtmlDiff.evaluateProjectionApplicability(v1, v2)
+    const proj23 = HtmlDiff.evaluateProjectionApplicability(v2, v3)
+    // The symmetric decision is the conjunction — project iff both pairs would.
+    const symmetric = proj12 && proj23
+    expect(symmetric).toBe(false) // V1↔V2 has no structural diff.
+    // Both calls then use useProjections=false and V2 tokenises identically.
+    const d1 = HtmlDiff.analyze(v1, v2, { useProjections: symmetric })
+    const d2 = HtmlDiff.analyze(v2, v3, { useProjections: symmetric })
+    expect(d1.newDiffWords).toEqual(d2.oldDiffWords)
+  })
+})

package/test/HtmlDiff.tables.spec.ts

@@ -1586,12 +1586,13 @@ describe('HtmlDiff — tables', () => {
     })
   })
 
-  // Coverage gaps surfaced by the v8 report: the cell-LCS fallback path
-  // (diffStructurallyAlignedRow + cellKey + pairSimilarUnmatchedCells) is
-  // only entered when the per-row column delta exceeds MAX_COLUMN_DELTA
-  // (6) or the row's logical width exceeds MAX_COLUMN_SEARCH_WIDTH (40).
-  // None of the existing tests trigger that. These tests exercise the
-  // fallback and pin its behaviour.
+  // The cell-LCS fallback path (diffStructurallyAlignedRow + cellKey +
+  // pairSimilarUnmatchedCells) is now entered only when the per-row
+  // column delta exceeds MAX_COLUMN_DELTA (6) — the semantic "this is a
+  // row rewrite, not a column add" guard. The row-width guard
+  // (MAX_COLUMN_SEARCH_WIDTH) is now defensive only since the DP is
+  // O(M × N). These tests pin the fallback's behaviour for the
+  // delta > 6 path.
   describe('cell-LCS fallback for very-wide column changes', () => {
     it('handles 8 columns inserted alongside existing cells (delta > MAX_COLUMN_DELTA)', () => {
       // Old: 3 cells. New: 11 cells (8 columns added). Exact-LCS finds
@@ -1716,11 +1717,11 @@ describe('HtmlDiff — tables', () => {
       )
     })
 
-    it('handles row wider than MAX_COLUMN_SEARCH_WIDTH (40 cells) — fallback to cell-LCS', () => {
+    it('handles a 50-cell row with a single column inserted at start', () => {
       // 50-cell row in old, 51-cell row in new (1 column added at
-      // start). MAX_COLUMN_SEARCH_WIDTH guard prevents the
-      // combinatorial search; fallback to cell-LCS which finds 50
-      // exact matches and the 1 new cell as an insertion.
+      // start). Now stays on the DP path (MAX_COLUMN_SEARCH_WIDTH=200);
+      // produces the same output as the prior cell-LCS fallback would
+      // have: 1 inserted cell, 50 preserved.
       const oldCells = Array.from({ length: 50 }, (_, i) => `<td>c${i}</td>`).join('')
       const newCells = `<td>NEW</td>${oldCells}`
       const oldHtml = `<table><tr>${oldCells}</tr></table>`
@@ -1758,21 +1759,44 @@ describe('HtmlDiff — tables', () => {
     })
   })
 
-  // The combinatorial position search can encounter score ties when
-  // inserted cells have content that is similar both to each other and to
+  // The column-position search can encounter score ties when inserted
+  // cells have content that is similar both to each other and to
   // existing cells (e.g. boilerplate "N/A" in a legal schedule). The
-  // algorithm resolves ties by combination-iteration order, so the choice
-  // of which specific column gets the diffins marker is deterministic
-  // but not necessarily the "intuitive" one. These tests lock in the
-  // observed behaviour and guard against silent regressions in the
-  // structural shape: all original cells must survive unmarked, and the
-  // inserted-marker count must equal the column delta.
-  describe('combinatorial column search — score-tied inputs', () => {
+  // algorithm's tie-breaking resolves to skipping LATER positions in
+  // the longer side — the lex-first-combo behaviour of the original
+  // combinatorial path, now matched by "prefer pair on ties" in the DP
+  // backtrack. These tests pin both the structural shape AND the exact
+  // positions the diffins markers land on, so a silent shift of the
+  // tie-breaking rule would fail loudly.
+  describe('column-position search — score-tied inputs', () => {
     it('handles delta=2 with content-similar inserts (N/A boilerplate)', () => {
       const oldHtml = '<table><tr><td>N/A</td><td>Term</td><td>Amount</td><td>N/A</td></tr></table>'
       const newHtml =
         '<table><tr><td>N/A</td><td>N/A</td><td>Term</td><td>N/A</td><td>Amount</td><td>N/A</td></tr></table>'
 
+      // Exact match locks in tie-breaking: the diffins markers MUST land
+      // on the earliest positions that produce the optimal score (here:
+      // positions 0 and 3).
+      expect(HtmlDiff.execute(oldHtml, newHtml)).toEqual(
+        '<table><tr>' +
+          "<td class='diffins'><ins class='diffins'>N/A</ins></td>" +
+          '<td>N/A</td>' +
+          '<td>Term</td>' +
+          "<td class='diffins'><ins class='diffins'>N/A</ins></td>" +
+          '<td>Amount</td>' +
+          '<td>N/A</td>' +
+          '</tr></table>'
+      )
+    })
+
+    it('still passes the loose structural checks for the same inputs', () => {
+      // Kept alongside the exact-match assertion above as a structural
+      // safety net: if the exact form ever shifts (e.g. quote style),
+      // these structural invariants still apply.
+      const oldHtml = '<table><tr><td>N/A</td><td>Term</td><td>Amount</td><td>N/A</td></tr></table>'
+      const newHtml =
+        '<table><tr><td>N/A</td><td>N/A</td><td>Term</td><td>N/A</td><td>Amount</td><td>N/A</td></tr></table>'
+
       const result = HtmlDiff.execute(oldHtml, newHtml)
       // Both inserted N/A cells must be marked diffins.
       const insMarkers = (result.match(/<td class='diffins'>/g) || []).length

package/test/HtmlDiff.threeWay.spec.ts

@@ -0,0 +1,173 @@
+import { describe, expect, it } from 'vitest'
+
+import HtmlDiff from '../src/HtmlDiff'
+
+/**
+ * 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('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('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 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('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 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"
+      )
+    })
+
+    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('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('all three identical → input verbatim', () => {
+      const text = '<p>Nothing changed at all.</p>'
+      expect(HtmlDiff.executeThreeWay(text, text, text)).toBe(text)
+    })
+
+    it('empty inputs produce empty output', () => {
+      expect(HtmlDiff.executeThreeWay('', '', '')).toBe('')
+    })
+
+    it('cp matches genesis (only Me changed)', () => {
+      expect(HtmlDiff.executeThreeWay('Hello world', 'Hello world', 'Hello brave world')).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', () => {
+      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('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 })
+      expect(without).toContain("data-author='me'")
+      expect(withFlag).not.toContain('data-author=')
+    })
+  })
+
+  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>',
+        '<p>Draft contract with amendments.</p>'
+      )
+      expect(out).toContain("data-author='me'")
+      expect(out).not.toContain("data-author='cp'")
+    })
+  })
+})