@createiq/htmldiff 1.1.0 → 1.2.0-beta.1

package/src/ThreeWayDiff.ts

@@ -0,0 +1,269 @@
+import Action from './Action'
+import type { AnalyzeResult } from './HtmlDiff'
+import type Operation from './Operation'
+import type { WrapMetadata } from './Utils'
+
+/**
+ * Composes diff(genesis → cp-latest) (CP's accumulated changes from the
+ * common ancestor) and diff(genesis → me-current) (Me's accumulated
+ * changes from the common ancestor) into a single attributed segment
+ * stream. The output is consumed by `HtmlDiff.executeThreeWay` for
+ * emission.
+ *
+ * Genesis is the structural spine. Both pair-wise analyses must
+ * tokenise genesis identically (`HtmlDiff.executeThreeWay` enforces
+ * this via the symmetric-projection decision), so genesis-diff indices
+ * are stable across the two streams.
+ *
+ * Per genesis token: classify by what each side did to it
+ * (kept / deleted) and emit accordingly. Per genesis boundary: collect
+ * each side's insertions and check for agreement — when both sides
+ * inserted identical content, the insertion is treated as "settled"
+ * and emitted unmarked (the reader sees the agreed-on text without
+ * authorship markup, matching Word-style track-changes conventions
+ * where both authors agreeing is silent).
+ *
+ * The emission order at a boundary mirrors the 2-way del-then-ins
+ * convention: a Replace (genesis token deleted + a paired insertion)
+ * reads as `<del>old</del><ins>new</ins>`. Pure insertions are
+ * positioned at their natural boundary.
+ */
+
+export type Author = 'cp' | 'me'
+
+/**
+ * Attribution assigned to each output segment.
+ *
+ * `equal` covers three cases: tokens both authors kept (rendered as the
+ * genesis word), insertion spans both authors made identically (rendered
+ * plain), and structural tags around both-deleted tokens (rendered to
+ * keep layout intact while the content token itself is dropped).
+ * Equal segments carry no markup.
+ */
+export type Attribution = { kind: 'equal' } | { kind: 'ins'; author: Author } | { kind: 'del'; author: Author }
+
+export interface Segment {
+  attr: Attribution
+  /** Tokens to emit. For Equal segments these are original genesis words
+   *  (including structural tags); for ins/del they are diff-space tokens. */
+  words: string[]
+}
+
+/**
+ * Builds the attributed segment stream for a three-way diff.
+ *
+ * @param dCp  analysis of diff(genesis → cp-latest)
+ * @param dMe  analysis of diff(genesis → me-current)
+ *
+ * Both analyses must share the same `oldDiffWords` (the genesis tokens)
+ * — the caller guarantees this by passing the same genesis input and
+ * the same `useProjections` decision to both `HtmlDiff.analyze` calls.
+ */
+export function buildSegments(dCp: AnalyzeResult, dMe: AnalyzeResult): Segment[] {
+  const genesisLen = dCp.oldDiffWords.length
+
+  // Per genesis token: did each author keep it or delete it?
+  const cpFate = buildFateFromGenesis(dCp.operations, genesisLen)
+  const meFate = buildFateFromGenesis(dMe.operations, genesisLen)
+
+  // Per boundary: tokens each author inserted at that boundary. Keyed by
+  // `endInOld` so a Replace's insertion sits AFTER the deleted genesis
+  // token (visual del-then-ins). Pure Insert ops have endInOld ==
+  // startInOld so they land at their natural between-tokens boundary.
+  const cpInsAt = collectInsertionsKeyedByEnd(dCp)
+  const meInsAt = collectInsertionsKeyedByEnd(dMe)
+
+  // Inverse map genesis-diff-index → genesis-original-index. Identity when
+  // no projection. Used to slice the original genesis words for Equal
+  // segments so structural tags pass through verbatim.
+  const diffToOriginal: readonly number[] = dCp.oldContentToOriginal ?? Array.from({ length: genesisLen }, (_, i) => i)
+  const genesisOriginalLen = dCp.oldOriginalWords.length
+
+  const segments: Segment[] = []
+  let originalCursor = 0
+
+  // Boundary 0 — pure insertions BEFORE genesis[0].
+  emitBoundary(0, cpInsAt, meInsAt, dCp.newDiffWords, dMe.newDiffWords, segments)
+
+  for (let i = 0; i < genesisLen; i++) {
+    const cpDel = cpFate[i] === 'deleted'
+    const meDel = meFate[i] === 'deleted'
+
+    // Pick up structural tags from cursor through to this genesis token's
+    // original index. Same cursor-based slicing as the 2-way path so a
+    // `<p>` opening tag preceding a content token gets attributed with
+    // that token's segment.
+    const origIdx = diffToOriginal[i]
+    const slice = dCp.oldOriginalWords.slice(originalCursor, origIdx + 1)
+    originalCursor = origIdx + 1
+
+    if (!cpDel && !meDel) {
+      // Kept by both — equal. Emit the original-word slice (includes
+      // any leading structural tags).
+      appendSegment(segments, { kind: 'equal' }, slice)
+    } else if (cpDel && meDel) {
+      // Both deleted — settled. Filter at emission time; pass the
+      // structural-tag-bearing slice through as equal so layout
+      // survives. The content token itself is the LAST element of the
+      // slice (since slice ends at origIdx+1); drop only that.
+      // If slice has multiple elements (leading structural tags), they
+      // belong to the surrounding flow and should remain.
+      if (slice.length > 1) {
+        appendSegment(segments, { kind: 'equal' }, slice.slice(0, slice.length - 1))
+      }
+      // The content token itself is silenced.
+    } else if (cpDel) {
+      // CP deleted, Me kept → render as <del cp>. Me's keeping means the
+      // token is still in V_me; the markup tells the reader "CP wanted
+      // this gone, you've kept it."
+      appendSegment(segments, { kind: 'del', author: 'cp' }, slice)
+    } else {
+      // Me deleted, CP kept → render as <del me>.
+      appendSegment(segments, { kind: 'del', author: 'me' }, slice)
+    }
+
+    // Boundary i+1 — pure insertions between genesis[i] and genesis[i+1],
+    // AND replace-insertions paired with genesis[i] (which we just
+    // emitted as a deletion).
+    emitBoundary(i + 1, cpInsAt, meInsAt, dCp.newDiffWords, dMe.newDiffWords, segments)
+  }
+
+  // Trailing original tokens (structural closing tags after the last
+  // content word).
+  if (originalCursor < genesisOriginalLen) {
+    appendSegment(segments, { kind: 'equal' }, dCp.oldOriginalWords.slice(originalCursor))
+  }
+
+  return segments
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+
+type GenesisFate = 'kept' | 'deleted'
+
+/**
+ * Per genesis-diff-index, what did this side do to that token? Both
+ * Delete and Replace ops remove the token from the side's output, so
+ * both contribute `'deleted'`. Equal ops contribute `'kept'`. Insert
+ * ops have an empty old range, so they don't touch the genesis fate
+ * map.
+ */
+function buildFateFromGenesis(ops: readonly Operation[], genesisLen: number): GenesisFate[] {
+  const out: GenesisFate[] = new Array(genesisLen).fill('kept')
+  for (const op of ops) {
+    if (op.action !== Action.Delete && op.action !== Action.Replace) continue
+    for (let i = op.startInOld; i < op.endInOld; i++) {
+      if (i >= 0 && i < genesisLen) out[i] = 'deleted'
+    }
+  }
+  return out
+}
+
+/**
+ * Per genesis boundary `b`, collect tokens this side inserted at that
+ * boundary. Keyed by `endInOld` so a Replace at genesis[k..k+1] has its
+ * insertion at boundary k+1 (after the deleted token) rather than k
+ * (before) — that produces the del-then-ins visual order.
+ *
+ * For pure Insert ops the old range is empty (endInOld == startInOld),
+ * so the key is the same as the semantic between-tokens position.
+ */
+function collectInsertionsKeyedByEnd(d: AnalyzeResult): Map<number, string[]> {
+  const out = new Map<number, string[]>()
+  for (const op of d.operations) {
+    if (op.action !== Action.Insert && op.action !== Action.Replace) continue
+    const words = d.newDiffWords.slice(op.startInNew, op.endInNew)
+    if (words.length === 0) continue
+    const key = op.endInOld
+    const existing = out.get(key) ?? []
+    existing.push(...words)
+    out.set(key, existing)
+  }
+  return out
+}
+
+/**
+ * Emit any insertions at boundary `b`. When both authors inserted at
+ * the same boundary AND the inserted token sequences are textually
+ * identical, the insertion is treated as agreed and emitted unmarked.
+ * Otherwise each side's insertion is emitted with author attribution.
+ *
+ * The CP-then-Me ordering for disagreement is arbitrary but consistent;
+ * callers don't depend on it.
+ */
+function emitBoundary(
+  b: number,
+  cpInsAt: Map<number, string[]>,
+  meInsAt: Map<number, string[]>,
+  _cpDiffWords: readonly string[],
+  _meDiffWords: readonly string[],
+  segments: Segment[]
+) {
+  const cpIns = cpInsAt.get(b)
+  const meIns = meInsAt.get(b)
+  const hasCp = !!cpIns && cpIns.length > 0
+  const hasMe = !!meIns && meIns.length > 0
+  if (!hasCp && !hasMe) return
+
+  if (hasCp && hasMe && tokenArraysEqual(cpIns, meIns)) {
+    // Both authors inserted the same content — settled. Emit unmarked.
+    appendSegment(segments, { kind: 'equal' }, cpIns)
+    return
+  }
+
+  if (hasCp) appendSegment(segments, { kind: 'ins', author: 'cp' }, cpIns)
+  if (hasMe) appendSegment(segments, { kind: 'ins', author: 'me' }, meIns)
+}
+
+function tokenArraysEqual(a: readonly string[], b: readonly string[]): boolean {
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false
+  return true
+}
+
+function appendSegment(segments: Segment[], attr: Attribution, words: readonly string[]) {
+  if (words.length === 0) return
+  const last = segments[segments.length - 1]
+  if (last && sameAttribution(last.attr, attr)) {
+    last.words.push(...words)
+    return
+  }
+  segments.push({ attr, words: [...words] })
+}
+
+function sameAttribution(a: Attribution, b: Attribution): boolean {
+  if (a.kind === 'equal' && b.kind === 'equal') return true
+  if (a.kind === 'ins' && b.kind === 'ins') return a.author === b.author
+  if (a.kind === 'del' && b.kind === 'del') return a.author === b.author
+  return false
+}
+
+/**
+ * Build the `WrapMetadata` for an attribution. Single source of truth
+ * for author-class / data-attr shape so the three emission paths
+ * (word-level, table-level full-row/cell, multi-table whole-table
+ * pre-wrap) stay consistent. A change here propagates to every author
+ * marker in the output.
+ */
+export function authorAttribution(author: Author): WrapMetadata {
+  return { extraClasses: author, dataAttrs: { author } }
+}
+
+/**
+ * Resolve a segment's attribution into the wrapper-tag, base CSS class,
+ * and `WrapMetadata` consumed by `Utils.wrapText` / `insertTag`. The
+ * caller is `HtmlDiff.executeThreeWay`'s emission loop.
+ *
+ * `equal` segments don't go through this — they're emitted unmarked.
+ */
+export function segmentEmissionShape(attr: Exclude<Attribution, { kind: 'equal' }>): {
+  tag: 'ins' | 'del'
+  baseClass: 'diffins' | 'diffdel'
+  metadata: WrapMetadata
+} {
+  return {
+    tag: attr.kind,
+    baseClass: attr.kind === 'ins' ? 'diffins' : 'diffdel',
+    metadata: authorAttribution(attr.author),
+  }
+}