@createiq/htmldiff 1.2.0-beta.0 → 1.2.0-beta.10

package/src/ThreeWayDiff.ts

@@ -1,95 +1,138 @@
 import Action from './Action'
+import { lcsAlign } from './Alignment'
 import type { AnalyzeResult } from './HtmlDiff'
 import type Operation from './Operation'
 import type { WrapMetadata } from './Utils'
 
 /**
- * Composes diff(V1, V2) (CP's changes) and diff(V2, V3) (Me's changes)
- * into a single attributed segment stream. The output is consumed by
- * `HtmlDiff.executeThreeWay` for emission.
+ * 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.
  *
- * V2 is the structural spine. Both pair-wise analyses must tokenise V2
- * identically (`HtmlDiff.executeThreeWay` enforces this via the
- * symmetric-projection decision), so V2-diff indices are stable across
- * the two streams and we can fold them into a single per-V2-token
- * attribution view, interleaved with off-spine CP-deletions (V1-side)
- * and Me-insertions (V3-side).
+ * 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. `reject` is its own kind
- * (rather than a flavour of `del`) so exhaustive switching is safe — no
- * property-presence narrowing required at use sites.
+ * 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 }
-  // Me deleting tokens that CP inserted = rejecting CP's proposal.
-  | { kind: 'reject'; by: 'me'; rejected: 'cp' }
+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 V2 words
+  /** Tokens to emit. For Equal segments these are original genesis words
    *  (including structural tags); for ins/del they are diff-space tokens. */
   words: string[]
 }
 
-export function buildSegments(d1: AnalyzeResult, d2: AnalyzeResult): Segment[] {
-  const v2DiffLen = d1.newDiffWords.length
-  const fromV1 = buildOriginMap(d1.operations, v2DiffLen)
-  const toV3 = buildFateMap(d2.operations, v2DiffLen)
-  const cpDeletionsAt = collectDeletionsAtBoundary(d1)
-  const meInsertionsAt = collectInsertionsAtBoundary(d2)
+/**
+ * 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 V2-diff-index → V2-original-index. Identity when no projection.
-  const diffToOriginal: readonly number[] = d1.newContentToOriginal ?? Array.from({ length: v2DiffLen }, (_, i) => i)
-  const v2OriginalLen = d1.newOriginalWords.length
+  // 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
 
-  for (let i = 0; i < v2DiffLen; i++) {
-    // CP-deletions from V1 land BEFORE the V2 token at this boundary —
-    // they conceptually "preceded" V2[i] in V1's stream.
-    const cpDel = cpDeletionsAt.get(i)
-    if (cpDel?.length) appendSegment(segments, { kind: 'del', author: 'cp' }, cpDel)
+  // Boundary 0 — pure insertions BEFORE genesis[0].
+  emitBoundary(0, cpInsAt, meInsAt, dCp.newDiffWords, dMe.newDiffWords, segments)
 
-    const attr = combine(fromV1[i], toV3[i])
+  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 = d1.newOriginalWords.slice(originalCursor, origIdx + 1)
+    const slice = dCp.oldOriginalWords.slice(originalCursor, origIdx + 1)
     originalCursor = origIdx + 1
 
-    // Me-insertions at this boundary go BEFORE V2[i] for pure
-    // insertions, but AFTER V2[i] when V2[i] is itself a Me-deletion
-    // (i.e. a Me Replace). This mirrors the 2-way del-then-ins
-    // convention so a Replace reads as `<del>X</del><ins>Y</ins>`.
-    const meIns = meInsertionsAt.get(i)
-    const meInsAfterV2 = meIns?.length && isDeletion(attr)
-
-    if (meIns?.length && !meInsAfterV2) {
-      appendSegment(segments, { kind: 'ins', author: 'me' }, meIns)
-    }
-    appendSegment(segments, attr, slice)
-    if (meInsAfterV2) {
-      appendSegment(segments, { kind: 'ins', author: 'me' }, meIns)
+    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)
   }
-  // Tail-end interleavings (CP-del / Me-ins at boundary v2DiffLen — i.e.
-  // after every V2 token). Ordering doesn't matter since there's no
-  // V2 token to anchor around.
-  const tailCpDel = cpDeletionsAt.get(v2DiffLen)
-  if (tailCpDel?.length) appendSegment(segments, { kind: 'del', author: 'cp' }, tailCpDel)
-  const tailMeIns = meInsertionsAt.get(v2DiffLen)
-  if (tailMeIns?.length) appendSegment(segments, { kind: 'ins', author: 'me' }, tailMeIns)
-
-  // Trailing V2-original tokens (structural closing tags after the last
-  // content word). Emit as equal — there's no following segment to claim
-  // them, and attributing them to either author would be arbitrary.
-  if (originalCursor < v2OriginalLen) {
-    appendSegment(segments, { kind: 'equal' }, d1.newOriginalWords.slice(originalCursor))
+
+  // Trailing original tokens (structural closing tags after the last
+  // content word).
+  if (originalCursor < genesisOriginalLen) {
+    appendSegment(segments, { kind: 'equal' }, dCp.oldOriginalWords.slice(originalCursor))
   }
 
   return segments
@@ -97,80 +140,135 @@ export function buildSegments(d1: AnalyzeResult, d2: AnalyzeResult): Segment[] {
 
 // ────────────────────────────────────────────────────────────────────────────
 
-type V2Origin = 'preserved-from-v1' | 'inserted-by-cp' | 'replaced-into-by-cp'
-type V2Fate = 'preserved-to-v3' | 'deleted-by-me' | 'replaced-out-by-me'
+type GenesisFate = 'kept' | 'deleted'
 
-function buildOriginMap(ops: readonly Operation[], v2Len: number): V2Origin[] {
-  const out: V2Origin[] = new Array(v2Len).fill('preserved-from-v1')
-  for (const op of ops) {
-    const origin =
-      op.action === Action.Insert ? 'inserted-by-cp' : op.action === Action.Replace ? 'replaced-into-by-cp' : null
-    if (origin === null) continue
-    for (let i = op.startInNew; i < op.endInNew; i++) {
-      if (i >= 0 && i < v2Len) out[i] = origin
-    }
-  }
-  return out
-}
-
-function buildFateMap(ops: readonly Operation[], v2Len: number): V2Fate[] {
-  const out: V2Fate[] = new Array(v2Len).fill('preserved-to-v3')
+/**
+ * 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) {
-    const fate =
-      op.action === Action.Delete ? 'deleted-by-me' : op.action === Action.Replace ? 'replaced-out-by-me' : null
-    if (fate === null) continue
+    if (op.action !== Action.Delete && op.action !== Action.Replace) continue
     for (let i = op.startInOld; i < op.endInOld; i++) {
-      if (i >= 0 && i < v2Len) out[i] = fate
+      if (i >= 0 && i < genesisLen) out[i] = 'deleted'
     }
   }
   return out
 }
 
-function isDeletion(attr: Attribution): boolean {
-  return attr.kind === 'del' || attr.kind === 'reject'
-}
-
-function combine(origin: V2Origin, fate: V2Fate): Attribution {
-  const cpInserted = origin === 'inserted-by-cp' || origin === 'replaced-into-by-cp'
-  const meDeleted = fate === 'deleted-by-me' || fate === 'replaced-out-by-me'
-  if (!cpInserted && !meDeleted) return { kind: 'equal' }
-  if (cpInserted && !meDeleted) return { kind: 'ins', author: 'cp' }
-  if (!cpInserted && meDeleted) return { kind: 'del', author: 'me' }
-  return { kind: 'reject', by: 'me', rejected: 'cp' }
-}
-
 /**
- * Map V2-diff-boundary → CP-deleted V1 tokens at that boundary. Includes
- * both pure Delete ops and the V1-side of Replace ops (semantically a
- * Delete+Insert; the Insert half is picked up by the V2-token walk).
+ * 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 collectDeletionsAtBoundary(d: AnalyzeResult): Map<number, string[]> {
+function collectInsertionsKeyedByEnd(d: AnalyzeResult): Map<number, string[]> {
   const out = new Map<number, string[]>()
   for (const op of d.operations) {
-    if (op.action !== Action.Delete && op.action !== Action.Replace) continue
-    const words = d.oldDiffWords.slice(op.startInOld, op.endInOld)
+    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 existing = out.get(op.startInNew) ?? []
+    const key = op.endInOld
+    const existing = out.get(key) ?? []
     existing.push(...words)
-    out.set(op.startInNew, existing)
+    out.set(key, existing)
   }
   return out
 }
 
-function collectInsertionsAtBoundary(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 existing = out.get(op.startInOld) ?? []
-    existing.push(...words)
-    out.set(op.startInOld, existing)
+/**
+ * Emit any insertions at boundary `b`.
+ *
+ * Reading model: a legal reviewer wants to see CP's INTENT relative
+ * to Me's current content. Me's content is the base; CP's deltas are
+ * what they need to act on. Under that framing:
+ *   - tokens both authors inserted at the same boundary → settled
+ *   - tokens CP inserted that Me doesn't have → ins-cp (CP wants
+ *     this added)
+ *   - tokens Me inserted that CP doesn't have → del-cp (CP wants
+ *     this removed from Me's content)
+ *
+ * The third case is the load-bearing attribution flip. The
+ * genesis-spine view technically labels me-only-at-boundary tokens
+ * as "ins-me" (Me added them; CP didn't), but that's confusing to
+ * a reviewer: they see "Me added X" alongside "CP added Y" and have
+ * to mentally derive "CP wants X gone, replaced with Y". Surfacing
+ * me-only tokens as `del-cp` shows CP's intent directly:
+ *   - "CP accepted Me's text minus `things`": settled bulk + del-cp
+ *     `things` (no parallel redundant insertions)
+ *   - "CP wants `cruel` where Me wrote `brave`": ins-cp `cruel` +
+ *     del-cp `brave` (the substitution intent reads directly)
+ *   - "CP added extra words": cp-extras stay as ins-cp (same as
+ *     before; the cp-only direction was always intent-correct)
+ *
+ * Pure single-side insertions (Me added text CP doesn't engage
+ * with at all, or vice versa) keep their genesis-spine attribution
+ * — these aren't refinement cases, just Me's own content additions.
+ */
+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
+
+  // Only-one-side: emit verbatim with that side's attribution.
+  // Genuine single-author additions stay author-attributed.
+  if (!hasCp) {
+    appendSegment(segments, { kind: 'ins', author: 'me' }, meIns!)
+    return
+  }
+  if (!hasMe) {
+    appendSegment(segments, { kind: 'ins', author: 'cp' }, cpIns!)
+    return
+  }
+
+  // Both sides inserted. Identical → settled. Otherwise LCS-align
+  // and apply the asymmetric intent reading.
+  if (tokenArraysEqual(cpIns!, meIns!)) {
+    appendSegment(segments, { kind: 'equal' }, cpIns!)
+    return
+  }
+
+  const alignment = lcsAlign(cpIns! as string[], meIns! as string[])
+  for (const a of alignment) {
+    if (a.oldIdx !== null && a.newIdx !== null) {
+      // Token appears in both insertions → settled.
+      appendSegment(segments, { kind: 'equal' }, [cpIns![a.oldIdx]])
+    } else if (a.oldIdx !== null) {
+      // Token in cp's insertion only → CP wants this added.
+      appendSegment(segments, { kind: 'ins', author: 'cp' }, [cpIns![a.oldIdx]])
+    } else if (a.newIdx !== null) {
+      // Token in me's insertion only → CP wants this removed from
+      // Me's content. (Genesis-spine would label this ins-me, but
+      // that reading is misleading for a reviewer at this kind of
+      // shared boundary — see the function-level comment.)
+      appendSegment(segments, { kind: 'del', author: 'cp' }, [meIns![a.newIdx]])
+    }
   }
-  return out
 }
 
-function appendSegment(segments: Segment[], attr: Attribution, words: string[]) {
+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)) {
@@ -184,7 +282,6 @@ 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
-  if (a.kind === 'reject' && b.kind === 'reject') return true
   return false
 }
 
@@ -195,29 +292,25 @@ function sameAttribution(a: Attribution, b: Attribution): boolean {
  * pre-wrap) stay consistent. A change here propagates to every author
  * marker in the output.
  */
-export function authorAttribution(author: Author, rejects?: Author): WrapMetadata {
-  const dataAttrs: Record<string, string> = { author }
-  if (rejects !== undefined) dataAttrs.rejects = rejects
-  const extraClasses = rejects !== undefined ? `${author} rejects-${rejects}` : author
-  return { extraClasses, dataAttrs }
+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
 } {
-  switch (attr.kind) {
-    case 'ins':
-      return { tag: 'ins', baseClass: 'diffins', metadata: authorAttribution(attr.author) }
-    case 'del':
-      return { tag: 'del', baseClass: 'diffdel', metadata: authorAttribution(attr.author) }
-    case 'reject':
-      return { tag: 'del', baseClass: 'diffdel', metadata: authorAttribution(attr.by, attr.rejected) }
+  return {
+    tag: attr.kind,
+    baseClass: attr.kind === 'ins' ? 'diffins' : 'diffdel',
+    metadata: authorAttribution(attr.author),
   }
 }