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

package/package.json

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

package/src/HtmlDiff.ts

@@ -249,8 +249,20 @@ export default class HtmlDiff {
     this.newText = newText
   }
 
-  static execute(oldText: string, newText: string): string {
-    return new HtmlDiff(oldText, newText).build()
+  static execute(oldText: string, newText: string, options: AnalyzeOptions = {}): string {
+    const inner = new HtmlDiff(oldText, newText)
+    if (options.blockExpressions) {
+      for (const expr of options.blockExpressions) inner.addBlockExpression(expr)
+    }
+    if (options.repeatingWordsAccuracy !== undefined) inner.repeatingWordsAccuracy = options.repeatingWordsAccuracy
+    if (options.orphanMatchThreshold !== undefined) inner.orphanMatchThreshold = options.orphanMatchThreshold
+    if (options.ignoreWhitespaceDifferences !== undefined) {
+      inner.ignoreWhitespaceDifferences = options.ignoreWhitespaceDifferences
+    }
+    // `useProjections` is intentionally NOT plumbed here — the 2-way
+    // path's build() runs its own heuristic. Pass via `analyze` if a
+    // caller needs to force it.
+    return inner.build()
   }
 
   /**

package/src/ThreeWayTable.ts

@@ -1,4 +1,4 @@
-import { lcsAlign, textSimilarity } from './Alignment'
+import { type Alignment, lcsAlign, pairSimilarUnmatched, textSimilarity } from './Alignment'
 import { injectClass, parseOpeningTagAt } from './HtmlScanner'
 import {
   type CellRange,
@@ -8,6 +8,7 @@ import {
   PLACEHOLDER_SUFFIX,
   type RowRange,
   rowKey,
+  rowText,
   sameDimensions,
   spliceString,
   type TableRange,
@@ -143,8 +144,14 @@ function preprocessByContent(
   const cKeys = cTables.map(t => tableKey(cpLatest, t))
   const mKeys = mTables.map(t => tableKey(meCurrent, t))
 
-  const alignCp = lcsAlign(gKeys, cKeys)
-  const alignMe = lcsAlign(gKeys, mKeys)
+  // Exact tableKey LCS, then fuzzy-pair unmatched runs by content
+  // similarity. Without this, a table whose cells were edited (but
+  // not its overall shape) fails the exact tableKey match and the
+  // table-level aligner pulls it apart into a whole-table del + a
+  // whole-table ins. Same fuzzy pass `TableDiff` uses for the 2-way
+  // path — `pairSimilarTablesThreeWay` is defined below.
+  const alignCp = pairSimilarTablesThreeWay(lcsAlign(gKeys, cKeys), genesis, cpLatest, gTables, cTables)
+  const alignMe = pairSimilarTablesThreeWay(lcsAlign(gKeys, mKeys), genesis, meCurrent, gTables, mTables)
 
   // Maps: genesisIdx → matching cpIdx (-1 if none); cpIdx → matching genesisIdx; etc.
   const gToCp = new Array<number>(gTables.length).fill(-1)
@@ -342,6 +349,76 @@ function tableKey(html: string, table: TableRange): string {
   return html.slice(table.tableStart, table.tableEnd).replace(/\s+/g, ' ').trim()
 }
 
+/**
+ * Character-level similarity above which the three-way aligner treats
+ * two rows / tables as "the same logical entry, edited" rather than
+ * an unrelated delete + insert. Matched to TableDiff's
+ * `ROW_FUZZY_THRESHOLD` / `CELL_FUZZY_THRESHOLD` so 2-way and 3-way
+ * agree on which pairings are reachable; if a row's content overlap
+ * is enough to fool the 2-way diff into pairing, it should also be
+ * enough for 3-way.
+ */
+const THREE_WAY_FUZZY_THRESHOLD = 0.5
+
+/**
+ * Run the same fuzzy-pairing pass `TableDiff.pairSimilarUnmatchedRows`
+ * applies after its exact-LCS, but against one side of the genesis
+ * spine (either cp or me). The genesis tables/rows are always the
+ * "old" side; `newTable` is the cp or me table being aligned. Returns
+ * the enriched alignment with additional paired entries.
+ *
+ * Cell-count guard: only fuzzy-pair when both rows have the same cell
+ * count. Without this guard an asymmetric restructure — e.g. CP and
+ * Me both added a different column — leads to ONE side fuzzy-pairing
+ * its row with genesis (content overlap above threshold) while the
+ * other side falls below threshold. That mismatch routes through
+ * `diffTableStructural`'s "Me dropped, CP kept" (or the mirror)
+ * branch, which emits CP's row as a Me-attributed deletion. In
+ * cp-only mode `stripMeAttributedMarkers` then removes the row
+ * entirely and CP's edit vanishes from the view — exactly the
+ * content-loss case we're meant to prevent. Restricting fuzzy
+ * pairing to same-shape rows preserves the common case (single cell
+ * edit, identical row shape) while pushing structural mismatches
+ * back to the boundary-insertion path that emits both sides
+ * explicitly.
+ */
+function pairSimilarRowsThreeWay(
+  alignment: Alignment[],
+  genesis: string,
+  newHtml: string,
+  oldTable: TableRange,
+  newTable: TableRange
+): Alignment[] {
+  const oldTexts = oldTable.rows.map(r => rowText(genesis, r))
+  const newTexts = newTable.rows.map(r => rowText(newHtml, r))
+  return pairSimilarUnmatched(alignment, THREE_WAY_FUZZY_THRESHOLD, (oldIdx, newIdx) => {
+    if (oldTable.rows[oldIdx].cells.length !== newTable.rows[newIdx].cells.length) return 0
+    return textSimilarity(oldTexts[oldIdx], newTexts[newIdx])
+  })
+}
+
+/**
+ * Table-level counterpart: after `lcsAlign(gKeys, otherKeys)` over
+ * full table HTML keys, fuzzy-pair unmatched table runs by their
+ * row-text-concatenated content. Without this, a table whose body
+ * was edited (but not its outer shape) fails the exact-key match
+ * and the preprocessing emits whole-table del + whole-table ins
+ * instead of recursing into per-cell three-way diffs.
+ */
+function pairSimilarTablesThreeWay(
+  alignment: Alignment[],
+  oldHtml: string,
+  newHtml: string,
+  oldTables: TableRange[],
+  newTables: TableRange[]
+): Alignment[] {
+  const oldTexts = oldTables.map(t => t.rows.map(r => rowText(oldHtml, r)).join(' '))
+  const newTexts = newTables.map(t => t.rows.map(r => rowText(newHtml, r)).join(' '))
+  return pairSimilarUnmatched(alignment, THREE_WAY_FUZZY_THRESHOLD, (oldIdx, newIdx) =>
+    textSimilarity(oldTexts[oldIdx], newTexts[newIdx])
+  )
+}
+
 // ────────────────────────────────────────────────────────────────────────────
 // Per-table diff: positional cells or row-level structural change.
 
@@ -426,8 +503,17 @@ function diffTableStructural(
   const cKeys = tC.rows.map(r => rowKey(cpLatest, r))
   const mKeys = tM.rows.map(r => rowKey(meCurrent, r))
 
-  const alignCp = lcsAlign(gKeys, cKeys)
-  const alignMe = lcsAlign(gKeys, mKeys)
+  // Exact LCS first, then fuzzy-pair remaining unmatched runs. Without
+  // the fuzzy pass, a row where CP edited just a single cell's text
+  // produces no key match — the row aligner emits the genesis row as
+  // CP-deleted AND CP's reshaped row as inserted, when a cell-level
+  // diff against the paired row would render the edit far more
+  // legibly. The 2-way path (`TableDiff.pairSimilarUnmatchedRows`)
+  // has done this since inception; bringing the three-way path in
+  // step removes the asymmetry where the cp-only / all-changes view
+  // looks markedly worse than plain 2-way for ordinary cell edits.
+  const alignCp = pairSimilarRowsThreeWay(lcsAlign(gKeys, cKeys), genesis, cpLatest, tG, tC)
+  const alignMe = pairSimilarRowsThreeWay(lcsAlign(gKeys, mKeys), genesis, meCurrent, tG, tM)
 
   // genesisIdx → matching cpIdx (-1 if cp deleted this row)
   const gToCp = new Array<number>(tG.rows.length).fill(-1)

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

@@ -288,6 +288,34 @@ describe('HtmlDiff.executeThreeWay (tables, genesis-spine)', () => {
       )
     })
 
+    it('CP edited one cell in a row (same shape) — fuzzy-pairs and emits a cell-level diff, not whole-row del+ins', () => {
+      // Regression: the 3-way row aligner only did exact lcsAlign over
+      // rowKey, so a row where CP edited a single cell's text produced
+      // no key match and the algorithm split the row into a whole-row
+      // delete + whole-row insert. The 2-way path has always run a
+      // fuzzy-pairing pass after lcsAlign; bringing the 3-way path in
+      // step removes the asymmetry where cp-only / all-changes views
+      // looked materially worse than 2-way for ordinary cell edits.
+      //
+      // Same-shape genesis/cp/me; CP edited the middle cell's text.
+      // Me === genesis. Expect a paired row with cell-level cp-ins
+      // markup, NOT two distinct whole-row entries.
+      const out = HtmlDiff.executeThreeWay(
+        '<table><tr><td>Party A</td><td>old details</td><td>kept</td></tr></table>',
+        '<table><tr><td>Party A</td><td>new details</td><td>kept</td></tr></table>',
+        '<table><tr><td>Party A</td><td>old details</td><td>kept</td></tr></table>'
+      )
+      // CP's edit lives inside the row, not as a parallel whole-row
+      // delete-then-insert. Whole-row markers would carry `class='diffdel ...'`
+      // or `class='diffins ...'` on the `<tr>` itself.
+      expect(out).not.toMatch(/<tr [^>]*class=['"]diffdel/)
+      expect(out).not.toMatch(/<tr [^>]*class=['"]diffins/)
+      expect(out).toContain('Party A')
+      expect(out).toContain("data-author='cp'")
+      // Me === genesis so any me attribution would indicate a swap.
+      expect(out).not.toContain("data-author='me'")
+    })
+
     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.