UNPKG

open-agreements

Version:

Open-source legal template filling CLI and library

1,002 lines • 39.2 kB
/** * Atomizer Module * * Provides factory functions for creating ComparisonUnitAtom instances. * Implements the core atomization logic from WmlComparer. * * @see WmlComparer.cs ComparisonUnitAtom constructor (lines 2314-2343) */ import { createHash } from 'crypto'; import { parseXml } from './primitives/xml.js'; import { CorrelationStatus, } from './core-types.js'; import { getLeafText, setLeafText, childElements, findChildByTagName, } from './primitives/index.js'; import { OOXML } from './primitives/namespaces.js'; // ============================================================================= // Shared synthetic document for creating virtual elements // ============================================================================= /** * A shared document used to create synthetic/virtual DOM elements. * These elements are not part of any real parsed document. */ const SYNTHETIC_DOC = parseXml('<root/>'); // ============================================================================= // SHA1 Hashing // ============================================================================= /** * Calculate SHA1 hash of a string. * * Used for quick equality checking of comparison units. * * @param content - The string content to hash * @returns Hexadecimal SHA1 hash string */ export function sha1(content) { return createHash('sha1').update(content, 'utf8').digest('hex'); } /** * Attributes that should be excluded from hashing for certain elements. * * - xml:space: A whitespace preservation hint that doesn't affect content. * Documents may have this attribute present on some w:t elements and absent * on others with identical text, causing spurious hash mismatches. */ const IGNORED_HASH_ATTRIBUTES = new Set(['xml:space']); /** * Calculate SHA1 hash for a WmlElement. * * Includes tag name, attributes, and text content for uniqueness. * Excludes presentation-only attributes like xml:space that don't affect content. * * @param element - The element to hash * @returns Hexadecimal SHA1 hash string */ export function hashElement(element) { const parts = [element.tagName]; // Sort attributes for deterministic hashing, excluding presentation-only attributes const attrs = []; for (let i = 0; i < element.attributes.length; i++) { const attr = element.attributes[i]; attrs.push([attr.name, attr.value]); } const sortedAttrs = attrs .filter(([key]) => !IGNORED_HASH_ATTRIBUTES.has(key)) .sort(([a], [b]) => a.localeCompare(b)); for (const [key, value] of sortedAttrs) { parts.push(`${key}=${value}`); } const leafText = getLeafText(element); if (leafText !== undefined) { parts.push(leafText); } return sha1(parts.join('|')); } // ============================================================================= // Revision Tracking Detection // ============================================================================= /** * Revision tracking element tag names. */ const REVISION_TRACKING_TAGS = new Set(['w:ins', 'w:del', 'w:moveFrom', 'w:moveTo']); /** * Find a revision tracking element in the ancestor chain. * * Searches ancestors from nearest to root for w:ins, w:del, w:moveFrom, or w:moveTo. * * @param ancestors - Ancestor elements from root to parent * @returns The revision tracking element if found, undefined otherwise */ export function findRevisionTrackingElement(ancestors) { // Search from nearest ancestor to root for (let i = ancestors.length - 1; i >= 0; i--) { const ancestor = ancestors[i]; if (ancestor && REVISION_TRACKING_TAGS.has(ancestor.tagName)) { return ancestor; } } return undefined; } /** * Determine initial correlation status from revision tracking element. * * @param revTrackElement - The revision tracking element (if any) * @returns Initial correlation status */ export function getStatusFromRevisionTracking(revTrackElement) { if (!revTrackElement) { return CorrelationStatus.Unknown; } switch (revTrackElement.tagName) { case 'w:ins': return CorrelationStatus.Inserted; case 'w:del': return CorrelationStatus.Deleted; case 'w:moveFrom': return CorrelationStatus.MovedSource; case 'w:moveTo': return CorrelationStatus.MovedDestination; default: return CorrelationStatus.Unknown; } } // ============================================================================= // Ancestor Unid Extraction // ============================================================================= /** * Extract Unid attributes from ancestor elements. * * WmlComparer uses w:Unid attributes to correlate elements between documents. * * @param ancestors - Ancestor elements from root to parent * @returns Array of Unid values found in ancestors */ export function extractAncestorUnids(ancestors) { const unids = []; for (const ancestor of ancestors) { const unid = ancestor.getAttribute('w:Unid'); if (unid) { unids.push(unid); } } return unids; } // ============================================================================= // Leaf Node Detection // ============================================================================= /** * Tag names that represent leaf nodes in the atomization tree. */ const LEAF_NODE_TAGS = new Set([ 'w:t', // Text 'w:br', // Break 'w:cr', // Carriage return 'w:tab', // Tab character 'w:sym', // Symbol 'w:softHyphen', // Soft hyphen 'w:noBreakHyphen', // Non-breaking hyphen 'w:fldChar', // Field character 'w:instrText', // Field instruction text 'w:delText', // Deleted text 'w:dayShort', // Date field short day 'w:dayLong', // Date field long day 'w:monthShort', // Date field short month 'w:monthLong', // Date field long month 'w:yearShort', // Date field short year 'w:yearLong', // Date field long year 'w:annotationRef', // Annotation reference 'w:footnoteRef', // Footnote reference marker 'w:endnoteRef', // Endnote reference marker 'w:footnoteReference', // Footnote reference 'w:endnoteReference', // Endnote reference 'w:commentReference', // Comment reference anchor (run-level child). // Note: w:commentRangeStart / w:commentRangeEnd / w:bookmarkStart / // w:bookmarkEnd / w:moveFromRangeStart/End / w:moveToRangeStart/End / // w:permStart / w:permEnd are paragraph-level markers // (siblings of <w:r>, not children). They are // tracked in PARAGRAPH_LEVEL_TAGS below and atomized via a separate branch in // atomizeTreeInternal so the reconstructor can emit them outside synthetic // <w:r> wrappers. 'w:separator', // Separator 'w:continuationSeparator', // Continuation separator 'w:pgNum', // Page number 'w:drawing', // Drawing (treat as atomic) 'w:pict', // Picture (VML) 'w:object', // Embedded object 'mc:AlternateContent', // Alternate content ]); /** * Tag names that are paragraph-level OOXML markers. * * These elements are valid as direct children of <w:p> (and revision wrappers * like <w:ins>/<w:del>/<w:moveFrom>/<w:moveTo>) but never inside <w:r>. The * rebuild reconstructor emits them as siblings of <w:r>, not leaves wrapped in * a synthetic run. * * Scope: commentRange, bookmark, moveFromRange / moveToRange, and * range-permission (permStart / permEnd) markers. Explicit move-range markers * coexist with the synthetic emission in wrapWithMoveFrom and wrapWithMoveTo: * the reconstructor suppresses synthesis for paragraphs whose atom stream * already carries explicit markers of the same kind, so the two paths never * double-emit. * * @conformance ECMA-376 edition 5, Part 1 § 17.13.5 * @see https://github.com/UseJunior/safe-docx/issues/110 * @see https://github.com/UseJunior/safe-docx/issues/111 */ export const PARAGRAPH_LEVEL_TAGS = new Set([ 'w:commentRangeStart', 'w:commentRangeEnd', 'w:bookmarkStart', 'w:bookmarkEnd', 'w:moveFromRangeStart', 'w:moveFromRangeEnd', 'w:moveToRangeStart', 'w:moveToRangeEnd', 'w:permStart', 'w:permEnd', ]); /** * Special tag name for empty paragraph boundary atoms. * These atoms are created for paragraphs that have no content (only w:pPr). */ export const EMPTY_PARAGRAPH_TAG = '__emptyParagraph__'; /** * Check if an element is a leaf node for atomization. * * Leaf nodes are the smallest units that can be compared. * * @param element - The element to check * @returns True if this is a leaf node */ export function isLeafNode(element) { return LEAF_NODE_TAGS.has(element.tagName); } /** * Check if an element is a paragraph-level OOXML marker. * * Paragraph-level markers (PARAGRAPH_LEVEL_TAGS: commentRange*, bookmark*, * moveFromRange*, moveToRange*, perm*) are * atomized only when they sit inside a <w:p> ancestor — body/table-sibling * placements stay out of the atom stream and are handled by the scaffold-strip * block in the reconstructor. */ export function isParagraphLevelLeaf(element) { return PARAGRAPH_LEVEL_TAGS.has(element.tagName); } /** * Create a ComparisonUnitAtom from a leaf element. * * Replicates the C# ComparisonUnitAtom constructor logic: * 1. Finds revision tracking elements in ancestors * 2. Sets initial correlation status based on revision type * 3. Extracts ancestor Unids for correlation * 4. Calculates SHA1 hash for equality checking * * @param options - Options containing element, ancestors, and part * @returns A new ComparisonUnitAtom * * @see WmlComparer.cs lines 2314-2343 */ export function createComparisonUnitAtom(options) { const { contentElement, ancestors, part } = options; // Find revision tracking element in ancestors const revTrackElement = findRevisionTrackingElement(ancestors); // Determine initial correlation status const correlationStatus = getStatusFromRevisionTracking(revTrackElement); // Extract Unids from ancestors const ancestorUnids = extractAncestorUnids(ancestors); // Calculate SHA1 hash for the atom const sha1Hash = hashElement(contentElement); // Extract and clone run properties for first-class rPr access const rPrElement = getRunProperties({ ancestorElements: ancestors }); const rPr = rPrElement ? rPrElement.cloneNode(true) : null; return { contentElement, ancestorElements: [...ancestors], // Copy to avoid mutation ancestorUnids, part, revTrackElement, sha1Hash, correlationStatus, rPr, }; } // ============================================================================= // Tree Atomization // ============================================================================= /** * Check if a paragraph element is empty (has no content-bearing children). * * Empty paragraphs have only paragraph properties, or proofing-error anchors. * `w:proofErr` marks spelling/grammar proofing state and carries no document * content, so a paragraph containing only those anchors is empty for * comparison. * * @conformance ECMA-376 edition 5, Part 1 § 17.13.8.1 * @see https://github.com/UseJunior/safe-docx/issues/456 */ const EMPTY_PARAGRAPH_TRANSPARENT_TAGS = new Set(['w:pPr', 'w:proofErr']); function isEmptyParagraph(node) { if (node.tagName !== 'w:p') return false; const kids = childElements(node); if (kids.length === 0) return true; for (const child of kids) { if (!EMPTY_PARAGRAPH_TRANSPARENT_TAGS.has(child.tagName)) { return false; } } return true; } /** * Create an empty paragraph boundary atom with context-aware hash. * * These atoms represent empty paragraphs that have no text content, * ensuring they are preserved during document reconstruction. * * The hash includes a paragraph-level content signature for the previous * content-bearing paragraph and a consecutive-empty index. Text fragment * boundaries are ignored, while non-text leaves contribute stable tokens. * * @param paragraphElement - The w:p element * @param ancestors - Ancestor elements from root to parent * @param part - The OPC part * @param state - Atomization state with context information */ function createEmptyParagraphAtomWithContext(paragraphElement, ancestors, part, state) { // Create a virtual element to represent the empty paragraph const virtualElement = SYNTHETIC_DOC.createElement(EMPTY_PARAGRAPH_TAG); // Find revision tracking element in ancestors const revTrackElement = findRevisionTrackingElement(ancestors); // Determine initial correlation status const correlationStatus = getStatusFromRevisionTracking(revTrackElement); const pPr = findChildByTagName(paragraphElement, 'w:pPr'); const pPrHash = pPr ? hashElement(pPr) : 'no-pPr'; const contextHash = state.lastContentHash || 'document-start'; const hashContent = `empty-paragraph:${contextHash}:${state.consecutiveEmptyIndex}:${pPrHash}`; return { contentElement: virtualElement, ancestorElements: [...ancestors, paragraphElement], ancestorUnids: extractAncestorUnids(ancestors), part, revTrackElement, sha1Hash: sha1(hashContent), correlationStatus, isEmptyParagraph: true, // Mark this as an empty paragraph atom rPr: null, // Empty paragraphs have no run formatting }; } function updateParagraphContentContext(node, atoms, state) { if (node.tagName !== 'w:p') { return; } const contentAtoms = atoms.filter((atom) => !PARAGRAPH_LEVEL_TAGS.has(atom.contentElement.tagName)); if (contentAtoms.length === 0) { return; } const signature = contentAtoms .map((atom) => { if (atom.contentElement.tagName === 'w:t') { return getLeafText(atom.contentElement) ?? ''; } return `\u0000${atom.contentElement.tagName}:${atom.sha1Hash}\u0000`; }) .join(''); state.lastContentHash = sha1(`para-content:${signature}`); state.consecutiveEmptyIndex = 0; } /** * Internal recursive atomization function with state tracking. */ function atomizeTreeInternal(node, ancestors, part, state, options) { const atoms = []; if (isLeafNode(node)) { const atom = createComparisonUnitAtom({ contentElement: options.cloneLeafNodes ? node.cloneNode(true) : node, ancestors, part, }); atoms.push(atom); } else if (options.atomizeParagraphLevelMarkers && isParagraphLevelLeaf(node) && ancestors.some((a) => a.tagName === 'w:p')) { // Paragraph-level markers (commentRange*, bookmark*, perm*) inside a <w:p> // become atoms so the rebuild reconstructor can re-emit them as siblings // of <w:r>. // Body/table-sibling placements are intentionally skipped — they are // already handled by the scaffold-strip block in the reconstructor and // would otherwise misattach to the previous paragraph in // assignParagraphIndices(). const atom = createComparisonUnitAtom({ contentElement: options.cloneLeafNodes ? node.cloneNode(true) : node, ancestors, part, }); atoms.push(atom); } else if (isEmptyParagraph(node)) { // Create empty paragraph atom with context-aware hash atoms.push(createEmptyParagraphAtomWithContext(node, ancestors, part, state)); state.emptyParagraphCount++; state.consecutiveEmptyIndex++; } else { for (const child of childElements(node)) { atoms.push(...atomizeTreeInternal(child, [...ancestors, node], part, state, options)); } updateParagraphContentContext(node, atoms, state); } return atoms; } /** * Atomize a document tree into a flat list of ComparisonUnitAtoms. * * Recursively traverses the tree, creating atoms for each leaf node. * Also creates special atoms for empty paragraphs to preserve document structure. * * @param node - The current node in the tree * @param ancestors - Ancestor elements from root to parent of node * @param part - The OPC part this tree belongs to * @returns Array of ComparisonUnitAtoms from leaf nodes */ export function atomizeTree(node, ancestors, part, options = {}) { const normalizedOptions = { cloneLeafNodes: options.cloneLeafNodes ?? false, mergeAcrossRuns: options.mergeAcrossRuns ?? true, mergePunctuationAcrossRuns: options.mergePunctuationAcrossRuns ?? true, splitTextIntoWords: options.splitTextIntoWords ?? true, atomizeParagraphLevelMarkers: options.atomizeParagraphLevelMarkers ?? false, }; const state = { emptyParagraphCount: 0, consecutiveEmptyIndex: 0, lastContentHash: '', }; const rawAtoms = atomizeTreeInternal(node, ancestors, part, state, normalizedOptions); // Step 1: Collapse field sequences into single atoms based on visible text // This allows matching between hardcoded text and field references const fieldCollapsedAtoms = collapseFieldSequences(rawAtoms); // Step 2: Merge contiguous text atoms with same formatting // This normalizes different w:t split boundaries const mergedAtoms = mergeContiguousTextAtoms(fieldCollapsedAtoms, normalizedOptions); // Step 3: Split merged atoms at word boundaries for finer-grained comparison // This enables word-level diffing within paragraphs const wordSplitAtoms = normalizedOptions.splitTextIntoWords ? splitAtomsIntoWords(mergedAtoms) : mergedAtoms; // Step 4: Merge punctuation-only atoms with preceding text // This handles "Conduct" + "," vs "Conduct," split differences // Must run AFTER word split since that's when punctuation becomes separate atoms const atoms = mergePunctuationAtoms(wordSplitAtoms, normalizedOptions); console.log(`[DEBUG] atomizeTree: created ${rawAtoms.length} atoms, field-collapsed to ${fieldCollapsedAtoms.length}, merged to ${mergedAtoms.length}, word-split to ${wordSplitAtoms.length}, punct-merged to ${atoms.length}, ${state.emptyParagraphCount} empty paragraphs`); return { atoms, emptyParagraphCount: state.emptyParagraphCount }; } /** * Get all ancestors of a node by following parent references. * * @param node - The node to get ancestors for * @returns Array of ancestors from root to immediate parent */ export function getAncestors(node) { const ancestors = []; let current = node.parentNode; while (current && current.nodeType === 1 /* ELEMENT_NODE */) { ancestors.unshift(current); current = current.parentNode; } return ancestors; } /** * Assign paragraph indices to atoms based on their w:p ancestors. * * This enables paragraph grouping in the document reconstructor when * merging atoms from different source trees (original vs revised). * * @param atoms - Array of atoms to assign indices to */ export function assignParagraphIndices(atoms) { const paragraphToIndex = new Map(); let nextIndex = 0; for (const atom of atoms) { // Find the w:p ancestor const pAncestor = atom.ancestorElements.find((a) => a.tagName === 'w:p'); if (pAncestor) { // Get or assign index for this paragraph let index = paragraphToIndex.get(pAncestor); if (index === undefined) { index = nextIndex++; paragraphToIndex.set(pAncestor, index); } atom.paragraphIndex = index; } } } // ============================================================================= // Field Sequence Collapsing // ============================================================================= /** * Special tag name for collapsed field atoms. * These represent Word field codes (REF, PAGEREF, etc.) collapsed to their visible result. */ export const COLLAPSED_FIELD_TAG = '__collapsedField__'; /** * Check if an atom is a field begin marker. */ function isFieldBegin(atom) { return (atom.contentElement.tagName === 'w:fldChar' && atom.contentElement.getAttribute('w:fldCharType') === 'begin'); } /** * Check if an atom is a field separate marker. */ function isFieldSeparate(atom) { return (atom.contentElement.tagName === 'w:fldChar' && atom.contentElement.getAttribute('w:fldCharType') === 'separate'); } /** * Check if an atom is a field end marker. */ function isFieldEnd(atom) { return (atom.contentElement.tagName === 'w:fldChar' && atom.contentElement.getAttribute('w:fldCharType') === 'end'); } /** * Extract visible text from a sequence of atoms (field result portion). * Only includes w:t elements, ignoring field markers and instructions. */ function extractVisibleText(atoms) { return atoms .filter((a) => a.contentElement.tagName === 'w:t') .map((a) => getLeafText(a.contentElement) ?? '') .join(''); } /** * Check if a field spans multiple paragraphs. * Multi-paragraph fields (like TOC) should not be collapsed. */ function fieldSpansMultipleParagraphs(fieldAtoms) { const paragraphs = new Set(); for (const atom of fieldAtoms) { const para = atom.ancestorElements.find((e) => e.tagName === 'w:p'); if (para) { paragraphs.add(para); if (paragraphs.size > 1) { return true; } } } return false; } /** * Collapse field sequences into single atoms based on visible text. * * Word fields consist of: * - w:fldChar[begin] - field start * - w:instrText - field instruction (e.g., "REF _Ref123 \h") * - w:fldChar[separate] - separates instruction from result * - w:t (one or more) - visible result text * - w:fldChar[end] - field end * * This function collapses each field sequence into a single atom whose hash * is based only on the visible text. This allows matching between: * - Hardcoded text: "2.6" * - Field reference: [REF field]2.6[/field] * * Both will produce atoms with the same hash if the visible text matches. * * NOTE: Multi-paragraph fields (like TOC, INDEX) are NOT collapsed because * they would lose paragraph structure information. * * @param atoms - Array of atoms from atomization * @returns Array with field sequences collapsed to single atoms */ export function collapseFieldSequences(atoms) { if (atoms.length === 0) return atoms; const result = []; let i = 0; while (i < atoms.length) { const atom = atoms[i]; if (isFieldBegin(atom)) { // Found field start - collect until matching end const fieldAtoms = [atom]; let depth = 1; let separatorIndex = -1; i++; while (i < atoms.length && depth > 0) { const current = atoms[i]; fieldAtoms.push(current); if (isFieldBegin(current)) { depth++; } else if (isFieldEnd(current)) { depth--; } else if (isFieldSeparate(current) && depth === 1) { // Track separator position for the outermost field separatorIndex = fieldAtoms.length - 1; } i++; } // Check if field spans multiple paragraphs (like TOC, INDEX) // If so, don't collapse the outer field - preserve paragraph structure. // But recursively collapse inner single-paragraph fields (e.g., PAGEREF // nested inside TOC) so they are treated as single atoms during LCS. if (fieldSpansMultipleParagraphs(fieldAtoms)) { if (separatorIndex >= 0 && separatorIndex < fieldAtoms.length - 1) { // Pass through outer field markers: begin, instrText..., separate result.push(...fieldAtoms.slice(0, separatorIndex + 1)); // Recursively collapse inner content (between separator and end) const innerContent = fieldAtoms.slice(separatorIndex + 1, -1); result.push(...collapseFieldSequences(innerContent)); // Pass through outer end marker result.push(fieldAtoms[fieldAtoms.length - 1]); } else { // No separator found (unusual), pass through unchanged result.push(...fieldAtoms); } continue; } // Extract visible text from the field result (after separator) let visibleText; if (separatorIndex >= 0) { // Get text between separator and end (exclusive of markers) const resultAtoms = fieldAtoms.slice(separatorIndex + 1, -1); visibleText = extractVisibleText(resultAtoms); } else { // No separator - might be a field with no result yet, use instruction visibleText = extractVisibleText(fieldAtoms); } // Create a collapsed field atom with the visible text const firstAtom = fieldAtoms[0]; // Use w:t so it can merge with adjacent text const virtualElement = SYNTHETIC_DOC.createElementNS(OOXML.W_NS, 'w:t'); setLeafText(virtualElement, visibleText); if (/\s/.test(visibleText)) { virtualElement.setAttributeNS('http://www.w3.org/XML/1998/namespace', 'xml:space', 'preserve'); } const collapsedAtom = { contentElement: virtualElement, ancestorElements: [...firstAtom.ancestorElements], ancestorUnids: firstAtom.ancestorUnids, part: firstAtom.part, revTrackElement: firstAtom.revTrackElement, sha1Hash: hashElement(virtualElement), correlationStatus: firstAtom.correlationStatus, // Store original atoms for document reconstruction collapsedFieldAtoms: fieldAtoms, // Inherit rPr from first atom in the field sequence rPr: firstAtom.rPr, }; result.push(collapsedAtom); } else { // Not a field - pass through unchanged result.push(atom); i++; } } return result; } // ============================================================================= // Word-Level Splitting // ============================================================================= /** * Split a w:t atom into word-level atoms. * * This enables finer-grained comparison when text is stored in single w:t elements. * For example, "Hello World" becomes ["Hello", " ", "World"]. * * Preserves whitespace as separate atoms to maintain spacing. * * @param atom - A w:t atom to split * @returns Array of word-level atoms (or original atom if not w:t) */ function splitAtomIntoWords(atom) { // Only split w:t elements if (atom.contentElement.tagName !== 'w:t') { return [atom]; } // Don't split collapsed fields - they should stay as-is if (atom.collapsedFieldAtoms) { return [atom]; } const text = getLeafText(atom.contentElement) ?? ''; // Don't split short text or single words if (text.length <= 1 || !text.includes(' ')) { return [atom]; } // Split into words and whitespace, preserving both // Uses regex to split on word boundaries while keeping whitespace const parts = text.split(/(\s+)/); if (parts.length <= 1) { return [atom]; } const result = []; for (const part of parts) { if (part === '') continue; // Create a new element for this word/whitespace const wordElement = SYNTHETIC_DOC.createElementNS(OOXML.W_NS, 'w:t'); // Copy attributes from the original content element for (let i = 0; i < atom.contentElement.attributes.length; i++) { const attr = atom.contentElement.attributes[i]; wordElement.setAttribute(attr.name, attr.value); } setLeafText(wordElement, part); // Ensure OOXML renderers preserve whitespace in this fragment if (/\s/.test(part)) { wordElement.setAttributeNS('http://www.w3.org/XML/1998/namespace', 'xml:space', 'preserve'); } // Create atom for this word const wordAtom = { contentElement: wordElement, ancestorElements: atom.ancestorElements, ancestorUnids: atom.ancestorUnids, part: atom.part, revTrackElement: atom.revTrackElement, sha1Hash: hashElement(wordElement), correlationStatus: atom.correlationStatus, paragraphIndex: atom.paragraphIndex, // Track that this came from a split atom for potential later merge splitFromAtom: atom, // Share rPr reference (read-only after atomization) rPr: atom.rPr, }; result.push(wordAtom); } return result; } /** * Split all w:t atoms into word-level atoms. * * @param atoms - Array of atoms * @returns Array with w:t atoms split into words */ export function splitAtomsIntoWords(atoms) { const result = []; for (const atom of atoms) { result.push(...splitAtomIntoWords(atom)); } return result; } // ============================================================================= // Atom Boundary Normalization // ============================================================================= /** * Get the run properties (w:rPr) from an atom's run ancestor. */ function getRunProperties(atom) { const run = atom.ancestorElements.find((e) => e.tagName === 'w:r'); if (!run) return undefined; return findChildByTagName(run, 'w:rPr') ?? undefined; } /** * Compute a deep hash of an element including its children. */ function hashElementDeep(element) { const parts = [element.tagName]; // Sort attributes for deterministic hashing const attrs = []; for (let i = 0; i < element.attributes.length; i++) { const attr = element.attributes[i]; attrs.push([attr.name, attr.value]); } const sortedAttrs = attrs.sort(([a], [b]) => a.localeCompare(b)); for (const [key, value] of sortedAttrs) { parts.push(`${key}=${value}`); } const leafText = getLeafText(element); if (leafText !== undefined) { parts.push(leafText); } // Recursively hash children for (const child of childElements(element)) { parts.push(hashElementDeep(child)); } return sha1(parts.join('|')); } /** * Compare two w:rPr elements for equivalence. * Returns true if they have the same formatting properties. */ function runPropertiesEqual(a, b) { // Both undefined = equal (no formatting) if (!a && !b) return true; // One undefined = not equal if (!a || !b) return false; // Compare by deep hashing (includes children for w:rPr properties) return hashElementDeep(a) === hashElementDeep(b); } /** * Find the nearest `w:hyperlink` ancestor of an atom, or null. * * Boundary normalization must never merge text atoms across a hyperlink * boundary: the surviving atom keeps a single ancestor chain, so a * cross-boundary merge either absorbs adjacent plain text into the link * (formatting bleed) or detaches link text from its wrapper. * * @conformance ECMA-376 edition 5, Part 1 § 17.16.22 * @see https://github.com/UseJunior/safe-docx/issues/368 */ export function nearestHyperlinkAncestor(atom) { for (let i = atom.ancestorElements.length - 1; i >= 0; i--) { const ancestor = atom.ancestorElements[i]; if (ancestor.tagName === 'w:hyperlink') return ancestor; // w:hyperlink always sits between the run and its paragraph; once the // walk reaches w:p there is no hyperlink wrapper. if (ancestor.tagName === 'w:p') break; } return null; } /** * Check if two atoms can be merged into one. * * Atoms can be merged if they: * - Are both w:t (text) elements * - Neither is a collapsed field (fields should stay as separate atoms for finer diff) * - Are in the same paragraph * - Are inside the same w:hyperlink wrapper (or both outside one) * - Have the same run formatting (w:rPr) OR are in the same run * - Have the same revision tracking status * * @param a - First atom * @param b - Second atom (immediately following a) * @returns True if atoms can be merged */ function canMergeAtoms(a, b, options) { // Only merge w:t elements if (a.contentElement.tagName !== 'w:t') return false; if (b.contentElement.tagName !== 'w:t') return false; // Never merge collapsed fields - they should stay as separate atoms for finer-grained diff if (a.collapsedFieldAtoms || b.collapsedFieldAtoms) return false; // Must be in the same paragraph const aPara = a.ancestorElements.find((e) => e.tagName === 'w:p'); const bPara = b.ancestorElements.find((e) => e.tagName === 'w:p'); if (aPara !== bPara) return false; // Must have same revision tracking status const aRevTag = a.revTrackElement?.tagName; const bRevTag = b.revTrackElement?.tagName; if (aRevTag !== bRevTag) return false; // Check if same run (fast path) const aRun = a.ancestorElements.find((e) => e.tagName === 'w:r'); const bRun = b.ancestorElements.find((e) => e.tagName === 'w:r'); if (aRun === bRun) return true; // Different runs - allow cross-run merge only if enabled. // (In inplace mode we disable this so each atom stays anchored to a real run.) if (!options.mergeAcrossRuns) return false; // Never merge across a w:hyperlink boundary — the merged atom keeps only // one side's ancestry, so link text would detach from (or plain text be // absorbed into) the hyperlink wrapper. if (nearestHyperlinkAncestor(a) !== nearestHyperlinkAncestor(b)) return false; // Different runs - check if they have equivalent formatting const aRPr = getRunProperties(a); const bRPr = getRunProperties(b); return runPropertiesEqual(aRPr, bRPr); } /** * Merge source atom's text content into target atom. * * Concatenates text content and recomputes the hash. * * @param target - Atom to merge into * @param source - Atom to merge from */ function mergeIntoAtom(target, source) { // Concatenate text content const newText = (getLeafText(target.contentElement) ?? '') + (getLeafText(source.contentElement) ?? ''); setLeafText(target.contentElement, newText); // Recompute hash target.sha1Hash = hashElement(target.contentElement); } /** * Check if an atom contains only punctuation. */ function isPunctuationOnlyAtom(atom) { if (atom.contentElement.tagName !== 'w:t') return false; const text = getLeafText(atom.contentElement) ?? ''; // Match common punctuation that should attach to adjacent words return /^[,.:;!?'")\]}>]+$/.test(text); } /** * Check if two atoms can be merged for punctuation normalization. * * More permissive than canMergeAtoms - allows merging punctuation with * preceding text even if they're in different runs, as long as they're * in the same paragraph and have the same revision tracking status. */ function canMergePunctuation(a, b, options) { // Only merge w:t elements if (a.contentElement.tagName !== 'w:t') return false; if (b.contentElement.tagName !== 'w:t') return false; // B must be punctuation-only if (!isPunctuationOnlyAtom(b)) return false; // Never merge collapsed fields if (a.collapsedFieldAtoms || b.collapsedFieldAtoms) return false; // Must be in the same paragraph const aPara = a.ancestorElements.find((e) => e.tagName === 'w:p'); const bPara = b.ancestorElements.find((e) => e.tagName === 'w:p'); if (aPara !== bPara) return false; // Must have same revision tracking status const aRevTag = a.revTrackElement?.tagName; const bRevTag = b.revTrackElement?.tagName; if (aRevTag !== bRevTag) return false; // A must end with a word character (not whitespace or punctuation) const aText = getLeafText(a.contentElement) ?? ''; if (!/\w$/.test(aText)) return false; // Never merge across a w:hyperlink boundary: punctuation that follows a // link must not inherit the link run's ancestry/formatting (e.g. the // sentence period after a URL turning underlined). if (nearestHyperlinkAncestor(a) !== nearestHyperlinkAncestor(b)) return false; // If cross-run punctuation merge is disabled, require same run. if (!options.mergePunctuationAcrossRuns) { const aRun = a.ancestorElements.find((e) => e.tagName === 'w:r'); const bRun = b.ancestorElements.find((e) => e.tagName === 'w:r'); if (aRun !== bRun) return false; } return true; } /** * Merge punctuation-only atoms with preceding text. * * This handles cases where documents have different w:t boundaries around * punctuation (e.g., "Conduct" + "," vs "Conduct,"). Punctuation is merged * with the preceding word regardless of run formatting differences. * * @param atoms - Array of atoms * @returns Atoms with punctuation merged into preceding text */ export function mergePunctuationAtoms(atoms, options = { mergePunctuationAcrossRuns: true }) { if (atoms.length === 0) return atoms; const result = []; for (const atom of atoms) { const prev = result[result.length - 1]; if (prev && canMergePunctuation(prev, atom, options)) { // Merge punctuation into previous atom mergeIntoAtom(prev, atom); } else { result.push(atom); } } return result; } /** * Merge contiguous w:t atoms within the same run into single atoms. * * This normalization ensures that identical text split differently across * w:t elements in original vs revised documents will produce matching hashes. * * Example: * Before: ["Def", "initions"] (2 atoms) * After: ["Definitions"] (1 atom) * * @param atoms - Array of atoms from atomization * @returns Normalized array with contiguous text atoms merged */ export function mergeContiguousTextAtoms(atoms, options = { mergeAcrossRuns: true }) { if (atoms.length === 0) return atoms; const result = []; for (const atom of atoms) { const prev = result[result.length - 1]; // Only merge w:t elements in the same run if (prev && canMergeAtoms(prev, atom, options)) { // Merge text content into previous atom mergeIntoAtom(prev, atom); } else { result.push(atom); } } return result; } //# sourceMappingURL=atomizer.js.map