@ansonlai/docx-redline-js 0.4.0 → 0.5.1

package/core/paragraph-text.js

@@ -0,0 +1,209 @@
+import { NS_W } from './types.js';
+
+function localName(node) {
+    return String(node?.localName || node?.nodeName || '').replace(/^.*:/, '');
+}
+
+/** Returns whether a node contributes to the selected revision view. */
+export function isNodeVisibleInRevisionView(node, boundary = null, revisionView = 'accepted') {
+    const view = revisionView === 'current' ? 'accepted' : revisionView;
+    let cursor = node;
+    while (cursor && cursor !== boundary) {
+        const name = localName(cursor);
+        if (view === 'accepted' && (name === 'del' || name === 'moveFrom')) return false;
+        if (view === 'rejected' && (name === 'ins' || name === 'moveTo')) return false;
+        cursor = cursor.parentNode;
+    }
+    return true;
+}
+
+/** Reads exact visible text from a run, including tabs, breaks and non-breaking hyphens. */
+export function readCanonicalRunText(run, options = {}) {
+    const revisionView = options.revisionView === 'current' ? 'accepted' : (options.revisionView || 'accepted');
+    const boundary = options.boundary || null;
+    if (!isNodeVisibleInRevisionView(run, boundary, revisionView)) return '';
+    let text = '';
+    const visit = node => {
+        for (const child of Array.from(node?.childNodes || [])) {
+            if (child?.nodeType !== 1 || (child.namespaceURI && child.namespaceURI !== NS_W)) continue;
+            if (!isNodeVisibleInRevisionView(child, boundary, revisionView)) continue;
+            const name = localName(child);
+            if (name === 't' || (name === 'delText' && revisionView === 'rejected')) text += child.textContent || '';
+            else if (name === 'tab') text += '\t';
+            else if (name === 'br' || name === 'cr') text += '\n';
+            else if (name === 'noBreakHyphen') text += '\u2011';
+            else if (name === 'softHyphen') text += '\u00ad';
+            else visit(child);
+        }
+    };
+    visit(run);
+    return text;
+}
+
+const attr = (node, name) => node?.getAttribute?.(`w:${name}`) || node?.getAttribute?.(name) || '';
+
+/**
+ * Extracts revision-view text segments from a paragraph or container node.
+ *
+ * Emits structural text pieces tracking revision ancestry (ins, del, moveFrom, moveTo),
+ * computes independent accepted and rejected UTF-16 cursor offsets, and merges
+ * adjacent pieces with compatible carrier containers and revision metadata.
+ *
+ * @param {Element | null | undefined} paragraph - Paragraph or container element
+ * @param {Object} [options={}] - Extraction options
+ * @param {boolean} [options.mergeRuns=true] - Merge adjacent runs sharing compatible container and revision metadata
+ * @returns {Array<{ text: string, kind: 'baseline' | 'insertion' | 'deletion' | 'move_from' | 'move_to', author?: string, revisionId?: string, acceptedStart: number | null, rejectedStart: number | null }>}
+ */
+export function extractParagraphRevisionSegments(paragraph, options = {}) {
+    if (!paragraph) return [];
+
+    const rawPieces = [];
+
+    function walk(node, currentRevision, currentCarrier) {
+        for (const child of Array.from(node?.childNodes || [])) {
+            if (child?.nodeType !== 1) continue;
+            if (child.namespaceURI && child.namespaceURI !== NS_W) continue;
+
+            const name = localName(child);
+            if (name === 'pPr' || name === 'rPr') continue;
+
+            let nextRevision = currentRevision;
+            if (name === 'ins') {
+                nextRevision = {
+                    kind: 'insertion',
+                    author: attr(child, 'author') || undefined,
+                    revisionId: attr(child, 'id') || undefined
+                };
+            } else if (name === 'del') {
+                nextRevision = {
+                    kind: 'deletion',
+                    author: attr(child, 'author') || undefined,
+                    revisionId: attr(child, 'id') || undefined
+                };
+            } else if (name === 'moveFrom') {
+                nextRevision = {
+                    kind: 'move_from',
+                    author: attr(child, 'author') || undefined,
+                    revisionId: attr(child, 'id') || undefined
+                };
+            } else if (name === 'moveTo') {
+                nextRevision = {
+                    kind: 'move_to',
+                    author: attr(child, 'author') || undefined,
+                    revisionId: attr(child, 'id') || undefined
+                };
+            }
+
+            let nextCarrier = currentCarrier;
+            if (name === 'r') {
+                nextCarrier = child;
+            }
+
+            let text = null;
+            let kind = nextRevision ? nextRevision.kind : 'baseline';
+            let author = nextRevision?.author;
+            let revisionId = nextRevision?.revisionId;
+
+            if (name === 't') {
+                text = child.textContent || '';
+            } else if (name === 'delText') {
+                text = child.textContent || '';
+                if (!nextRevision) {
+                    kind = 'deletion';
+                }
+            } else if (name === 'tab') {
+                text = '\t';
+            } else if (name === 'br' || name === 'cr') {
+                text = '\n';
+            } else if (name === 'noBreakHyphen') {
+                text = '\u2011';
+            } else if (name === 'softHyphen') {
+                text = '\u00ad';
+            }
+
+            if (text !== null) {
+                if (text.length > 0) {
+                    rawPieces.push({
+                        text,
+                        kind,
+                        author,
+                        revisionId,
+                        carrier: nextCarrier || child,
+                        carrierContainer: (nextCarrier || child)?.parentNode || null
+                    });
+                }
+            } else {
+                walk(child, nextRevision, nextCarrier);
+            }
+        }
+    }
+
+    const initialCarrier = localName(paragraph) === 'r' ? paragraph : null;
+    walk(paragraph, null, initialCarrier);
+
+    if (rawPieces.length === 0) return [];
+
+    const mergeRuns = options.mergeRuns !== false;
+    const merged = [];
+    let current = null;
+
+    for (const piece of rawPieces) {
+        if (!current) {
+            current = { ...piece };
+            continue;
+        }
+
+        const sameKind = current.kind === piece.kind;
+        const sameAuthor = current.author === piece.author;
+        const sameRevisionId = current.revisionId === piece.revisionId;
+        const sameCarrier = current.carrier === piece.carrier;
+        const compatibleContainer = mergeRuns && current.carrierContainer === piece.carrierContainer;
+
+        if (sameKind && sameAuthor && sameRevisionId && (sameCarrier || compatibleContainer)) {
+            current.text += piece.text;
+        } else {
+            merged.push(current);
+            current = { ...piece };
+        }
+    }
+    if (current) merged.push(current);
+
+    let acceptedCursor = 0;
+    let rejectedCursor = 0;
+    const segments = [];
+
+    for (const item of merged) {
+        const isAccepted = item.kind !== 'deletion' && item.kind !== 'move_from';
+        const isRejected = item.kind !== 'insertion' && item.kind !== 'move_to';
+
+        const acceptedStart = isAccepted ? acceptedCursor : null;
+        const rejectedStart = isRejected ? rejectedCursor : null;
+
+        if (isAccepted) acceptedCursor += item.text.length;
+        if (isRejected) rejectedCursor += item.text.length;
+
+        const segment = {
+            text: item.text,
+            kind: item.kind,
+            acceptedStart,
+            rejectedStart
+        };
+        if (item.author !== undefined) segment.author = item.author;
+        if (item.revisionId !== undefined) segment.revisionId = item.revisionId;
+
+        segments.push(segment);
+    }
+
+    return segments;
+}
+
+/** Canonical exact paragraph text used by inspection, targeting and ingestion. */
+export function extractCanonicalParagraphText(paragraph, options = {}) {
+    if (!paragraph) return '';
+    const view = options.revisionView === 'current' ? 'accepted' : (options.revisionView || 'accepted');
+    const segments = extractParagraphRevisionSegments(paragraph, options);
+    if (view === 'rejected') {
+        return segments.filter(s => s.rejectedStart !== null).map(s => s.text).join('');
+    }
+    return segments.filter(s => s.acceptedStart !== null).map(s => s.text).join('');
+}

package/core/redline-validation.js

@@ -3,8 +3,9 @@
  *
  * Mirrors the invariants enforced by the test-suite round-trip harness so
  * downstream consumers can verify output before writing it into a package:
- * no nested revisions, deleted text uses w:delText, revision metadata is
- * complete, revision ids are unique, and boundary whitespace is preserved.
+ * only schema-permitted nested revisions, deleted text uses w:delText,
+ * revision metadata is complete, revision ids are unique, and boundary
+ * whitespace is preserved.
  */
 
 import { parseXml } from '../adapters/xml-adapter.js';
@@ -107,13 +108,18 @@ export function validateRedlineOoxml(oxml) {
         }
     }
 
-    // No w:ins/w:del nested inside another w:ins/w:del.
+    // A w:del may be a direct revision child of w:ins. All other insertion /
+    // deletion nesting is rejected, including deeper revisions inside that del.
     for (const revision of revisions) {
         const nested = Array.from(revision.getElementsByTagName('*'))
             .filter(el => el !== revision && ['ins', 'del'].includes(localNameOf(el)));
-        if (nested.length > 0) {
+        const invalidNested = nested.find(candidate => {
+            if (localNameOf(revision) !== 'ins' || localNameOf(candidate) !== 'del') return true;
+            return candidate.parentNode !== revision;
+        });
+        if (invalidNested) {
             addIssue('NESTED_REVISION', 'error',
-                `<${revision.nodeName}> (w:id="${wordAttribute(revision, 'id')}") contains nested <${nested[0].nodeName}>.`);
+                `<${revision.nodeName}> (w:id="${wordAttribute(revision, 'id')}") contains invalid nested <${invalidNested.nodeName}>.`);
         }
     }
 

package/core/revision-cloning.js

@@ -0,0 +1,38 @@
+import {
+    NS_W,
+    RevisionIdAllocator,
+    createRevisionIdAllocator,
+    getRevisionIdAllocatorForDocument
+} from './types.js';
+import { isWordElement } from './word-xml.js';
+
+/**
+ * Assigns fresh document-scoped IDs to w:rPrChange elements in a cloned
+ * run-properties subtree. This preserves formatting-revision metadata while
+ * preventing a DOM split from duplicating the original revision ID.
+ *
+ * @param {Element} root - Cloned subtree whose revision IDs should be refreshed
+ * @param {RevisionIdAllocator|null} [allocator=null] - Document-scoped allocator
+ * @returns {Element}
+ */
+export function refreshRunPropertyChangeIds(root, allocator = null) {
+    if (!root) return root;
+
+    const xmlDoc = root.nodeType === 9 ? root : root.ownerDocument;
+    const resolvedAllocator = allocator instanceof RevisionIdAllocator
+        ? allocator
+        : (getRevisionIdAllocatorForDocument(xmlDoc) || createRevisionIdAllocator(xmlDoc));
+    const candidates = [root, ...Array.from(root.getElementsByTagName?.('*') || [])];
+
+    for (const node of candidates) {
+        if (!isWordElement(node, 'rPrChange')) continue;
+        const nextId = String(resolvedAllocator.next());
+        if (typeof node.setAttributeNS === 'function') {
+            node.setAttributeNS(NS_W, 'w:id', nextId);
+        } else {
+            node.setAttribute('w:id', nextId);
+        }
+    }
+
+    return root;
+}

package/core/types.js

@@ -202,15 +202,24 @@ export class RevisionIdAllocator {
 
     seed(xmlDoc) {
         let maxFound = -1;
-        const elements = Array.from(xmlDoc?.getElementsByTagName?.('*') || []);
-        if (xmlDoc?.nodeType === 1) elements.unshift(xmlDoc);
+        const traversalRoot = xmlDoc?.nodeType === 9 ? xmlDoc.documentElement : xmlDoc;
+        let node = traversalRoot || null;
 
-        for (const element of elements) {
-            if (!isRevisionIdElement(element)) continue;
-            const id = readWordId(element);
-            if (id == null) continue;
-            this.occupiedIds.add(id);
-            maxFound = Math.max(maxFound, id);
+        while (node) {
+            if (isRevisionIdElement(node)) {
+                const id = readWordId(node);
+                if (id != null) {
+                    this.occupiedIds.add(id);
+                    maxFound = Math.max(maxFound, id);
+                }
+            }
+
+            if (node.firstChild) {
+                node = node.firstChild;
+                continue;
+            }
+            while (node && node !== traversalRoot && !node.nextSibling) node = node.parentNode;
+            node = node && node !== traversalRoot ? node.nextSibling : null;
         }
 
         const highRiskBoundary = MAX_PRACTICAL_REVISION_ID - REVISION_ID_SAFETY_MARGIN;
@@ -286,7 +295,7 @@ export function getRevisionTimestamp(date = new Date()) {
  * @param {RevisionIdAllocator|Document|Element|null} [allocatorOrNode] - Scoped allocator or registered OOXML node
  * @returns {{ id: number, author: string, date: string }}
  */
-export function createRevisionMetadata(author, allocatorOrNode = null) {
+export function createRevisionMetadata(author, allocatorOrNode = null, kind = null) {
     const resolvedAuthor = typeof author === 'string' && author.trim()
         ? author.trim()
         : getDefaultAuthor();
@@ -294,13 +303,58 @@ export function createRevisionMetadata(author, allocatorOrNode = null) {
         ? allocatorOrNode
         : (getRevisionIdAllocatorForDocument(allocatorOrNode) || defaultRevisionIdAllocator);
 
+    const id = allocator.next();
+    if (allocator._receiptCollector) {
+        allocator._receiptCollector.recordRevision(id, kind || 'structural');
+    }
+
     return {
-        id: allocator.next(),
+        id,
         author: resolvedAuthor,
         date: getRevisionTimestamp()
     };
 }
 
+/**
+ * @typedef {Object} ReplacementRevisionEvent
+ * @property {number} deletionId - Unique revision ID for deletion
+ * @property {number} insertionId - Unique revision ID for insertion
+ * @property {string} author - Change author
+ * @property {string} date - Shared ISO timestamp
+ */
+
+/**
+ * Creates paired revision metadata for a replacement event.
+ * Allocates two unique IDs but shares author and timestamp.
+ *
+ * @param {string} [author]
+ * @param {RevisionIdAllocator|Document|Element|null} [allocatorOrNode=null]
+ * @returns {ReplacementRevisionEvent}
+ */
+export function createReplacementRevisionEvent(author, allocatorOrNode = null) {
+    const resolvedAuthor = typeof author === 'string' && author.trim()
+        ? author.trim()
+        : getDefaultAuthor();
+    const allocator = allocatorOrNode instanceof RevisionIdAllocator
+        ? allocatorOrNode
+        : (getRevisionIdAllocatorForDocument(allocatorOrNode) || defaultRevisionIdAllocator);
+    const date = getRevisionTimestamp();
+    const deletionId = allocator.next();
+    const insertionId = allocator.next();
+
+    if (allocator._receiptCollector) {
+        allocator._receiptCollector.recordRevision(deletionId, 'del');
+        allocator._receiptCollector.recordRevision(insertionId, 'ins');
+    }
+
+    return {
+        deletionId,
+        insertionId,
+        author: resolvedAuthor,
+        date
+    };
+}
+
 /**
  * Seeds the revision ID counter above any existing Word revision/comment id values.
  *

package/core/word-xml.js

@@ -33,6 +33,27 @@ function wordElementsByLocalName(xmlDoc, localName) {
     return Array.from(xmlDoc?.getElementsByTagName?.('*') || []).filter(node => isWordElement(node, localName));
 }
 
+// Keep revision discovery and author discovery on the same taxonomy. Cell
+// markers are included for fail-closed detection even though selective
+// acceptance/rejection of those structural revisions is not yet supported.
+const TRACKED_CHANGE_NAMES = [
+    'ins',
+    'del',
+    'moveFrom',
+    'moveTo',
+    'moveFromRangeStart',
+    'moveFromRangeEnd',
+    'moveToRangeStart',
+    'moveToRangeEnd',
+    'rPrChange',
+    'pPrChange',
+    'tblPrChange',
+    'trPrChange',
+    'tcPrChange',
+    'cellIns',
+    'cellDel'
+];
+
 /**
  * Returns true if a document or fragment contains Word tracked-change markup.
  *
@@ -40,22 +61,29 @@ function wordElementsByLocalName(xmlDoc, localName) {
  * @returns {boolean}
  */
 export function containsTrackedChanges(xmlDoc) {
-    const trackedChangeNames = [
-        'ins',
-        'del',
-        'moveFrom',
-        'moveTo',
-        'moveFromRangeStart',
-        'moveFromRangeEnd',
-        'moveToRangeStart',
-        'moveToRangeEnd',
-        'rPrChange',
-        'pPrChange',
-        'cellIns',
-        'cellDel'
-    ];
+    return TRACKED_CHANGE_NAMES.some(localName => wordElementsByLocalName(xmlDoc, localName).length > 0);
+}
 
-    return trackedChangeNames.some(localName => wordElementsByLocalName(xmlDoc, localName).length > 0);
+/**
+ * Collects all distinct author names from tracked changes in the given XML document or element.
+ *
+ * @param {Document|Element|null|undefined} xmlDocOrElement
+ * @returns {string[]} Sorted unique list of author names.
+ */
+export function getTrackedChangeAuthors(xmlDocOrElement) {
+    if (!xmlDocOrElement) return [];
+    const authors = new Set();
+    for (const localName of TRACKED_CHANGE_NAMES) {
+        for (const node of wordElementsByLocalName(xmlDocOrElement, localName)) {
+            const author = node.getAttribute?.('w:author')
+                || node.getAttribute?.('author')
+                || (typeof node.getAttributeNS === 'function' ? node.getAttributeNS(NS_W, 'author') : null);
+            if (author && typeof author === 'string' && author.trim()) {
+                authors.add(author.trim());
+            }
+        }
+    }
+    return [...authors].sort();
 }
 
 /**