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

package/package.json

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

package/src/HtmlDiff.ts

@@ -162,7 +162,22 @@ export default class HtmlDiff {
   // constructor overload that would re-leak the parameter we just hid.
   private tablePreprocessDepth = 0
 
-  private specialTagDiffStack: string[] = []
+  /**
+   * Tracks currently-open formatting-tag wraps. Each entry pairs the
+   * opening tag (so a later closing tag can find its match) with the
+   * styling info needed to RE-OPEN the wrap if an overlapping
+   * formatting-tag close forces it to split. Without the styling info,
+   * an overlap like `<strong>X</strong>` ↔ `<u>X</u>` produces an
+   * unclosable wrap (the closing tag for the outer wrap arrives while
+   * an inner wrap is still on the stack); see `insertTag`'s closing
+   * handler for the split logic.
+   */
+  private specialTagDiffStack: Array<{
+    tag: string
+    styledTagNames: string
+    cssClass: string
+    metadata: WrapMetadata | undefined
+  }> = []
   private newWords: string[] = []
   private oldWords: string[] = []
   /**
@@ -827,8 +842,13 @@ export default class HtmlDiff {
       // if there are nonTags, the index of the last tag is the index before the first nonTag.
       const indexLastTagInFirstTagBlock = indexOfFirstNonTag === -1 ? words.length - 1 : indexOfFirstNonTag - 1
 
-      let specialCaseTagInjection = ''
-      let specialCaseTagInjectionIsBefore = false
+      // Pre-injection sits BEFORE the extracted tag-block content (used
+      // by closing tags so `</ins></strong>` reads left-to-right).
+      // Post-injection sits AFTER (used by opening tags so the rendered
+      // order is `<strong><ins ...>` and by the overlap-split case so
+      // the re-opened `<ins>`s sit AFTER the actual closing tag).
+      let preInject = ''
+      let postInject = ''
 
       // handle opening tag
       if (HtmlDiff.SpecialCaseOpeningTagRegex.test(words[0])) {
@@ -840,10 +860,11 @@ export default class HtmlDiff {
         }
         const styledTagNames = Array.from(tagNames).join(' ')
 
-        this.specialTagDiffStack.push(words[0])
         // Carry the caller's metadata into the formatting-tag wrapper so
         // a 3-way author tag survives a `<strong>`/`<em>` content edit.
-        specialCaseTagInjection = `<ins${Utils.composeTagAttributes(`mod ${styledTagNames}`, metadata ?? {})}>`
+        const styledCssClass = `mod ${styledTagNames}`
+        this.specialTagDiffStack.push({ tag: words[0], styledTagNames, cssClass: styledCssClass, metadata })
+        postInject = `<ins${Utils.composeTagAttributes(styledCssClass, metadata ?? {})}>`
         if (tag === HtmlDiff.DelTag) {
           words.shift()
 
@@ -855,7 +876,6 @@ export default class HtmlDiff {
       }
       // handle closing tag
       else if (HtmlDiff.SpecialCaseClosingTagsSet.has(words[0].toLowerCase())) {
-        const openingTag = this.specialTagDiffStack.length === 0 ? null : this.specialTagDiffStack.pop()
         // For delete operations: when the tag block contains a mix of formatting and
         // non-formatting closing tags (e.g. </strong></div>), compare against the first
         // closing tag (the formatting one) rather than the last tag in the block.
@@ -870,19 +890,39 @@ export default class HtmlDiff {
             tagIndexToCompare = 0
           }
         }
-        const openingAndClosingTagsMatch =
-          !!openingTag && Utils.getTagName(openingTag) === Utils.getTagName(words[tagIndexToCompare])
 
-        if (openingTag && openingAndClosingTagsMatch) {
-          specialCaseTagInjection = '</ins>'
-          specialCaseTagInjectionIsBefore = true
+        // Search the stack for a matching opener (LIFO). When the match
+        // is the top entry, this is the normal balanced case and we
+        // emit a single `</ins>` before the closing tag. When the match
+        // is below an unmatched opener — i.e. another formatting wrap
+        // opened after it but hasn't been closed yet — the wraps
+        // overlap in source order, which has no valid LIFO HTML
+        // expression. Resolve by SPLITTING the wraps: close everything
+        // above the match (their `<ins>`s and the match's `<ins>`), then
+        // re-open the above wraps with fresh `<ins>` tags AFTER the
+        // closing tag emits. The above wraps continue to apply until
+        // their own closing tag arrives.
+        const closingTagName = Utils.getTagName(words[tagIndexToCompare])
+        let matchIdx = -1
+        for (let i = this.specialTagDiffStack.length - 1; i >= 0; i--) {
+          if (Utils.getTagName(this.specialTagDiffStack[i].tag) === closingTagName) {
+            matchIdx = i
+            break
+          }
         }
 
-        // if the tag has a corresponding opening tag, but they don't match,
-        // we need to push the opening tag back onto the stack
-        else if (openingTag) {
-          this.specialTagDiffStack.push(openingTag)
+        if (matchIdx >= 0) {
+          const aboveEntries = this.specialTagDiffStack.splice(matchIdx + 1)
+          this.specialTagDiffStack.pop() // pop the matched entry
+          // One `</ins>` per above entry, then one for the match itself.
+          preInject = '</ins>'.repeat(aboveEntries.length + 1)
+          for (const entry of aboveEntries) {
+            postInject += `<ins${Utils.composeTagAttributes(entry.cssClass, entry.metadata ?? {})}>`
+            this.specialTagDiffStack.push(entry) // their wrap continues via the new <ins>
+          }
         }
+        // No match in stack — orphan closing tag, drop the `<ins>` work
+        // and just let the tag itself flow through extractConsecutiveWords.
 
         if (tag === HtmlDiff.DelTag) {
           words.shift()
@@ -893,7 +933,7 @@ export default class HtmlDiff {
         }
       }
 
-      if (words.length === 0 && specialCaseTagInjection.length === 0) {
+      if (words.length === 0 && preInject.length === 0 && postInject.length === 0) {
         break
       }
 
@@ -909,11 +949,7 @@ export default class HtmlDiff {
               !HtmlDiff.SpecialCaseClosingTagsSet.has(x.toLowerCase())
           : Utils.isTag
 
-      if (specialCaseTagInjectionIsBefore) {
-        this.content.push(specialCaseTagInjection + this.extractConsecutiveWords(words, isTagForExtraction).join(''))
-      } else {
-        this.content.push(this.extractConsecutiveWords(words, isTagForExtraction).join('') + specialCaseTagInjection)
-      }
+      this.content.push(preInject + this.extractConsecutiveWords(words, isTagForExtraction).join('') + postInject)
 
       if (words.length === 0) continue
 

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,

package/test/HtmlDiff.spec.ts

@@ -48,6 +48,21 @@ describe('HtmlDiff', () => {
       'Some formatted text',
       "Some <ins class='mod strong i'>formatted</ins> text",
     ],
+    // Overlapping formatting wraps — old wraps a word in <strong>, new wraps the same
+    // word in <u>. The wraps cross (mod-strong opens before mod-u, but the </strong>
+    // closing arrives before </u>), so emission must split the inner wrap to keep
+    // HTML well-formed. Regression: previously left mod-strong unclosed and the
+    // 3-way path threw on the unbalanced stack.
+    [
+      '<strong>three</strong>',
+      '<u>three</u>',
+      "<ins class='mod strong'><u><ins class='mod u'>three</ins></ins><ins class='mod u'></ins></u>",
+    ],
+    [
+      'a <strong>three</strong> b',
+      'a <u>three</u> b',
+      "a <ins class='mod strong'><u><ins class='mod u'>three</ins></ins><ins class='mod u'></ins></u> b",
+    ],
     [
       '<table><tr><td>col1</td><td>col2</td></tr><tr><td>Data 1</td><td>Data 2</td></tr></table>',
       '<table><tr><td>col1</td><td>col2</td></tr></table>',

package/test/HtmlDiff.threeWay.spec.ts

@@ -144,6 +144,17 @@ describe('HtmlDiff.executeThreeWay (genesis-spine)', () => {
       expect(out).toMatch(/<p>First paragraph.*data-author='cp'.*<\/p>/)
       expect(out).toMatch(/<p>Second paragraph.*data-author='me'.*<\/p>/)
     })
+
+    it('overlapping formatting wraps from each author do not unbalance the emission stack', () => {
+      // Genesis: plain "three". CP wrapped it in <strong>, Me in <u>. The
+      // mod-strong (cp) and mod-u (me) wraps cross: <strong> opens before
+      // <u>, but </strong> arrives before </u>. The emitter must split
+      // the inner wrap so the output stays well-formed instead of
+      // throwing an unbalanced-stack error.
+      expect(HtmlDiff.executeThreeWay('three', '<strong>three</strong>', '<u>three</u>')).toBe(
+        "<strong><ins class='mod strong cp' data-author='cp'><u><ins class='mod u me' data-author='me'>three</ins></ins></strong><ins class='mod u me' data-author='me'></ins></u>"
+      )
+    })
   })
 
   describe('options pass-through', () => {

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

@@ -298,4 +298,30 @@ 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'/)
+      expect(out).toContain('Extra column')
+      expect(out).toContain('Form/Document/Certificate')
+    })
+  })
 })