UNPKG

open-agreements

Version:

Open-source legal template filling CLI and library

376 lines • 15.4 kB
/** * LCS Algorithm for Atoms * * Implements hash-based Longest Common Subsequence (LCS) algorithm * for comparing arrays of ComparisonUnitAtom. */ import { CorrelationStatus } from '../../core-types.js'; import { EMPTY_PARAGRAPH_TAG } from '../../atomizer.js'; import { debug } from './debug.js'; /** * Compute the Longest Common Subsequence of two atom arrays. * * Uses hash-based comparison for O(1) equality checks. * Time complexity: O(N * M) where N and M are array lengths. * * @param original - Atoms from the original document * @param revised - Atoms from the revised document * @returns LCS result with matches and differences */ export function computeAtomLcs(original, revised) { const n = original.length; const m = revised.length; // Build LCS length table // dp[i][j] = length of LCS of original[0..i-1] and revised[0..j-1] const dp = Array(n + 1) .fill(null) .map(() => Array(m + 1).fill(0)); for (let i = 1; i <= n; i++) { for (let j = 1; j <= m; j++) { if (atomsEqual(original[i - 1], revised[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 to find the actual LCS matches const matches = []; let i = n; let j = m; while (i > 0 && j > 0) { if (atomsEqual(original[i - 1], revised[j - 1])) { matches.unshift({ originalIndex: i - 1, revisedIndex: j - 1 }); i--; j--; } else if (dp[i - 1][j] > dp[i][j - 1]) { i--; } else { j--; } } // Find deleted and inserted indices const matchedOriginal = new Set(matches.map((m) => m.originalIndex)); const matchedRevised = new Set(matches.map((m) => m.revisedIndex)); const deletedIndices = []; for (let idx = 0; idx < n; idx++) { if (!matchedOriginal.has(idx)) { deletedIndices.push(idx); } } const insertedIndices = []; for (let idx = 0; idx < m; idx++) { if (!matchedRevised.has(idx)) { insertedIndices.push(idx); } } return { matches, deletedIndices, insertedIndices }; } /** * Check if two atoms are equal based on their hash. * * For more precise comparison, we also check the text content * and ancestor context to avoid false positives from hash collisions. */ function atomsEqual(a, b) { // First check hash for quick rejection if (a.sha1Hash !== b.sha1Hash) { return false; } // Same hash - verify content to avoid collisions const aText = a.contentElement.textContent ?? ''; const bText = b.contentElement.textContent ?? ''; if (aText !== bText) { return false; } // Check tag name if (a.contentElement.tagName !== b.contentElement.tagName) { return false; } return true; } /** * Mark correlation status on atoms based on LCS result. * * Sets atoms to Equal, Deleted, or Inserted status. * Also links matched atoms via comparisonUnitAtomBefore reference. * * @param original - Atoms from the original document * @param revised - Atoms from the revised document * @param lcsResult - Result from computeAtomLcs */ export function markCorrelationStatus(original, revised, lcsResult) { // Mark matched atoms as Equal and link them for (const match of lcsResult.matches) { const origAtom = original[match.originalIndex]; const revAtom = revised[match.revisedIndex]; origAtom.correlationStatus = CorrelationStatus.Equal; revAtom.correlationStatus = CorrelationStatus.Equal; // Link revised atom to original for format change detection revAtom.comparisonUnitAtomBefore = origAtom; } // Mark deleted atoms for (const idx of lcsResult.deletedIndices) { original[idx].correlationStatus = CorrelationStatus.Deleted; } // Mark inserted atoms for (const idx of lcsResult.insertedIndices) { revised[idx].correlationStatus = CorrelationStatus.Inserted; } } /** * Create a merged atom list for document reconstruction. * * Interleaves original and revised atoms in document order, * preserving the structure needed for track changes rendering. * * @param original - Atoms from the original document (with status marked) * @param revised - Atoms from the revised document (with status marked) * @param lcsResult - Result from computeAtomLcs * @returns Merged atom list in document order */ export function createMergedAtomList(original, revised, lcsResult) { const merged = []; // Build maps for quick lookup const originalToRevised = new Map(); const revisedToOriginal = new Map(); for (const match of lcsResult.matches) { originalToRevised.set(match.originalIndex, match.revisedIndex); revisedToOriginal.set(match.revisedIndex, match.originalIndex); } const deletedSet = new Set(lcsResult.deletedIndices); const insertedSet = new Set(lcsResult.insertedIndices); // We'll walk through the revised document order // and insert deleted atoms at appropriate positions let originalPtr = 0; let revisedPtr = 0; while (revisedPtr < revised.length || originalPtr < original.length) { // First, add any deleted atoms that come before the current revised position while (originalPtr < original.length && deletedSet.has(originalPtr)) { const atom = original[originalPtr]; atom.sourceDocument = 'original'; merged.push(atom); originalPtr++; } // Now handle the current revised atom if (revisedPtr < revised.length) { const revAtom = revised[revisedPtr]; if (insertedSet.has(revisedPtr)) { // This is an inserted atom revAtom.sourceDocument = 'revised'; merged.push(revAtom); } else { // This is an equal atom - advance original pointer past its match const matchedOrigIdx = revisedToOriginal.get(revisedPtr); if (matchedOrigIdx !== undefined) { // Add any deleted atoms before this match while (originalPtr < matchedOrigIdx) { if (deletedSet.has(originalPtr)) { const atom = original[originalPtr]; atom.sourceDocument = 'original'; merged.push(atom); } originalPtr++; } // For equal empty paragraphs, use the original version to preserve // the original document's structure (important for reject all changes) const origAtom = original[matchedOrigIdx]; if (origAtom.contentElement.tagName === EMPTY_PARAGRAPH_TAG) { origAtom.sourceDocument = 'original'; merged.push(origAtom); } else { // For non-empty content, use the revised version revAtom.sourceDocument = 'revised'; merged.push(revAtom); } // Advance past the matched original atom originalPtr = matchedOrigIdx + 1; } else { merged.push(revAtom); } } revisedPtr++; } else { // No more revised atoms - add remaining deleted originals while (originalPtr < original.length) { if (deletedSet.has(originalPtr)) { const atom = original[originalPtr]; atom.sourceDocument = 'original'; merged.push(atom); } originalPtr++; } } } return merged; } /** * Compute unified paragraph indices for merged atoms. * * Maps original and revised paragraph indices to a unified output paragraph index. * This ensures that: * 1. Atoms from corresponding paragraphs (Equal matches) share the same output index * 2. Deleted paragraphs get their own output indices interleaved with matched paragraphs * 3. Inserted paragraphs get their own output indices * * @param original - Original atoms with paragraphIndex set * @param revised - Revised atoms with paragraphIndex set * @param merged - Merged atom list * @param lcsResult - LCS result with matches */ /** * Compute a container key for an atom based on its ancestor chain. * For atoms inside table cells, produces a string like "w:tbl:0/w:tr:2/w:tc:1". * For atoms not in tables, produces "". * Used to prevent cross-cell paragraph matches in unified index assignment. */ function getAtomContainerKey(atom) { const parts = []; for (const el of atom.ancestorElements) { if (el.tagName === 'w:tc' || el.tagName === 'w:tr' || el.tagName === 'w:tbl') { let index = 0; let sibling = el.previousSibling; while (sibling) { if (sibling.nodeType === 1 && sibling.tagName === el.tagName) { index++; } sibling = sibling.previousSibling; } parts.push(`${el.tagName}:${index}`); } } return parts.join('/'); } export function assignUnifiedParagraphIndices(original, revised, merged, lcsResult) { // Build paragraph correspondence from matches. // Container-aware (issue #65): skip matches where atoms are in different // structural containers (e.g., different table cells) to prevent empty // paragraphs from matching across cell boundaries. const originalToRevisedPara = new Map(); for (const match of lcsResult.matches) { const origAtom = original[match.originalIndex]; const revAtom = revised[match.revisedIndex]; if (origAtom.paragraphIndex !== undefined && revAtom.paragraphIndex !== undefined) { if (!originalToRevisedPara.has(origAtom.paragraphIndex)) { // Only establish correspondence if atoms are in the same container if (getAtomContainerKey(origAtom) === getAtomContainerKey(revAtom)) { originalToRevisedPara.set(origAtom.paragraphIndex, revAtom.paragraphIndex); } } } } // Collect all unique original paragraph indices const allOriginalParas = [...new Set(original.map(a => a.paragraphIndex).filter(p => p !== undefined))]; allOriginalParas.sort((a, b) => a - b); // Collect all unique revised paragraph indices const allRevisedParas = [...new Set(revised.map(a => a.paragraphIndex).filter(p => p !== undefined))]; allRevisedParas.sort((a, b) => a - b); // Build interleaved output index sequence // Walk through original paragraphs in order, interleaving with revised paragraphs const originalToOutputPara = new Map(); const revisedToOutputPara = new Map(); let nextOutputPara = 0; let revisedIdx = 0; for (const origPara of allOriginalParas) { const correspondingRevised = originalToRevisedPara.get(origPara); if (correspondingRevised !== undefined) { // This original paragraph has a correspondent in revised // First, assign output indices to any revised paragraphs before this correspondent while (revisedIdx < allRevisedParas.length && allRevisedParas[revisedIdx] < correspondingRevised) { const revPara = allRevisedParas[revisedIdx]; if (!revisedToOutputPara.has(revPara)) { revisedToOutputPara.set(revPara, nextOutputPara++); } revisedIdx++; } // Assign the same output index to both original and revised if (!revisedToOutputPara.has(correspondingRevised)) { revisedToOutputPara.set(correspondingRevised, nextOutputPara); originalToOutputPara.set(origPara, nextOutputPara); nextOutputPara++; } else { originalToOutputPara.set(origPara, revisedToOutputPara.get(correspondingRevised)); } // Move past this revised paragraph if (revisedIdx < allRevisedParas.length && allRevisedParas[revisedIdx] === correspondingRevised) { revisedIdx++; } } else { // This original paragraph is deleted (no correspondent) // Give it its own output index originalToOutputPara.set(origPara, nextOutputPara++); } } // Assign output indices to any remaining revised paragraphs (inserted) while (revisedIdx < allRevisedParas.length) { const revPara = allRevisedParas[revisedIdx]; if (!revisedToOutputPara.has(revPara)) { revisedToOutputPara.set(revPara, nextOutputPara++); } revisedIdx++; } // Assign unified paragraph indices to merged atoms let emptyParagraphsWithoutMapping = 0; for (const atom of merged) { if (atom.paragraphIndex === undefined) continue; const isEmptyPara = atom.contentElement.tagName === EMPTY_PARAGRAPH_TAG; if (atom.correlationStatus === CorrelationStatus.Deleted || atom.correlationStatus === CorrelationStatus.MovedSource) { // Deleted and MovedSource atoms have paragraph indices from original const outputPara = originalToOutputPara.get(atom.paragraphIndex); if (outputPara !== undefined) { atom.paragraphIndex = outputPara; } else if (isEmptyPara) { emptyParagraphsWithoutMapping++; } } else if (atom.correlationStatus === CorrelationStatus.Equal && isEmptyPara) { // Equal empty paragraphs use the original atom (see createMergedAtomList), // so their paragraphIndex is from original, not revised const outputPara = originalToOutputPara.get(atom.paragraphIndex); if (outputPara !== undefined) { atom.paragraphIndex = outputPara; } else { emptyParagraphsWithoutMapping++; } } else { // Inserted and Equal (non-empty) atoms have paragraph indices from revised const outputPara = revisedToOutputPara.get(atom.paragraphIndex); if (outputPara !== undefined) { atom.paragraphIndex = outputPara; } else if (isEmptyPara) { emptyParagraphsWithoutMapping++; } } } if (emptyParagraphsWithoutMapping > 0) { debug('atomLcs', `Empty paragraphs without mapping: ${emptyParagraphsWithoutMapping}`); } } /** * Compute statistics from LCS result. */ export function computeLcsStats(original, revised, lcsResult) { return { equal: lcsResult.matches.length, deleted: lcsResult.deletedIndices.length, inserted: lcsResult.insertedIndices.length, originalCount: original.length, revisedCount: revised.length, }; } //# sourceMappingURL=atomLcs.js.map