@createiq/htmldiff 1.2.0-beta.2 → 1.2.0-beta.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@createiq/htmldiff",
-  "version": "1.2.0-beta.2",
+  "version": "1.2.0-beta.4",
   "description": "TypeScript port of htmldiff.net",
   "type": "module",
   "author": "Mathew Mannion <mathew.mannion@linklaters.com>",

package/src/HtmlDiff.ts

@@ -335,22 +335,6 @@ export default class HtmlDiff {
     return HtmlDiff.shouldUseContentProjections(oldWords, newWords, oldProj, newProj)
   }
 
-  /**
-   * Three-way HTML diff. Given V1 (the version Me last sent), V2 (the
-   * version CP sent back), and V3 (Me's current draft), produces a
-   * single attributed HTML output where CP's and Me's changes are
-   * distinguished by `data-author` ('cp' or 'me') and matching
-   * `class='diffins cp'` / `class='diffdel me'` etc. The "Me rejected
-   * CP's proposal" case (Me deleted text CP had inserted) gets a
-   * dedicated marker: `data-rejects='cp'` plus `class='... rejects-cp'`.
-   *
-   * Coordinates the symmetric-projection decision (D1) across both
-   * internal `analyze` calls so V2 tokenises identically on each side
-   * of the spine. When `useProjections` is left undefined, the decision
-   * is the conjunction of both pair-wise heuristics — project iff both
-   * pairs would project on their own. Pass an explicit boolean to
-   * override.
-   */
   /**
    * Three-way HTML diff against a shared genesis. Produces attributed
    * HTML that distinguishes CP's accumulated changes (genesis → cpLatest)
@@ -439,6 +423,17 @@ export default class HtmlDiff {
    * buffer. Reusing the instance keeps the formatting-tag stack
    * (`specialTagDiffStack`) coherent across segments — a `<strong>`
    * opened in one segment and closed in another stays balanced.
+   *
+   * Edge case: an ins/del segment can open a formatting wrap whose
+   * matching closer ends up in an equal segment (`<strong>` deleted
+   * by CP but `</strong>` kept by both — buildSegments emits the open
+   * as del-cp and the close as equal). Equal segments bypass
+   * `insertTag` and push raw, so the stack entry for the open is
+   * never popped. Rather than throw — which forces the caller's UI
+   * into an error boundary — close every leftover wrap with `</ins>`
+   * at the end of emission. The resulting HTML has an extra
+   * `</ins>` next to the formatting closer; DOMParser-normalisation
+   * downstream produces sensible nesting.
    */
   private static emitSegments(segments: Segment[]): string {
     const emitter = new HtmlDiff('', '')
@@ -451,18 +446,21 @@ export default class HtmlDiff {
       // insertTag mutates its `words` array; pass a copy.
       emitter.insertTag(tag, baseClass, [...seg.words], metadata)
     }
-    // Stack-balance invariant: every special-case opening tag pushed onto
-    // `specialTagDiffStack` during emission must have been matched by a
-    // closing tag. An unbalanced stack means the input had unbalanced
-    // formatting tags AND a Replace at an inconvenient position — the
-    // output would be silently malformed (half-closed `<ins>`). Fail
-    // loudly so the caller can investigate rather than ship broken HTML.
     if (emitter.specialTagDiffStack.length > 0) {
-      throw new Error(
+      // Log once so we can spot bad inputs in dev tools, but don't
+      // throw — the caller's only fallback was to crash the React
+      // tree, which is worse than emitting slightly-imperfect HTML.
+      // eslint-disable-next-line no-console
+      console.warn(
         `HtmlDiff.executeThreeWay: emission left ${emitter.specialTagDiffStack.length} ` +
-          'unclosed formatting tag(s) on the stack — input may have unbalanced ' +
-          '<strong>/<em>/etc. or there is a bug in segment emission.'
+          'unclosed formatting wrap(s) on the stack. Closing defensively. ' +
+          'This usually means a formatting tag opens in a del/ins segment ' +
+          'and its matching closer is in an equal segment.'
       )
+      while (emitter.specialTagDiffStack.length > 0) {
+        emitter.content.push('</ins>')
+        emitter.specialTagDiffStack.pop()
+      }
     }
     return emitter.content.join('')
   }

package/src/ThreeWayTable.ts

@@ -303,7 +303,21 @@ function preprocessByContent(
   return { modifiedGenesis, modifiedCp, modifiedMe, placeholderToDiff }
 }
 
-const POSITIONAL_PAIR_SIMILARITY_THRESHOLD = 0.5
+// Positional pairing is the strict-default for three-way table merge:
+// when all three inputs have the same number of tables in the same
+// order, we pair them by index and let `diffTableThreeWay` handle
+// per-table cell/row level differences. The similarity guard below
+// only kicks in to *reject* positional alignment when a pair is
+// SO dissimilar that it's near-certainly a table reorder/rename
+// where content-LCS pairing would be materially better. The
+// threshold is intentionally low — the 2-way path has no such guard
+// and pairs purely by index (its `diffTable` falls back through
+// same-dimension → equal-row-count → row-LCS → whole-table on its
+// own), so the three-way path was stricter than its sibling and
+// silently dropped to whole-table del+ins for legitimate edits
+// like "rename one column and tweak its values". Aligning the
+// threshold here keeps the two-way and three-way paths in step.
+const POSITIONAL_PAIR_SIMILARITY_THRESHOLD = 0.15
 
 function positionallyAligned(
   genesis: string,
@@ -521,9 +535,40 @@ function emitPreservedRow(
     return out.join('')
   }
   // Cell-count mismatch within a preserved row — cell-level structural
-  // change deferred. Fall back to me-attributed Replace (genesis row
-  // removed, me row inserted). Lossy for CP within that row.
-  return emitFullRowAttributed(genesis, rG, 'del', 'me') + emitFullRowAttributed(meCurrent, rM, 'ins', 'me')
+  // alignment is non-trivial (which Me cell maps to which CP cell when
+  // the counts diverge?). The previous fallback emitted only
+  // genesis-as-del + me-as-ins, which silently destroyed CP's row
+  // content whenever CP changed the cell count — a content-loss bug
+  // (a row where CP added a column would disappear from the rendered
+  // diff entirely). Emit each side's row as a distinct attributed
+  // block so neither party's restructure can vanish:
+  //   - if both restructured (different shapes on both sides) the
+  //     genesis row is settled-deleted (silent) and we emit cp + me
+  //     rows side by side, each attributed to its author;
+  //   - if only one restructured, the genesis row is del-attributed to
+  //     the restructuring author so the reader sees what was there
+  //     before, then the new shape ins-attributed to the same author.
+  //
+  // Content edits inside a side that DID keep the genesis cell count
+  // are not surfaced here (no positional path is available across
+  // mismatched shapes); the underlying data is still present in the
+  // source document but the visual diff doesn't decompose it. That is
+  // a degradation of detail, not content loss — symmetric for cp/me.
+  const cpRestructured = rC.cells.length !== rG.cells.length
+  const meRestructured = rM.cells.length !== rG.cells.length
+  const blocks: string[] = []
+  if (cpRestructured && meRestructured) {
+    // Both sides restructured; genesis shape retained by neither.
+    blocks.push(emitFullRowAttributed(cpLatest, rC, 'ins', 'cp'))
+    blocks.push(emitFullRowAttributed(meCurrent, rM, 'ins', 'me'))
+  } else if (cpRestructured) {
+    blocks.push(emitFullRowAttributed(genesis, rG, 'del', 'cp'))
+    blocks.push(emitFullRowAttributed(cpLatest, rC, 'ins', 'cp'))
+  } else {
+    blocks.push(emitFullRowAttributed(genesis, rG, 'del', 'me'))
+    blocks.push(emitFullRowAttributed(meCurrent, rM, 'ins', 'me'))
+  }
+  return blocks.join('')
 }
 
 /**

package/test/HtmlDiff.threeWay.spec.ts

@@ -120,11 +120,19 @@ describe('HtmlDiff.executeThreeWay (genesis-spine)', () => {
     })
 
     it('cp matches genesis (only Me changed)', () => {
-      expect(HtmlDiff.executeThreeWay('Hello world', 'Hello world', 'Hello brave world')).toContain("data-author='me'")
+      // Negative assertion is load-bearing: without `not.toContain`
+      // a cp↔me swap inside the genesis-spine merge would still
+      // emit `data-author='cp'` somewhere in the output and the
+      // positive assertion would silently pass.
+      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('me matches genesis (only CP changed)', () => {
-      expect(HtmlDiff.executeThreeWay('Hello world', 'Hello cruel world', 'Hello world')).toContain("data-author='cp'")
+      const out = HtmlDiff.executeThreeWay('Hello world', 'Hello cruel world', 'Hello world')
+      expect(out).toContain("data-author='cp'")
+      expect(out).not.toContain("data-author='me'")
     })
   })
 
@@ -163,10 +171,47 @@ describe('HtmlDiff.executeThreeWay (genesis-spine)', () => {
       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'")
+      // CP matches genesis — any cp attribution would be a mis-merge.
+      expect(without).not.toContain("data-author='cp'")
       expect(withFlag).not.toContain('data-author=')
     })
   })
 
+  describe('stack-balance defence', () => {
+    // The emission walks segments built by `buildSegments`: ins/del
+    // segments go through `insertTag` (which manages the formatting-
+    // tag stack), but equal segments push raw words straight to the
+    // content buffer. When a formatting opener is in a del segment
+    // and its matching closer falls in an equal segment, the stack
+    // entry never gets popped — the emitter used to throw "emission
+    // left 1 unclosed formatting tag(s) on the stack" and crash the
+    // caller. Now it closes the leftover wraps defensively with
+    // `</ins>` so the output stays renderable.
+
+    it('CP inserted a <strong> opener whose closer is matched as equal — does not throw', () => {
+      // Genesis has an orphan closer (`X</strong>`); CP wrapped X in
+      // a fresh `<strong>`. The opener is ins-cp (no genesis match)
+      // but the closer is shared by all three and emits as equal.
+      // The mod-`<ins>` opened on the strong push needs to be closed
+      // somehow; the defensive path emits a trailing `</ins>`.
+      expect(() => HtmlDiff.executeThreeWay('X</strong>', '<strong>X</strong>', 'X</strong>')).not.toThrow()
+    })
+
+    it('CP deleted only the <strong> opener — does not throw', () => {
+      // Symmetric: genesis had `<strong>X</strong>`, CP dropped the
+      // opener but kept the closer. The opener-delete pushes onto
+      // the stack and the closer arrives via an equal segment.
+      expect(() => HtmlDiff.executeThreeWay('<strong>X</strong>', 'X</strong>', '<strong>X</strong>')).not.toThrow()
+    })
+
+    it('produces non-empty output even when the stack is left unbalanced at end', () => {
+      const out = HtmlDiff.executeThreeWay('X</strong>', '<strong>X</strong>', 'X</strong>')
+      // The content is still there, the formatting wraps just close
+      // defensively. Sanity-check the visible content survives.
+      expect(out).toContain('X')
+    })
+  })
+
   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

package/test/HtmlDiff.threeWay.tables.spec.ts

@@ -259,6 +259,47 @@ describe('HtmlDiff.executeThreeWay (tables, genesis-spine)', () => {
       const html = `<table>${rows}</table>`
       expect(HtmlDiff.executeThreeWay(html, html, html)).toBe(html)
     })
+
+    it('cell-count mismatch: CP added a column — CP row content is visible (not silently dropped)', () => {
+      // Regression: the previous fallback in emitPreservedRow emitted
+      // only `del me` + `ins me` for any cell-count mismatch, which
+      // silently destroyed CP's row content whenever CP changed the
+      // cell count. A reader in cp-only mode would see no trace of
+      // CP's added column — a content-loss bug that violates the
+      // "CP's changes always visible" invariant.
+      const out = HtmlDiff.executeThreeWay(
+        '<table><tr><td>a</td><td>b</td></tr></table>',
+        '<table><tr><td>a</td><td>X</td><td>b</td></tr></table>',
+        '<table><tr><td>a</td><td>b</td></tr></table>'
+      )
+      expect(out).toBe(
+        "<table><tr class='diffdel cp' data-author='cp'><td class='diffdel cp' data-author='cp'><del class='diffdel cp' data-author='cp'>a</del></td><td class='diffdel cp' data-author='cp'><del class='diffdel cp' data-author='cp'>b</del></td></tr><tr class='diffins cp' data-author='cp'><td class='diffins cp' data-author='cp'><ins class='diffins cp' data-author='cp'>a</ins></td><td class='diffins cp' data-author='cp'><ins class='diffins cp' data-author='cp'>X</ins></td><td class='diffins cp' data-author='cp'><ins class='diffins cp' data-author='cp'>b</ins></td></tr></table>"
+      )
+    })
+
+    it('cell-count mismatch: Me removed a column — symmetric to the CP case', () => {
+      const out = HtmlDiff.executeThreeWay(
+        '<table><tr><td>a</td><td>b</td></tr></table>',
+        '<table><tr><td>a</td><td>b</td></tr></table>',
+        '<table><tr><td>a</td></tr></table>'
+      )
+      expect(out).toBe(
+        "<table><tr class='diffdel me' data-author='me'><td class='diffdel me' data-author='me'><del class='diffdel me' data-author='me'>a</del></td><td class='diffdel me' data-author='me'><del class='diffdel me' data-author='me'>b</del></td></tr><tr class='diffins me' data-author='me'><td class='diffins me' data-author='me'><ins class='diffins me' data-author='me'>a</ins></td></tr></table>"
+      )
+    })
+
+    it('cell-count mismatch: both sides restructured differently — both ins rows attributed', () => {
+      // Genesis 2 cells, CP 3 cells, Me 4 cells. Neither side keeps
+      // the genesis shape, so both restructures must be visible.
+      const out = HtmlDiff.executeThreeWay(
+        '<table><tr><td>a</td><td>b</td></tr></table>',
+        '<table><tr><td>a</td><td>X</td><td>b</td></tr></table>',
+        '<table><tr><td>a</td><td>b</td><td>Y</td><td>Z</td></tr></table>'
+      )
+      expect(out).toBe(
+        "<table><tr class='diffins cp' data-author='cp'><td class='diffins cp' data-author='cp'><ins class='diffins cp' data-author='cp'>a</ins></td><td class='diffins cp' data-author='cp'><ins class='diffins cp' data-author='cp'>X</ins></td><td class='diffins cp' data-author='cp'><ins class='diffins cp' data-author='cp'>b</ins></td></tr><tr class='diffins me' data-author='me'><td class='diffins me' data-author='me'><ins class='diffins me' data-author='me'>a</ins></td><td class='diffins me' data-author='me'><ins class='diffins me' data-author='me'>b</ins></td><td class='diffins me' data-author='me'><ins class='diffins me' data-author='me'>Y</ins></td><td class='diffins me' data-author='me'><ins class='diffins me' data-author='me'>Z</ins></td></tr></table>"
+      )
+    })
   })
 
   describe('nested tables', () => {
@@ -270,6 +311,9 @@ describe('HtmlDiff.executeThreeWay (tables, genesis-spine)', () => {
       )
       expect(out).toMatch(/<del[^>]*data-author='cp'[^>]*>inner<\/del>/)
       expect(out).toMatch(/<ins[^>]*data-author='cp'[^>]*>INNER<\/ins>/)
+      // me == genesis here, so any me attribution would indicate a
+      // cp↔me swap inside the table-cell merge.
+      expect(out).not.toContain("data-author='me'")
       expect(out.startsWith('<table><tr><td><table>')).toBe(true)
       expect(out.endsWith('</table></td></tr></table>')).toBe(true)
     })
@@ -298,4 +342,34 @@ describe('HtmlDiff.executeThreeWay (tables, genesis-spine)', () => {
       expect(HtmlDiff.executeThreeWay('<p>a</p>', '<p>a</p>', '<p>a</p>')).toBe('<p>a</p>')
     })
   })
+
+  describe('positional pairing under moderate dissimilarity', () => {
+    it('column rename + value rewrite still routes through cell-level diff (not whole-table del+ins)', () => {
+      // Real-world regression: cp renamed a column ("Form/Document/Certificate"
+      // → "Extra column") and replaced the values in that column with short
+      // tokens. Word-level Jaccard between the genesis table and cp's edited
+      // table drops to ~0.38 — under the 0.5 threshold the three-way path
+      // used to take, which kicked the diff into multi-table content-LCS
+      // and produced whole-table del+ins (the cp's CP-bubble showed the
+      // entire old table struck through and the entire new table inserted).
+      // 2-way had no such guard and produced a cell-level diff for the same
+      // inputs; lowering the 3-way threshold brings the two paths in step.
+      const genesis =
+        '<table><tr><td>A</td><td>Form/Document/Certificate</td><td>Date</td></tr><tr><td>Party A</td><td>IRS W-8</td><td>On execution</td></tr></table>'
+      const cp =
+        '<table><tr><td>A</td><td>Extra column</td><td>Date</td></tr><tr><td>Party A</td><td>Yes</td><td>On execution</td></tr></table>'
+      const me = genesis
+      const out = HtmlDiff.executeThreeWay(genesis, cp, me)
+      // Expect cell-level cp attribution INSIDE the table cells, NOT a
+      // whole-table del+ins wrapping the entire <table>.
+      expect(out).not.toMatch(/<del[^>]*><table/)
+      expect(out).toMatch(/data-author='cp'/)
+      // me === genesis, so any me-attribution markers would mean the
+      // diff swapped CP's edits onto Me. Negative assertion locks the
+      // attribution direction.
+      expect(out).not.toContain("data-author='me'")
+      expect(out).toContain('Extra column')
+      expect(out).toContain('Form/Document/Certificate')
+    })
+  })
 })

package/test/Utils.spec.ts

@@ -138,10 +138,10 @@ describe('Utils', () => {
     it('combines extraClasses and dataAttrs in one call', () => {
       expect(
         Utils.wrapText('hello', 'del', 'diffdel', {
-          extraClasses: 'me rejects-cp',
-          dataAttrs: { author: 'me', rejects: 'cp' },
+          extraClasses: 'me',
+          dataAttrs: { author: 'me', source: 'edit' },
         })
-      ).toBe("<del class='diffdel me rejects-cp' data-author='me' data-rejects='cp'>hello</del>")
+      ).toBe("<del class='diffdel me' data-author='me' data-source='edit'>hello</del>")
     })
 
     it('skips the metadata path entirely when neither extraClasses nor dataAttrs is set', () => {