open-agreements
Version:
Open-source legal template filling CLI and library
390 lines • 14 kB
JavaScript
/**
* Move Detection Module
*
* Detects relocated content after LCS comparison by matching deleted blocks
* with inserted blocks using Jaccard word similarity.
*
* Pipeline position:
* LCS() → MarkRowsAsDeletedOrInserted() → FlattenToAtomList() → detectMovesInAtomList() → CoalesceRecurse()
*
* @see WmlComparer.cs DetectMovesInAtomList() line 3811
*/
import { CorrelationStatus, DEFAULT_MOVE_DETECTION_SETTINGS, } from './core-types.js';
import { getLeafText } from './primitives/index.js';
import { parseXml } from './primitives/xml.js';
// =============================================================================
// Text Extraction
// =============================================================================
/**
* Extract text content from an atom.
*
* @param atom - The atom to extract text from
* @returns The text content, or empty string for non-text atoms
*/
export function getAtomText(atom) {
const element = atom.contentElement;
// Handle text elements
if (element.tagName === 'w:t' || element.tagName === 'w:delText') {
return getLeafText(element) ?? '';
}
// Handle break elements
if (element.tagName === 'w:br' || element.tagName === 'w:cr') {
return '\n';
}
// Handle tab
if (element.tagName === 'w:tab') {
return '\t';
}
return '';
}
/**
* Extract text from a sequence of atoms.
*
* @param atoms - The atoms to extract text from
* @returns Combined text content
*/
export function getAtomsText(atoms) {
return atoms.map(getAtomText).join('');
}
/**
* Count words in text.
*
* @param text - The text to count words in
* @returns Number of words
*/
export function countWords(text) {
const words = text.split(/\s+/).filter(Boolean);
return words.length;
}
// =============================================================================
// Jaccard Similarity
// =============================================================================
/**
* Calculate Jaccard similarity between two texts based on word sets.
*
* Jaccard index = |intersection| / |union|
*
* Benefits:
* - Order-independent: "fox quick brown" matches "brown quick fox"
* - Handles insertions/deletions well: adding one word to a 10-word block only slightly reduces similarity
* - O(n) complexity where n = total words
*
* @param text1 - First text
* @param text2 - Second text
* @param caseInsensitive - Whether to ignore case (default: true)
* @returns Similarity score between 0 and 1
*
* @example
* jaccardWordSimilarity("The quick brown fox", "The quick brown dog")
* // Returns 0.6 (3 common words / 5 total unique words)
*/
export function jaccardWordSimilarity(text1, text2, caseInsensitive = true) {
const normalize = caseInsensitive
? (s) => s.toLowerCase()
: (s) => s;
const words1 = new Set(normalize(text1)
.split(/\s+/)
.filter(Boolean));
const words2 = new Set(normalize(text2)
.split(/\s+/)
.filter(Boolean));
if (words1.size === 0 && words2.size === 0) {
return 1; // Both empty = identical
}
if (words1.size === 0 || words2.size === 0) {
return 0; // One empty = completely different
}
// Calculate intersection
let intersectionSize = 0;
for (const word of words1) {
if (words2.has(word)) {
intersectionSize++;
}
}
// Calculate union (|A| + |B| - |A ∩ B|)
const unionSize = words1.size + words2.size - intersectionSize;
return intersectionSize / unionSize;
}
// =============================================================================
// Block Grouping
// =============================================================================
/**
* Group consecutive atoms by correlation status.
*
* Creates blocks of atoms with the same status (Deleted or Inserted).
*
* @param atoms - The atoms to group
* @returns Array of atom blocks
*/
export function groupIntoBlocks(atoms) {
const blocks = [];
let currentBlock = null;
for (const atom of atoms) {
const status = atom.correlationStatus;
// Only group Deleted and Inserted atoms for move detection
if (status !== CorrelationStatus.Deleted && status !== CorrelationStatus.Inserted) {
// End current block
if (currentBlock) {
blocks.push(currentBlock);
currentBlock = null;
}
continue;
}
// Start new block or continue existing
if (!currentBlock || currentBlock.status !== status) {
if (currentBlock) {
blocks.push(currentBlock);
}
currentBlock = {
status,
atoms: [atom],
text: getAtomText(atom),
wordCount: 0, // Calculated at end
};
}
else {
currentBlock.atoms.push(atom);
currentBlock.text += getAtomText(atom);
}
}
// Don't forget the last block
if (currentBlock) {
blocks.push(currentBlock);
}
// Calculate word counts
for (const block of blocks) {
block.wordCount = countWords(block.text);
}
return blocks;
}
/**
* Find the best matching inserted block for a deleted block.
*
* @param deleted - The deleted block to match
* @param insertedBlocks - Available inserted blocks
* @param settings - Move detection settings
* @returns The best match, or undefined if no match meets threshold
*/
export function findBestMatch(deleted, insertedBlocks, settings) {
let bestMatch;
for (let i = 0; i < insertedBlocks.length; i++) {
const inserted = insertedBlocks[i];
if (!inserted)
continue;
// Skip already matched blocks (marked as MovedDestination)
if (inserted.atoms.length > 0 &&
inserted.atoms[0]?.correlationStatus === CorrelationStatus.MovedDestination) {
continue;
}
const similarity = jaccardWordSimilarity(deleted.text, inserted.text, settings.caseInsensitiveMove);
if (similarity >= settings.moveSimilarityThreshold) {
if (!bestMatch || similarity > bestMatch.similarity) {
bestMatch = { block: inserted, similarity, index: i };
}
}
}
return bestMatch;
}
// =============================================================================
// Move Marking
// =============================================================================
/**
* Mark atoms as part of a move operation.
*
* @param atoms - Atoms to mark
* @param status - New correlation status (MovedSource or MovedDestination)
* @param moveGroupId - ID linking source and destination
* @param moveName - Name for move tracking (e.g., "move1")
*/
export function markAsMove(atoms, status, moveGroupId, moveName) {
for (const atom of atoms) {
atom.correlationStatus = status;
atom.moveGroupId = moveGroupId;
atom.moveName = moveName;
}
}
// =============================================================================
// Main Algorithm
// =============================================================================
/**
* Detect moves in a flat list of atoms.
*
* Runs after LCS comparison to identify deleted blocks that were actually
* moved to a new location. Updates atoms in place with move status.
*
* @param atoms - The atom list to process (modified in place)
* @param settings - Move detection settings (optional, uses defaults)
*
* @see WmlComparer.cs DetectMovesInAtomList() line 3811
*
* @example
* const atoms = atomizeTree(document, [], part);
* runLCSComparison(atoms);
* detectMovesInAtomList(atoms); // Updates atoms in place
*/
export function detectMovesInAtomList(atoms, settings = DEFAULT_MOVE_DETECTION_SETTINGS) {
if (!settings.detectMoves) {
return;
}
// 1. Group consecutive atoms by status
const blocks = groupIntoBlocks(atoms);
// 2. Filter by minimum word count
const deletedBlocks = blocks.filter((b) => b.status === CorrelationStatus.Deleted &&
b.wordCount >= settings.moveMinimumWordCount);
const insertedBlocks = blocks.filter((b) => b.status === CorrelationStatus.Inserted &&
b.wordCount >= settings.moveMinimumWordCount);
// 3. Find best matches using Jaccard similarity
let moveGroupId = 1;
for (const deleted of deletedBlocks) {
const bestMatch = findBestMatch(deleted, insertedBlocks, settings);
if (bestMatch) {
// 4. Convert to moves
const moveName = `move${moveGroupId}`;
markAsMove(deleted.atoms, CorrelationStatus.MovedSource, moveGroupId, moveName);
markAsMove(bestMatch.block.atoms, CorrelationStatus.MovedDestination, moveGroupId, moveName);
moveGroupId++;
}
}
}
/**
* Format a date as ISO string for w:date attribute.
*/
function formatDateTime(date) {
return date.toISOString();
}
/**
* Generate move source markup (w:moveFrom with range markers).
*
* @param moveName - Name linking source and destination (e.g., "move1")
* @param content - Child elements to wrap
* @param options - Markup generation options
* @returns Move markup elements
*
* @example
* Output structure:
* <w:moveFromRangeStart w:id="1" w:name="move1" w:author="..." w:date="..."/>
* <w:moveFrom w:id="2" w:author="..." w:date="...">
* <!-- content -->
* </w:moveFrom>
* <w:moveFromRangeEnd w:id="1"/>
*/
export function generateMoveSourceMarkup(moveName, content, options) {
const doc = parseXml('<root xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"/>');
const W_NS = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
const dateStr = formatDateTime(options.dateTime);
const rangeId = options.startId.toString();
const moveId = (options.startId + 1).toString();
const rangeStart = doc.createElementNS(W_NS, 'w:moveFromRangeStart');
rangeStart.setAttribute('w:id', rangeId);
rangeStart.setAttribute('w:name', moveName);
rangeStart.setAttribute('w:author', options.author);
rangeStart.setAttribute('w:date', dateStr);
const moveWrapper = doc.createElementNS(W_NS, 'w:moveFrom');
moveWrapper.setAttribute('w:id', moveId);
moveWrapper.setAttribute('w:author', options.author);
moveWrapper.setAttribute('w:date', dateStr);
for (const child of content)
moveWrapper.appendChild(child);
const rangeEnd = doc.createElementNS(W_NS, 'w:moveFromRangeEnd');
rangeEnd.setAttribute('w:id', rangeId);
return {
rangeStart,
moveWrapper,
rangeEnd,
nextId: options.startId + 2,
};
}
/**
* Generate move destination markup (w:moveTo with range markers).
*
* @param moveName - Name linking source and destination (e.g., "move1")
* @param content - Child elements to wrap
* @param options - Markup generation options
* @returns Move markup elements
*
* @example
* Output structure:
* <w:moveToRangeStart w:id="3" w:name="move1" w:author="..." w:date="..."/>
* <w:moveTo w:id="4" w:author="..." w:date="...">
* <!-- content -->
* </w:moveTo>
* <w:moveToRangeEnd w:id="3"/>
*/
export function generateMoveDestinationMarkup(moveName, content, options) {
const doc = parseXml('<root xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"/>');
const W_NS = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
const dateStr = formatDateTime(options.dateTime);
const rangeId = options.startId.toString();
const moveId = (options.startId + 1).toString();
const rangeStart = doc.createElementNS(W_NS, 'w:moveToRangeStart');
rangeStart.setAttribute('w:id', rangeId);
rangeStart.setAttribute('w:name', moveName);
rangeStart.setAttribute('w:author', options.author);
rangeStart.setAttribute('w:date', dateStr);
const moveWrapper = doc.createElementNS(W_NS, 'w:moveTo');
moveWrapper.setAttribute('w:id', moveId);
moveWrapper.setAttribute('w:author', options.author);
moveWrapper.setAttribute('w:date', dateStr);
for (const child of content)
moveWrapper.appendChild(child);
const rangeEnd = doc.createElementNS(W_NS, 'w:moveToRangeEnd');
rangeEnd.setAttribute('w:id', rangeId);
return {
rangeStart,
moveWrapper,
rangeEnd,
nextId: options.startId + 2,
};
}
/**
* Create initial revision ID state.
*
* @param startId - Starting ID (default: 1)
* @returns Initial state
*/
export function createRevisionIdState(startId = 1) {
return {
nextId: startId,
moveRangeIds: new Map(),
};
}
/**
* Allocate IDs for a move operation.
*
* Ensures source and destination use consistent IDs for proper linking.
*
* @param state - Revision ID state (modified in place)
* @param moveName - Move name (e.g., "move1")
* @returns IDs for source and destination markup
*/
export function allocateMoveIds(state, moveName) {
let ids = state.moveRangeIds.get(moveName);
if (!ids) {
// Allocate new IDs: source range, source move, dest range, dest move
ids = {
sourceRangeId: state.nextId,
destRangeId: state.nextId + 2,
};
state.moveRangeIds.set(moveName, ids);
state.nextId += 4;
}
return {
sourceRangeId: ids.sourceRangeId,
sourceMoveId: ids.sourceRangeId + 1,
destRangeId: ids.destRangeId,
destMoveId: ids.destRangeId + 1,
};
}
/**
* Fix up revision IDs after all moves have been processed.
*
* Ensures proper ID pairing between source and destination elements.
* This is a post-processing step after markup generation.
*
* @param state - The revision ID state
*/
export function fixUpRevisionIds(_state) {
// No-op for now - IDs are allocated consistently during generation
// This function exists for future use if ID renumbering is needed
}
//# sourceMappingURL=move-detection.js.map