open-agreements
Version:
Open-source legal template filling CLI and library
1,002 lines • 39.2 kB
JavaScript
/**
* 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