@ansonlai/docx-redline-js 0.1.0

package/engine/format-application.js

@@ -0,0 +1,358 @@
+/**
+ * Formatting application orchestration utilities.
+ *
+ * Applies format-only changes and surgical formatting synchronization over
+ * existing OOXML runs.
+ */
+
+import { mergeFormats } from '../pipeline/markdown-processor.js';
+import { applyFormatOverridesToRPr, extractFormatFromRPr } from './rpr-helpers.js';
+import { snapshotAndAttachRPrChange, injectFormattingToRPr } from './run-builders.js';
+import { getDocumentParagraphs, buildTextSpansFromParagraphs } from './format-extraction.js';
+import { buildParagraphInfos, findTargetParagraphInfo } from './format-paragraph-targeting.js';
+import { splitSpansAtBoundaries, applyFormatHintsToSpansRobust } from './format-span-application.js';
+import { getRevisionTimestamp } from '../core/types.js';
+import { warn, log } from '../adapters/logger.js';
+import { getFirstElementByTag } from '../core/xml-query.js';
+import { getDefaultAuthor } from '../adapters/config.js';
+
+const NS_W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
+
+function isWordElement(node, localName) {
+    if (!node || node.nodeType !== 1) return false;
+    if (node.namespaceURI === NS_W && node.localName === localName) return true;
+    const nodeName = String(node.nodeName || '');
+    return nodeName === `w:${localName}` || nodeName === localName;
+}
+
+function normalizePrecomputedFormatContext(precomputedContext) {
+    if (Array.isArray(precomputedContext)) {
+        return {
+            textSpans: precomputedContext,
+            paragraphs: null,
+            paragraphInfos: null
+        };
+    }
+
+    if (!precomputedContext || typeof precomputedContext !== 'object') {
+        return {
+            textSpans: null,
+            paragraphs: null,
+            paragraphInfos: null
+        };
+    }
+
+    return {
+        textSpans: Array.isArray(precomputedContext.textSpans) ? precomputedContext.textSpans : null,
+        paragraphs: Array.isArray(precomputedContext.paragraphs) ? precomputedContext.paragraphs : null,
+        paragraphInfos: Array.isArray(precomputedContext.paragraphInfos) ? precomputedContext.paragraphInfos : null
+    };
+}
+
+/**
+ * Removes existing core formatting via `w:rPrChange` snapshots and explicit overrides.
+ *
+ * @param {Document} xmlDoc - XML document
+ * @param {Array} textSpans - Text spans (unused, kept for compatibility)
+ * @param {Array} existingFormatHints - Existing formatting hints
+ * @param {XMLSerializer} serializer - Serializer instance
+ * @param {string} author - Change author
+ * @param {boolean} [generateRedlines=true] - Track change toggle
+ * @returns {{ oxml: string, hasChanges: boolean }}
+ */
+export function applyFormatRemovalAsSurgicalReplacement(xmlDoc, textSpans, existingFormatHints, serializer, author, generateRedlines = true) {
+    void textSpans;
+    let hasAnyChanges = false;
+    const processedRuns = new Set();
+    const dateStr = getRevisionTimestamp();
+
+    log(`[OxmlEngine] Surgical format removal: ${existingFormatHints.length} hints to process (using w:rPrChange)`);
+
+    for (const hint of existingFormatHints) {
+        const run = hint.run;
+        if (processedRuns.has(run)) continue;
+        processedRuns.add(run);
+        if (!run.parentNode) continue;
+
+        log('[OxmlEngine] Processing run for surgical format removal, format:', hint.format);
+
+        let rPr = getFirstElementByTag(run, 'w:rPr');
+        if (!rPr) {
+            rPr = xmlDoc.createElement('w:rPr');
+            run.insertBefore(rPr, run.firstChild);
+        }
+
+        if (generateRedlines) {
+            snapshotAndAttachRPrChange(xmlDoc, rPr, author || getDefaultAuthor(), dateStr);
+        }
+
+        applyFormatOverridesToRPr(xmlDoc, rPr, hint.format);
+        hasAnyChanges = true;
+    }
+
+    if (hasAnyChanges) {
+        log('[OxmlEngine] Surgical format removal completed successfully (Pure Format Mode)');
+        return { oxml: serializer.serializeToString(xmlDoc), hasChanges: true };
+    }
+
+    log('[OxmlEngine] No format changes were applied');
+    return { oxml: serializer.serializeToString(xmlDoc), hasChanges: false };
+}
+
+/**
+ * Applies format additions by synchronizing run-level target state after boundary splitting.
+ *
+ * @param {Document} xmlDoc - XML document
+ * @param {Array} textSpans - Extracted text spans
+ * @param {Array} formatHints - Format hints
+ * @param {XMLSerializer} serializer - Serializer instance
+ * @param {string} author - Change author
+ * @param {boolean} [generateRedlines=true] - Track change toggle
+ * @returns {{ oxml: string, hasChanges: boolean }}
+ */
+export function applyFormatAdditionsAsSurgicalReplacement(xmlDoc, textSpans, formatHints, serializer, author, generateRedlines = true) {
+    let hasAnyChanges = false;
+    const processedRuns = new Set();
+
+    if (!textSpans || textSpans.length === 0) {
+        return { oxml: serializer.serializeToString(xmlDoc), hasChanges: false };
+    }
+
+    const boundaries = [];
+    for (const hint of formatHints) {
+        boundaries.push(hint.start, hint.end);
+    }
+    const currentSpans = splitSpansAtBoundaries(xmlDoc, textSpans, boundaries);
+    const orderedSpans = currentSpans
+        .slice()
+        .sort((a, b) => a.charStart - b.charStart || a.charEnd - b.charEnd);
+    const getOverlappingHints = createFormatHintOverlapLookup(formatHints);
+
+    for (const span of orderedSpans) {
+        if (!span || !span.textElement || !isWordElement(span.textElement, 't')) continue;
+
+        const applicableHints = getOverlappingHints(span.charStart, span.charEnd);
+        if (applicableHints.length === 0) continue;
+
+        const mergedDesiredFormat = mergeFormats(...applicableHints.map(h => h.format));
+        const desiredFormat = {
+            bold: !!mergedDesiredFormat.bold,
+            italic: !!mergedDesiredFormat.italic,
+            underline: !!mergedDesiredFormat.underline,
+            strikethrough: !!mergedDesiredFormat.strikethrough
+        };
+
+        const existingFormatRaw = span.format || extractFormatFromRPr(span.rPr);
+        const existingFormat = {
+            bold: !!existingFormatRaw.bold,
+            italic: !!existingFormatRaw.italic,
+            underline: !!existingFormatRaw.underline,
+            strikethrough: !!existingFormatRaw.strikethrough
+        };
+
+        const formatsToCheck = ['bold', 'italic', 'underline', 'strikethrough'];
+        const needsSync = formatsToCheck.some(f => desiredFormat[f] !== existingFormat[f]);
+        if (!needsSync) continue;
+
+        if (processedRuns.has(span.runElement)) continue;
+        processedRuns.add(span.runElement);
+
+        const textContent = span.textElement.textContent || '';
+        if (!textContent) continue;
+
+        const parentNode = span.runElement.parentNode;
+        if (!parentNode) continue;
+
+        const run = span.runElement;
+        const baseRPr = getFirstElementByTag(run, 'w:rPr');
+        const syncedRPr = injectFormattingToRPr(
+            xmlDoc,
+            baseRPr,
+            desiredFormat,
+            author || getDefaultAuthor(),
+            generateRedlines
+        );
+
+        let rPr = baseRPr;
+        if (!rPr) {
+            run.insertBefore(syncedRPr, run.firstChild);
+        } else {
+            while (rPr.firstChild) {
+                rPr.removeChild(rPr.firstChild);
+            }
+            Array.from(syncedRPr.childNodes).forEach(child => rPr.appendChild(child));
+        }
+
+        hasAnyChanges = true;
+    }
+
+    return { oxml: serializer.serializeToString(xmlDoc), hasChanges: hasAnyChanges };
+}
+
+/**
+ * Applies formatting changes to existing text without modifying content.
+ * Used when markdown formatting is applied to unchanged text.
+ *
+ * @param {Document} xmlDoc - XML document
+ * @param {string} originalText - Original plain text
+ * @param {Array} formatHints - Format hints
+ * @param {XMLSerializer} serializer - Serializer instance
+ * @param {string} author - Change author
+ * @param {boolean} [generateRedlines=true] - Track change toggle
+ * @param {Array|Object|null} [precomputedContext=null] - Optional precomputed format context
+ * @returns {{ oxml?: string, hasChanges: boolean, useNativeApi?: boolean, formatHints?: Array, originalText?: string }}
+ */
+export function applyFormatOnlyChanges(xmlDoc, originalText, formatHints, serializer, author, generateRedlines = true, precomputedContext = null) {
+    const precomputed = normalizePrecomputedFormatContext(precomputedContext);
+    const allParagraphs = precomputed.paragraphs || getDocumentParagraphs(xmlDoc);
+
+    let textSpans = precomputed.textSpans || [];
+    if (!precomputed.textSpans) {
+        ({ textSpans } = buildTextSpansFromParagraphs(allParagraphs));
+    }
+
+    if (!textSpans || textSpans.length === 0) {
+        warn('[OxmlEngine] No spans available for format-only change; requesting caller fallback strategy');
+        return {
+            hasChanges: true,
+            useNativeApi: true,
+            formatHints,
+            originalText
+        };
+    }
+
+    if (!formatHints || formatHints.length === 0) {
+        return { oxml: serializer.serializeToString(xmlDoc), hasChanges: false };
+    }
+
+    const paragraphInfos = precomputed.paragraphInfos || buildParagraphInfos(xmlDoc, allParagraphs, textSpans);
+    const { targetInfo, matchOffset } = findTargetParagraphInfo(paragraphInfos, originalText);
+
+    if (!targetInfo || !targetInfo.spans || targetInfo.spans.length === 0) {
+        warn('[OxmlEngine] Unable to pinpoint target paragraph for format-only change; requesting caller fallback strategy');
+        return {
+            hasChanges: true,
+            useNativeApi: true,
+            formatHints,
+            originalText
+        };
+    }
+
+    const baseOffset = targetInfo.spans[0].charStart;
+    const localizedSpans = targetInfo.spans.map(span => ({
+        ...span,
+        charStart: span.charStart - baseOffset,
+        charEnd: span.charEnd - baseOffset
+    }));
+
+    const adjustedHints = formatHints.map(hint => ({
+        ...hint,
+        start: hint.start + matchOffset,
+        end: hint.end + matchOffset
+    }));
+
+    applyFormatHintsToSpansRobust(xmlDoc, localizedSpans, adjustedHints, author, generateRedlines);
+
+    return { oxml: serializer.serializeToString(xmlDoc), hasChanges: true };
+}
+
+/**
+ * Surgical variant of format-only changes.
+ *
+ * @param {Document} xmlDoc - XML document
+ * @param {string} originalText - Original plain text
+ * @param {Array} formatHints - Format hints
+ * @param {XMLSerializer} serializer - Serializer instance
+ * @param {string} author - Change author
+ * @param {boolean} [generateRedlines=true] - Track change toggle
+ * @param {Array|Object|null} [precomputedContext=null] - Optional precomputed format context
+ * @returns {{ oxml?: string, hasChanges: boolean, useNativeApi?: boolean, formatHints?: Array, originalText?: string }}
+ */
+export function applyFormatOnlyChangesSurgical(xmlDoc, originalText, formatHints, serializer, author, generateRedlines = true, precomputedContext = null) {
+    const precomputed = normalizePrecomputedFormatContext(precomputedContext);
+    const allParagraphs = precomputed.paragraphs || getDocumentParagraphs(xmlDoc);
+
+    let textSpans = precomputed.textSpans || [];
+    if (!precomputed.textSpans) {
+        ({ textSpans } = buildTextSpansFromParagraphs(allParagraphs));
+    }
+
+    if (!textSpans || textSpans.length === 0) {
+        warn('[OxmlEngine] No spans available for surgical format-only change; requesting caller fallback strategy');
+        return {
+            hasChanges: true,
+            useNativeApi: true,
+            formatHints,
+            originalText
+        };
+    }
+
+    if (!formatHints || formatHints.length === 0) {
+        return { oxml: serializer.serializeToString(xmlDoc), hasChanges: false };
+    }
+
+    const paragraphInfos = precomputed.paragraphInfos || buildParagraphInfos(xmlDoc, allParagraphs, textSpans);
+    const { targetInfo, matchOffset } = findTargetParagraphInfo(paragraphInfos, originalText);
+
+    if (!targetInfo || !targetInfo.spans || targetInfo.spans.length === 0) {
+        warn('[OxmlEngine] Unable to pinpoint target paragraph for surgical format-only change; requesting caller fallback strategy');
+        return {
+            hasChanges: true,
+            useNativeApi: true,
+            formatHints,
+            originalText
+        };
+    }
+
+    const baseOffset = targetInfo.spans[0].charStart;
+    const localizedSpans = targetInfo.spans.map(span => ({
+        ...span,
+        charStart: span.charStart - baseOffset,
+        charEnd: span.charEnd - baseOffset
+    }));
+
+    const adjustedHints = formatHints.map(hint => ({
+        ...hint,
+        start: hint.start + matchOffset,
+        end: hint.end + matchOffset
+    }));
+
+    return applyFormatAdditionsAsSurgicalReplacement(
+        xmlDoc,
+        localizedSpans,
+        adjustedHints,
+        serializer,
+        author,
+        generateRedlines
+    );
+}
+
+/**
+ * Builds a sweep-line overlap lookup for format hints.
+ *
+ * @param {Array} formatHints - Format hints
+ * @returns {(start:number, end:number)=>Array}
+ */
+function createFormatHintOverlapLookup(formatHints) {
+    const sortedHints = (formatHints || [])
+        .slice()
+        .sort((a, b) => a.start - b.start || a.end - b.end);
+
+    const activeHints = [];
+    let nextHintIndex = 0;
+
+    return (start, end) => {
+        while (nextHintIndex < sortedHints.length && sortedHints[nextHintIndex].start < end) {
+            activeHints.push(sortedHints[nextHintIndex]);
+            nextHintIndex++;
+        }
+
+        for (let i = activeHints.length - 1; i >= 0; i--) {
+            if (activeHints[i].end <= start) {
+                activeHints.splice(i, 1);
+            }
+        }
+
+        return activeHints.filter(hint => hint.start < end && hint.end > start);
+    };
+}

package/engine/format-extraction.js

@@ -0,0 +1,232 @@
+/**
+ * OOXML format extraction utilities.
+ *
+ * Provides shared paragraph filtering, text-span extraction, and run-format
+ * extraction for formatting-aware reconciliation flows.
+ */
+
+import { extractFormatFromRPr } from './rpr-helpers.js';
+import { advanceOffsetForParagraphBoundary } from '../core/paragraph-offset-policy.js';
+import { log } from '../adapters/logger.js';
+import { getElementsByTag, getElementsByTagNS, getFirstElementByTag } from '../core/xml-query.js';
+
+const NS_W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
+
+function isWordElement(node, localName) {
+    if (!node || node.nodeType !== 1) return false;
+    if (node.namespaceURI === NS_W && node.localName === localName) return true;
+    const nodeName = String(node.nodeName || '');
+    return nodeName === `w:${localName}` || nodeName === localName;
+}
+
+function isExcludedRevisionContainer(node) {
+    if (!node || node.nodeType !== 1 || node.namespaceURI !== NS_W) return false;
+    return node.localName === 'del' || node.localName === 'moveFrom';
+}
+
+function collectParagraphRuns(paragraph) {
+    const runs = [];
+    const stack = Array.from(paragraph?.childNodes || []).reverse();
+
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (!node || node.nodeType !== 1) continue;
+        if (isExcludedRevisionContainer(node)) continue;
+
+        if (isWordElement(node, 'r')) {
+            runs.push(node);
+            continue;
+        }
+
+        const children = Array.from(node.childNodes || []);
+        for (let i = children.length - 1; i >= 0; i -= 1) {
+            stack.push(children[i]);
+        }
+    }
+
+    return runs;
+}
+
+/**
+ * Returns only document body paragraphs, excluding comments/footnotes/endnotes.
+ *
+ * @param {Document} xmlDoc - XML document
+ * @returns {Element[]}
+ */
+export function getDocumentParagraphs(xmlDoc) {
+    const excludedContainers = new Set(['comment', 'footnote', 'endnote']);
+    const allParagraphs = getElementsByTagNS(xmlDoc, '*', 'p');
+
+    return allParagraphs.filter(p => {
+        let node = p.parentNode;
+        while (node && node.nodeName) {
+            const localName = String(node.localName || '').toLowerCase();
+            if (excludedContainers.has(localName)) {
+                return false;
+            }
+            node = node.parentNode;
+        }
+        return true;
+    });
+}
+
+/**
+ * Builds linear text spans from paragraph elements.
+ *
+ * @param {Element[]} paragraphs - Paragraph nodes
+ * @returns {{ textSpans: Array, charOffset: number }}
+ */
+export function buildTextSpansFromParagraphs(paragraphs) {
+    const textSpans = [];
+    let charOffset = 0;
+
+    for (let pIndex = 0; pIndex < paragraphs.length; pIndex++) {
+        const p = paragraphs[pIndex];
+        const runs = collectParagraphRuns(p);
+        for (const run of runs) {
+            const rPr = getFirstElementByTag(run, 'w:rPr');
+            Array.from(run.childNodes || []).forEach(rc => {
+                if (isWordElement(rc, 't')) {
+                    const text = rc.textContent || '';
+                    if (text.length > 0) {
+                        textSpans.push({
+                            charStart: charOffset,
+                            charEnd: charOffset + text.length,
+                            textElement: rc,
+                            runElement: run,
+                            paragraph: p,
+                            container: run.parentNode,
+                            rPr
+                        });
+                        charOffset += text.length;
+                    }
+                } else if (isWordElement(rc, 'br') || isWordElement(rc, 'cr') || isWordElement(rc, 'tab') || isWordElement(rc, 'noBreakHyphen')) {
+                    textSpans.push({
+                        charStart: charOffset,
+                        charEnd: charOffset + 1,
+                        textElement: rc,
+                        runElement: run,
+                        paragraph: p,
+                        container: run.parentNode,
+                        rPr
+                    });
+                    charOffset += 1;
+                }
+            });
+        }
+        charOffset = advanceOffsetForParagraphBoundary(charOffset, pIndex, paragraphs.length);
+    }
+
+    return { textSpans, charOffset };
+}
+
+/**
+ * Processes a single run element and appends extracted spans/hints.
+ *
+ * @param {Element} run - `w:r` element
+ * @param {Element} paragraph - Parent paragraph
+ * @param {number} charOffset - Start offset
+ * @param {Array} textSpans - Span collection (mutated)
+ * @param {Array} formatHints - Format hint collection (mutated)
+ * @param {Object|null} pFormat - Paragraph-level run format defaults
+ * @returns {number}
+ */
+export function processRunForFormatting(run, paragraph, charOffset, textSpans, formatHints, pFormat = null) {
+    let rPr = null;
+    for (const child of Array.from(run.childNodes)) {
+        if (isWordElement(child, 'rPr')) {
+            rPr = child;
+            break;
+        }
+    }
+
+    const format = extractFormatFromRPr(rPr);
+
+    if (pFormat) {
+        if (pFormat.bold && !format.bold) format.bold = true;
+        if (pFormat.italic && !format.italic) format.italic = true;
+        if (pFormat.underline && !format.underline) format.underline = true;
+        if (pFormat.strikethrough && !format.strikethrough) format.strikethrough = true;
+    }
+
+    format.hasFormatting = format.bold || format.italic || format.underline || format.strikethrough;
+
+    let currentOffset = charOffset;
+    for (const child of Array.from(run.childNodes)) {
+        if (isWordElement(child, 't')) {
+            const text = child.textContent || '';
+            if (text.length > 0) {
+                const start = currentOffset;
+                const end = currentOffset + text.length;
+
+                textSpans.push({
+                    charStart: start,
+                    charEnd: end,
+                    textElement: child,
+                    runElement: run,
+                    paragraph,
+                    rPr,
+                    format: { ...format }
+                });
+
+                if (format.hasFormatting) {
+                    formatHints.push({
+                        start,
+                        end,
+                        format: { ...format },
+                        run,
+                        rPr
+                    });
+                }
+
+                currentOffset = end;
+            }
+        }
+    }
+
+    return currentOffset;
+}
+
+/**
+ * Extracts existing formatting hints from OOXML paragraph runs.
+ *
+ * @param {Document} xmlDoc - XML document
+ * @returns {{ existingFormatHints: Array, textSpans: Array, paragraphs: Element[] }}
+ */
+export function extractFormattingFromOoxml(xmlDoc) {
+    const existingFormatHints = [];
+    const textSpans = [];
+    let charOffset = 0;
+
+    const paragraphs = getDocumentParagraphs(xmlDoc);
+
+    for (let pIndex = 0; pIndex < paragraphs.length; pIndex++) {
+        const p = paragraphs[pIndex];
+        let pRPr = null;
+        for (const child of Array.from(p.childNodes)) {
+            if (isWordElement(child, 'pPr')) {
+                for (const pChild of Array.from(child.childNodes)) {
+                    if (isWordElement(pChild, 'rPr')) {
+                        pRPr = pChild;
+                        break;
+                    }
+                }
+                break;
+            }
+        }
+
+        const pFormat = extractFormatFromRPr(pRPr);
+        if (pFormat.hasFormatting) {
+            log(`[OxmlEngine] Found paragraph-level formatting: ${JSON.stringify(pFormat)}`);
+        }
+
+        const runs = collectParagraphRuns(p);
+        for (const run of runs) {
+            charOffset = processRunForFormatting(run, p, charOffset, textSpans, existingFormatHints, pFormat);
+        }
+        charOffset = advanceOffsetForParagraphBoundary(charOffset, pIndex, paragraphs.length);
+    }
+
+    log(`[OxmlEngine] Extracted ${textSpans.length} text spans, ${existingFormatHints.length} format hints`);
+    return { existingFormatHints, textSpans, paragraphs };
+}