open-agreements
Version:
Open-source legal template filling CLI and library
339 lines • 12.6 kB
JavaScript
/**
* Format Change Detection Module
*
* Detects formatting changes (bold, italic, font size, etc.) between
* documents after LCS comparison. Runs on atoms marked as Equal to
* identify text that matches but has different formatting.
*
* Pipeline position:
* LCS() → FlattenToAtomList() → detectMovesInAtomList() → detectFormatChangesInAtomList() → CoalesceRecurse()
*
* @see design.md Decision 10: Format Change Detection as Post-LCS Phase
*/
import { CorrelationStatus, DEFAULT_FORMAT_DETECTION_SETTINGS, RUN_PROPERTY_FRIENDLY_NAMES, } from './core-types.js';
import { getLeafText, childElements } from './primitives/index.js';
import { parseXml } from './primitives/xml.js';
// =============================================================================
// Run Property Extraction
// =============================================================================
/**
* Extract run properties (w:rPr) from an atom's ancestor elements.
*
* Finds the w:r (run) element in ancestors and extracts its w:rPr child.
*
* @param atom - The atom to extract properties from
* @returns The w:rPr element, or null if not found
*
* @example
* // For an atom inside <w:r><w:rPr><w:b/></w:rPr><w:t>text</w:t></w:r>
* // Returns the <w:rPr><w:b/></w:rPr> element
*/
export function getRunPropertiesFromAtom(atom) {
// Find the w:r ancestor element
const runElement = atom.ancestorElements?.find((a) => a.tagName === 'w:r');
if (!runElement) {
return null;
}
// Get the rPr child element
for (const child of childElements(runElement)) {
if (child.tagName === 'w:rPr')
return child;
}
return null;
}
function extractNormalizedProperties(rPr) {
if (!rPr) {
return { children: [] };
}
const normalizedChildren = childElements(rPr)
// Remove revision tracking elements
.filter((e) => e.tagName !== 'w:rPrChange')
// Sort by tag name for deterministic comparison
.sort((a, b) => a.tagName.localeCompare(b.tagName))
// Normalize each child
.map((e) => {
const attrs = [];
for (let i = 0; i < e.attributes.length; i++) {
const attr = e.attributes[i];
attrs.push([attr.name, attr.value]);
}
attrs.sort(([a], [b]) => a.localeCompare(b));
const text = getLeafText(e);
const prop = { tagName: e.tagName, attrs };
if (text !== undefined)
prop.text = text;
return prop;
});
return { children: normalizedChildren };
}
// =============================================================================
// Run Property Comparison
// =============================================================================
/**
* Serialize normalized properties to a string for comparison.
*/
function serializeNormalizedProperties(rPr) {
const parts = [];
for (const child of rPr.children) {
const attrs = child.attrs
.map(([k, v]) => `${k}="${v}"`)
.join(' ');
const textPart = child.text ? `|${child.text}` : '';
parts.push(`<${child.tagName} ${attrs}${textPart}/>`);
}
return parts.join('');
}
/**
* Check if two run properties are equal after normalization.
*/
export function areRunPropertiesEqual(rPr1, rPr2) {
const norm1 = extractNormalizedProperties(rPr1);
const norm2 = extractNormalizedProperties(rPr2);
return serializeNormalizedProperties(norm1) === serializeNormalizedProperties(norm2);
}
// Keep legacy overload for callers that pass WmlElement (= Element)
export { areRunPropertiesEqual as areNormalizedRunPropertiesEqual };
// =============================================================================
// Changed Property Detection
// =============================================================================
/**
* Get the set of property tag names from a normalized rPr.
*/
function getPropertyTagNames(rPr) {
return new Set(rPr.children.map((c) => c.tagName));
}
/**
* Find a property element by tag name in a normalized rPr.
*/
function findPropertyByTag(rPr, tagName) {
return rPr.children.find((c) => c.tagName === tagName);
}
/**
* Check if two property elements have the same value.
*/
function arePropertiesValueEqual(prop1, prop2) {
if (!prop1 && !prop2)
return true;
if (!prop1 || !prop2)
return false;
const str1 = serializeNormalizedProperties({ children: [prop1] });
const str2 = serializeNormalizedProperties({ children: [prop2] });
return str1 === str2;
}
/**
* Get the list of property names that changed between two run properties.
*
* Returns friendly names (e.g., "bold", "italic") when available,
* otherwise returns the OOXML tag name.
*
* @param oldRPr - Old run properties element (or null)
* @param newRPr - New run properties element (or null)
* @returns Array of changed property names
*/
export function getChangedPropertyNames(oldRPr, newRPr) {
const changed = [];
const normalizedOld = extractNormalizedProperties(oldRPr);
const normalizedNew = extractNormalizedProperties(newRPr);
const oldTags = getPropertyTagNames(normalizedOld);
const newTags = getPropertyTagNames(normalizedNew);
// All unique tags from both
const allTags = new Set([...oldTags, ...newTags]);
for (const tag of allTags) {
const oldProp = findPropertyByTag(normalizedOld, tag);
const newProp = findPropertyByTag(normalizedNew, tag);
if (!arePropertiesValueEqual(oldProp, newProp)) {
// Use friendly name if available
const friendlyName = RUN_PROPERTY_FRIENDLY_NAMES[tag] ?? tag;
changed.push(friendlyName);
}
}
return changed.sort();
}
/**
* Categorize changed properties into added, removed, and modified.
*
* @param oldRPr - Old run properties element (or null)
* @param newRPr - New run properties element (or null)
* @returns Object with added, removed, and changed arrays
*/
export function categorizePropertyChanges(oldRPr, newRPr) {
const added = [];
const removed = [];
const changed = [];
const normalizedOld = extractNormalizedProperties(oldRPr);
const normalizedNew = extractNormalizedProperties(newRPr);
const oldTags = getPropertyTagNames(normalizedOld);
const newTags = getPropertyTagNames(normalizedNew);
// Check for added properties (in new but not old)
for (const tag of newTags) {
if (!oldTags.has(tag)) {
const friendlyName = RUN_PROPERTY_FRIENDLY_NAMES[tag] ?? tag;
added.push(friendlyName);
}
}
// Check for removed properties (in old but not new)
for (const tag of oldTags) {
if (!newTags.has(tag)) {
const friendlyName = RUN_PROPERTY_FRIENDLY_NAMES[tag] ?? tag;
removed.push(friendlyName);
}
}
// Check for changed properties (in both but different value)
for (const tag of oldTags) {
if (newTags.has(tag)) {
const oldProp = findPropertyByTag(normalizedOld, tag);
const newProp = findPropertyByTag(normalizedNew, tag);
if (!arePropertiesValueEqual(oldProp, newProp)) {
const friendlyName = RUN_PROPERTY_FRIENDLY_NAMES[tag] ?? tag;
changed.push(friendlyName);
}
}
}
return {
added: added.sort(),
removed: removed.sort(),
changed: changed.sort(),
};
}
// =============================================================================
// Main Algorithm
// =============================================================================
/**
* Detect format changes in a flat list of atoms.
*
* Runs after LCS and move detection to identify Equal atoms where the text
* matches but formatting differs. Updates atoms in place with format change status.
*
* @param atoms - The atom list to process (modified in place)
* @param settings - Format detection settings (optional, uses defaults)
*/
export function detectFormatChangesInAtomList(atoms, settings = DEFAULT_FORMAT_DETECTION_SETTINGS) {
if (!settings.detectFormatChanges) {
return;
}
for (const atom of atoms) {
// Only check Equal atoms that have a "before" reference
if (atom.correlationStatus !== CorrelationStatus.Equal) {
continue;
}
if (!atom.comparisonUnitAtomBefore) {
continue;
}
// Extract rPr from both documents
const oldRPr = getRunPropertiesFromAtom(atom.comparisonUnitAtomBefore);
const newRPr = getRunPropertiesFromAtom(atom);
// Compare run properties
if (!areRunPropertiesEqual(oldRPr, newRPr)) {
atom.correlationStatus = CorrelationStatus.FormatChanged;
atom.formatChange = {
oldRunProperties: oldRPr,
newRunProperties: newRPr,
changedProperties: getChangedPropertyNames(oldRPr, newRPr),
};
}
}
}
/**
* Merge format change markup into a run's existing rPr element.
*
* Adds the w:rPrChange element as the last child of w:rPr.
*
* @param runElement - The w:r element to modify
* @param rPrChange - The w:rPrChange element to insert
*/
export function mergeFormatChangeIntoRun(runElement, rPrChange) {
if (runElement.tagName !== 'w:r') {
return;
}
// Find existing rPr
let rPr = null;
for (const child of childElements(runElement)) {
if (child.tagName === 'w:rPr') {
rPr = child;
break;
}
}
if (!rPr) {
// Create rPr as first child
const doc = runElement.ownerDocument;
rPr = doc.createElementNS('http://schemas.openxmlformats.org/wordprocessingml/2006/main', 'w:rPr');
runElement.insertBefore(rPr, runElement.firstChild);
}
// Add rPrChange as last child of rPr
rPr.appendChild(rPrChange);
}
// =============================================================================
// Paragraph Property Change Support (Future Enhancement)
// =============================================================================
/**
* Extract paragraph properties (w:pPr) from an element.
*
* @param paragraphElement - The w:p element
* @returns The w:pPr element, or null if not found
*/
export function getParagraphProperties(paragraphElement) {
if (paragraphElement.tagName !== 'w:p') {
return null;
}
for (const child of childElements(paragraphElement)) {
if (child.tagName === 'w:pPr')
return child;
}
return null;
}
/**
* Paragraph property friendly names.
*/
export const PARAGRAPH_PROPERTY_FRIENDLY_NAMES = {
'w:jc': 'alignment',
'w:ind': 'indentation',
'w:spacing': 'spacing',
'w:pStyle': 'style',
'w:numPr': 'numbering',
'w:pBdr': 'borders',
'w:shd': 'shading',
'w:tabs': 'tabs',
'w:keepNext': 'keepWithNext',
'w:keepLines': 'keepLinesTogether',
'w:pageBreakBefore': 'pageBreakBefore',
'w:widowControl': 'widowControl',
'w:outlineLvl': 'outlineLevel',
};
// =============================================================================
// Legacy API — kept for backward compatibility during migration
// =============================================================================
/**
* @deprecated Use areRunPropertiesEqual directly with Element params
*/
export function normalizeRunProperties(rPr) {
return extractNormalizedProperties(rPr);
}
/**
* @deprecated Use getParagraphProperties directly
*/
export function normalizeParagraphProperties(pPr) {
return extractNormalizedProperties(pPr);
}
/**
* @deprecated Removed — use generateFormatChangeMarkup with DOM approach
*/
export function generateFormatChangeMarkup(formatChange, options) {
const doc = parseXml('<root/>');
const dateStr = options.dateTime.toISOString();
const W_NS = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
const rPrChange = doc.createElementNS(W_NS, 'w:rPrChange');
rPrChange.setAttribute('w:id', options.id.toString());
rPrChange.setAttribute('w:author', options.author);
rPrChange.setAttribute('w:date', dateStr);
const rPr = doc.createElementNS(W_NS, 'w:rPr');
rPrChange.appendChild(rPr);
if (formatChange.oldRunProperties) {
for (const child of childElements(formatChange.oldRunProperties)) {
if (child.tagName === 'w:rPrChange')
continue;
rPr.appendChild(child.cloneNode(true));
}
}
return rPrChange;
}
//# sourceMappingURL=format-detection.js.map