@createiq/htmldiff 1.1.0 → 1.2.0-beta.1

package/package.json

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

package/src/Alignment.ts

@@ -0,0 +1,349 @@
+/**
+ * Generic sequence-alignment primitives used by the table-aware diff and
+ * potentially other granularities (rows, cells, list items, …). Nothing
+ * here knows about tables or HTML — the caller passes string keys for
+ * exact matching and a similarity callback for fuzzy pairing.
+ */
+
+export interface Alignment {
+  oldIdx: number | null
+  newIdx: number | null
+}
+
+/**
+ * Standard LCS alignment: walks both sequences and emits a list of pairs
+ * where `(oldIdx, newIdx)` are both set for matching positions, and one
+ * side is null for an unmatched entry on the other side. Equality uses
+ * strict ===.
+ */
+export function lcsAlign(oldKeys: string[], newKeys: string[]): Alignment[] {
+  const m = oldKeys.length
+  const n = newKeys.length
+  const dp: number[][] = Array.from({ length: m + 1 }, () => new Array<number>(n + 1).fill(0))
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      if (oldKeys[i - 1] === newKeys[j - 1]) {
+        dp[i][j] = dp[i - 1][j - 1] + 1
+      } else {
+        dp[i][j] = Math.max(dp[i - 1][j], dp[i][j - 1])
+      }
+    }
+  }
+
+  // Backtrack and push; reverse at the end. `unshift` is O(n) per call
+  // so the naive version was O(n²); push+reverse is O(n) total.
+  const result: Alignment[] = []
+  let i = m
+  let j = n
+  while (i > 0 || j > 0) {
+    if (i > 0 && j > 0 && oldKeys[i - 1] === newKeys[j - 1]) {
+      result.push({ oldIdx: i - 1, newIdx: j - 1 })
+      i--
+      j--
+    } else if (j > 0 && (i === 0 || dp[i][j - 1] >= dp[i - 1][j])) {
+      result.push({ oldIdx: null, newIdx: j - 1 })
+      j--
+    } else {
+      result.push({ oldIdx: i - 1, newIdx: null })
+      i--
+    }
+  }
+  result.reverse()
+  return result
+}
+
+/**
+ * Given a shorter sequence (M items) and a longer sequence (N items, with
+ * N > M), find the K = N - M positions in the longer sequence that should
+ * be "skipped" so the unskipped longer items, aligned positionally with
+ * the shorter items, maximise the sum of pairwise similarity.
+ *
+ * Solves the same problem as enumerating C(N, K) skip combinations and
+ * picking the highest-scoring one, but in O(M × N) time via DP:
+ *
+ *   f(i, j) = max similarity from consuming i shorter and j longer items
+ *             (defined for j >= i; entries below the diagonal are never
+ *              written or read).
+ *   f(0, j) = 0
+ *   f(i, j) = max(
+ *     f(i-1, j-1) + similarity(i-1, j-1),  // pair
+ *     f(i,   j-1)                          // skip longer[j-1]
+ *   )
+ *
+ * Tie-breaking prefers pairing over skipping, so ties resolve to skipping
+ * EARLIER positions — matching the lex-first-combo behaviour of a full
+ * combinatorial enumeration over which K positions to skip. Backtrack
+ * re-asks the fill's pair-vs-skip question to preserve this direction
+ * (the alternative — a `dp[i][j] > dp[i][j-1]` shortcut — would invert
+ * the tie-breaking).
+ *
+ * Caller responsibility: ensure `longerTexts.length >= shorterTexts.length`.
+ */
+export function findOptimalAlignmentSkips(
+  shorterTexts: string[],
+  longerTexts: string[],
+  similarity: (shorterIdx: number, longerIdx: number) => number
+): number[] {
+  const m = shorterTexts.length
+  const n = longerTexts.length
+  // dp[i][j] is valid only for j >= i; entries below the diagonal are
+  // allocated (uniform-shaped matrix keeps the indexing straight) but
+  // never written or read. The wasted (M choose 2)-ish cells are not
+  // worth "optimising" — a triangular layout would complicate the
+  // backtrack's `dp[i][j-1]` reads and the (j > i ? skip : NEG_INF)
+  // boundary handling, with no measurable win at the sizes this runs
+  // on (capped by MAX_COLUMN_SEARCH_WIDTH).
+  const dp: number[][] = Array.from({ length: m + 1 }, () => new Array<number>(n + 1).fill(0))
+  for (let i = 1; i <= m; i++) {
+    for (let j = i; j <= n; j++) {
+      const pair = dp[i - 1][j - 1] + similarity(i - 1, j - 1)
+      const skip = j > i ? dp[i][j - 1] : Number.NEGATIVE_INFINITY
+      dp[i][j] = pair >= skip ? pair : skip
+    }
+  }
+
+  // Backtrack from (m, n). To preserve the fill's "prefer pair on ties"
+  // direction we have to ask the same question the fill asked:
+  //   pair = dp[i-1][j-1] + similarity(i-1, j-1)
+  //   skip = dp[i][j-1]
+  // and choose pair iff pair >= skip. A `dp[i][j] > dp[i][j-1]` shortcut
+  // would invert the tie-breaking (it'd skip earlier positions on ties)
+  // and shift outputs for score-tied scenarios — see the
+  // `column-position search — score-tied inputs` regression tests in
+  // `HtmlDiff.tables.spec.ts`. The extra similarity calls during
+  // backtrack run O(M+N) times total, dwarfed by the O(M × N) fill.
+  const skipped: number[] = []
+  let i = m
+  let j = n
+  while (j > 0) {
+    if (i === 0) {
+      skipped.push(j - 1)
+      j--
+      continue
+    }
+    if (j === i) {
+      // No slack left — every remaining move is a pair.
+      i--
+      j--
+      continue
+    }
+    const pair = dp[i - 1][j - 1] + similarity(i - 1, j - 1)
+    const skip = dp[i][j - 1]
+    if (pair >= skip) {
+      i--
+      j--
+    } else {
+      skipped.push(j - 1)
+      j--
+    }
+  }
+  skipped.reverse()
+  return skipped
+}
+
+/**
+ * Identifies pairings inside each unmatched-only run, then builds the
+ * output alignment by walking the original and substituting paired
+ * entries at the *ins position* (not the del position). This keeps the
+ * result monotonically non-decreasing in newIdx — required by any
+ * downstream emission that walks the new sequence in order. Emitting at
+ * the del position would be safe when del<ins in the alignment array
+ * (the typical case), but can violate monotonicity when unpaired
+ * entries interleave with paired ones in the same run.
+ *
+ * Greedy assignment: the first del in document order wins its best ins.
+ * Suboptimal vs Hungarian on edge cases (two dels above threshold for
+ * the same ins), but bounded — a losing del just emits as a full delete
+ * rather than a content edit.
+ */
+export function pairSimilarUnmatched(
+  alignment: Alignment[],
+  threshold: number,
+  similarity: (oldIdx: number, newIdx: number) => number
+): Alignment[] {
+  const pairs = new Map<number, number>() // del-alignment-idx → ins-alignment-idx
+  let i = 0
+  while (i < alignment.length) {
+    if (alignment[i].oldIdx !== null && alignment[i].newIdx !== null) {
+      i++
+      continue
+    }
+    const runStart = i
+    while (i < alignment.length && (alignment[i].oldIdx === null) !== (alignment[i].newIdx === null)) i++
+    const runEnd = i
+
+    const delIndices: number[] = []
+    const insIndices: number[] = []
+    for (let k = runStart; k < runEnd; k++) {
+      if (alignment[k].oldIdx !== null) delIndices.push(k)
+      else insIndices.push(k)
+    }
+
+    const usedIns = new Set<number>()
+    for (const di of delIndices) {
+      let bestIi = -1
+      let bestSim = threshold
+      for (const ii of insIndices) {
+        if (usedIns.has(ii)) continue
+        const sim = similarity(alignment[di].oldIdx as number, alignment[ii].newIdx as number)
+        if (sim > bestSim) {
+          bestSim = sim
+          bestIi = ii
+        }
+      }
+      if (bestIi >= 0) {
+        pairs.set(di, bestIi)
+        usedIns.add(bestIi)
+      }
+    }
+  }
+
+  const insToDel = new Map<number, number>() // ins-alignment-idx → del-alignment-idx
+  for (const [delAi, insAi] of pairs) insToDel.set(insAi, delAi)
+  const pairedDels = new Set<number>(pairs.keys())
+
+  const result: Alignment[] = []
+  for (let k = 0; k < alignment.length; k++) {
+    if (pairedDels.has(k)) continue // paired del — emitted when we reach its ins
+    if (insToDel.has(k)) {
+      const delAi = insToDel.get(k) as number
+      result.push({ oldIdx: alignment[delAi].oldIdx, newIdx: alignment[k].newIdx })
+    } else {
+      result.push(alignment[k])
+    }
+  }
+  return result
+}
+
+/**
+ * Reorders the alignment so a cursor-based emission walking the new
+ * sequence in order produces entries in their visually-correct
+ * position. Each entry is assigned a fractional "position" in new's
+ * flow:
+ *
+ *   • Preserved/paired (oldIdx, newIdx): position = newIdx.
+ *   • Pure insert (null, newIdx): position = newIdx.
+ *   • Pure delete (oldIdx, null): position = newIdx-of-preserved-just-
+ *     before-this-oldIdx + 0.5. Dels at the same gap sort by oldIdx so
+ *     they appear in old's source order. The +0.5 places dels BEFORE
+ *     any insert at the same gap (insert at newIdx N1+1 has position
+ *     N1+1 which is > N1+0.5), giving the natural "delete first, insert
+ *     second" reading order at a replaced position.
+ *
+ * Handles the full range:
+ *   • Run of unpaired dels at the start (no preserved predecessor):
+ *     position -0.5, sorted by oldIdx.
+ *   • Dels in the middle: positioned right after their preceding
+ *     preserved entry.
+ *   • Dels at the end (no preserved successor): positioned after the
+ *     last preserved entry.
+ *
+ * Without this reordering, a run of unpaired deletes ahead of any
+ * preserved entry would be emitted before the first preserved entry,
+ * regardless of where they originated in old.
+ *
+ * NB: `0.5` is the ONLY fractional offset used. If another decoration
+ * kind ever needs a fractional position too, redesign this scheme
+ * (e.g. a discrete `(integerSlot, kind, secondary)` triple) rather than
+ * picking another magic offset and hoping it doesn't collide.
+ */
+export function orderAlignmentForEmission(alignment: Alignment[]): Alignment[] {
+  const preserved: Array<{ oldIdx: number; newIdx: number }> = []
+  for (const a of alignment) {
+    if (a.oldIdx !== null && a.newIdx !== null) {
+      preserved.push({ oldIdx: a.oldIdx, newIdx: a.newIdx })
+    }
+  }
+  preserved.sort((a, b) => a.oldIdx - b.oldIdx)
+
+  // For a deleted entry with oldIdx K, return the newIdx of the preserved
+  // entry with the largest oldIdx less than K, or -1 if none.
+  function newIdxOfPreservedBefore(oldIdx: number): number {
+    let result = -1
+    for (const p of preserved) {
+      if (p.oldIdx >= oldIdx) break
+      result = p.newIdx
+    }
+    return result
+  }
+
+  // Decorate each alignment with a fractional position. We use
+  // (primary, secondary) tuples so dels at the same gap sort by oldIdx
+  // (in old's source order) and inserts at the same newIdx stay stable.
+  const decorated = alignment.map((a, i) => {
+    let primary: number
+    let secondary: number
+    if (a.newIdx !== null) {
+      primary = a.newIdx
+      secondary = a.oldIdx === null ? 1 : 0 // preserved before pure-insert at same newIdx (rare)
+    } else {
+      // Pure delete
+      primary = newIdxOfPreservedBefore(a.oldIdx as number) + 0.5
+      secondary = a.oldIdx as number
+    }
+    return { entry: a, primary, secondary, originalIdx: i }
+  })
+
+  decorated.sort((a, b) => {
+    if (a.primary !== b.primary) return a.primary - b.primary
+    if (a.secondary !== b.secondary) return a.secondary - b.secondary
+    return a.originalIdx - b.originalIdx // stable
+  })
+
+  return decorated.map(d => d.entry)
+}
+
+/**
+ * Combined similarity metric used for fuzzy pairing. Returns the MAX of
+ * two complementary metrics:
+ *
+ *   1. **Character prefix+suffix similarity** — fraction of the longer
+ *      string covered by shared prefix + shared suffix. Catches small
+ *      edits in the middle of a string (one word changed). Misses cases
+ *      where the bulk of common content is in the middle and the ends
+ *      differ.
+ *
+ *   2. **Token Jaccard similarity** — intersection-over-union of the
+ *      whitespace-split tokens. Catches "most of the content is the
+ *      same but bookended by different bits" — e.g. an edit where the
+ *      ~50 chars in the middle that DO match would be invisible to
+ *      prefix+suffix.
+ *
+ * Either metric exceeding the threshold means pair. Neither alone is
+ * sufficient for the full range of legal-doc edits we see in
+ * production tables.
+ */
+export function textSimilarity(a: string, b: string): number {
+  if (a === b) return 1
+  if (a.length === 0 || b.length === 0) return 0
+  return Math.max(charPrefixSuffixSimilarity(a, b), tokenJaccardSimilarity(a, b))
+}
+
+function charPrefixSuffixSimilarity(a: string, b: string): number {
+  let prefix = 0
+  const minLen = Math.min(a.length, b.length)
+  while (prefix < minLen && a[prefix] === b[prefix]) prefix++
+
+  let suffix = 0
+  while (
+    suffix < a.length - prefix &&
+    suffix < b.length - prefix &&
+    a[a.length - 1 - suffix] === b[b.length - 1 - suffix]
+  ) {
+    suffix++
+  }
+
+  return (prefix + suffix) / Math.max(a.length, b.length)
+}
+
+function tokenJaccardSimilarity(a: string, b: string): number {
+  const tokensA = new Set(a.split(/\s+/).filter(Boolean))
+  const tokensB = new Set(b.split(/\s+/).filter(Boolean))
+  if (tokensA.size === 0 && tokensB.size === 0) return 1
+  let intersection = 0
+  for (const t of tokensA) {
+    if (tokensB.has(t)) intersection++
+  }
+  const union = tokensA.size + tokensB.size - intersection
+  return union === 0 ? 0 : intersection / union
+}