@createiq/htmldiff 1.1.0 → 1.2.0-beta.0

package/src/Utils.ts

@@ -32,8 +32,39 @@ export function stripTagAttributes(word: string): string {
   return word
 }
 
-export function wrapText(text: string, tagName: string, cssClass: string): string {
-  return `<${tagName} class='${cssClass}'>${text}</${tagName}>`
+/**
+ * Optional metadata attached to a wrapped tag. Used by `executeThreeWay`
+ * to colour diff segments with their author (CP vs Me) via extra classes
+ * and `data-*` attributes; the two-way path passes nothing and gets the
+ * unchanged historical output.
+ */
+export interface WrapMetadata {
+  /** Space-separated classes appended after `cssClass`. */
+  extraClasses?: string
+  /** `data-*` attribute map, keyed by the attribute name *without* the `data-` prefix. */
+  dataAttrs?: Readonly<Record<string, string>>
+}
+
+export function wrapText(text: string, tagName: string, cssClass: string, metadata?: WrapMetadata): string {
+  if (!metadata) return `<${tagName} class='${cssClass}'>${text}</${tagName}>`
+  return `<${tagName}${composeTagAttributes(cssClass, metadata)}>${text}</${tagName}>`
+}
+
+/**
+ * Build the attribute portion of an opening tag from a base class plus
+ * optional metadata. Exposed so emission paths that build opening-tag
+ * fragments by hand (e.g. the formatting-tag special-case in
+ * `HtmlDiff.insertTag`) can stay consistent with `wrapText`.
+ */
+export function composeTagAttributes(cssClass: string, metadata: WrapMetadata): string {
+  const classes = metadata.extraClasses ? `${cssClass} ${metadata.extraClasses}` : cssClass
+  let out = ` class='${classes}'`
+  if (metadata.dataAttrs) {
+    for (const key of Object.keys(metadata.dataAttrs)) {
+      out += ` data-${key}='${metadata.dataAttrs[key]}'`
+    }
+  }
+  return out
 }
 
 export function isStartOfTag(val: string): boolean {
@@ -85,6 +116,7 @@ export default {
   isTag,
   stripTagAttributes,
   wrapText,
+  composeTagAttributes,
   isStartOfTag,
   isEndOfTag,
   isStartOfEntity,

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,175 @@
+import { describe, expect, it } from 'vitest'
+
+import HtmlDiff from '../src/HtmlDiff'
+
+describe('HtmlDiff.executeThreeWay', () => {
+  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('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('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 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-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."
+      )
+    })
+  })
+
+  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('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>"
+      )
+    })
+  })
+
+  describe('identity inputs', () => {
+    it('V1 == V2 == V3 returns the 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('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('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'")
+    })
+  })
+
+  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('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>"
+      )
+    })
+  })
+
+  describe('options pass-through', () => {
+    it('honours ignoreWhitespaceDifferences', () => {
+      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.
+      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'")
+    })
+  })
+})