@ansonlai/docx-redline-js 0.9.0 → 0.11.0

package/services/inspection-comparison.js

@@ -0,0 +1,82 @@
+/**
+ * Compares two `inspectDocumentParts` results by what a reader and reviewer see:
+ * paragraph text, table position, list label, review segments and comments.
+ *
+ * A host that writes a prepared package uses this to verify what it committed
+ * against what was prepared. Revision ids, dates, rsids, paragraph ids and
+ * run boundaries are ignored, because hosts regenerate them on write.
+ */
+
+const commentIdentity = comment => [comment.author ?? null, comment.text ?? '', comment.anchoredText || ''];
+
+// Adjacent review segments of one kind and author are one change, however the
+// host split the runs.
+function reviewSegments(segments = []) {
+    return segments.filter(segment => segment.kind !== 'baseline').reduce((result, segment) => {
+        const next = {
+            kind: segment.kind, author: segment.author || null, text: segment.text,
+            acceptedStart: segment.acceptedStart ?? null, rejectedStart: segment.rejectedStart ?? null
+        };
+        const previous = result.at(-1);
+        const adjacent = key => (previous[key] == null && next[key] == null)
+            || (previous[key] != null && previous[key] + previous.text.length === next[key]);
+        if (previous && previous.kind === next.kind && previous.author === next.author
+            && adjacent('acceptedStart') && adjacent('rejectedStart')) previous.text += next.text;
+        else result.push(next);
+        return result;
+    }, []);
+}
+
+/**
+ * The host-independent shape of one inspection.
+ * @param {{ paragraphs: Array<object>, comments?: Array<object> }} inspection
+ */
+export function inspectionReviewShape(inspection) {
+    const comments = inspection?.comments || [];
+    return {
+        paragraphs: (inspection?.paragraphs || []).map(paragraph => ({
+            text: paragraph.exactText,
+            inTable: paragraph.inTable === true,
+            table: paragraph.table ? [paragraph.table.rowIndex, paragraph.table.cellIndex] : null,
+            list: paragraph.list ? [paragraph.list.format, paragraph.list.level, paragraph.list.label] : null,
+            review: {
+                present: paragraph.hasRevisions === true,
+                authors: [...(paragraph.revisionAuthors || [])].sort(),
+                segments: reviewSegments(paragraph.segments)
+            }
+        })),
+        comments: comments.map(comment => {
+            const parent = comment.parentCommentId != null
+                ? comments.find(item => String(item.id) === String(comment.parentCommentId))
+                : null;
+            return [...commentIdentity(comment), comment.done === true,
+                parent ? commentIdentity(parent)
+                    : (comment.parentCommentId != null || comment.parentParaId ? 'unresolved parent' : null)];
+        }).map(item => JSON.stringify(item)).sort()
+    };
+}
+
+/**
+ * @param {{ paragraphs: Array<object>, comments?: Array<object> }} expected - e.g. inspection of the prepared package
+ * @param {{ paragraphs: Array<object>, comments?: Array<object> }} actual - e.g. inspection of what the host committed
+ * @returns {{ matches: boolean, differences: Array<{ path: string, expected: any, actual: any }> }}
+ *   `differences` lists at most the first ten mismatches.
+ */
+export function compareDocumentInspections(expected, actual) {
+    const left = inspectionReviewShape(expected);
+    const right = inspectionReviewShape(actual);
+    const differences = [];
+    const note = (path, a, b) => {
+        if (differences.length < 10 && JSON.stringify(a) !== JSON.stringify(b)) differences.push({ path, expected: a, actual: b });
+    };
+    note('paragraphs.length', left.paragraphs.length, right.paragraphs.length);
+    const count = Math.max(left.paragraphs.length, right.paragraphs.length);
+    for (let index = 0; index < count; index++) {
+        const a = left.paragraphs[index] ?? null;
+        const b = right.paragraphs[index] ?? null;
+        if (!a || !b) { note(`paragraphs[${index}]`, a, b); continue; }
+        for (const key of ['text', 'inTable', 'table', 'list', 'review']) note(`paragraphs[${index}].${key}`, a[key], b[key]);
+    }
+    note('comments', left.comments, right.comments);
+    return { matches: differences.length === 0, differences };
+}

package/services/operation-heuristics.js

@@ -192,6 +192,6 @@ export function deriveParagraphThenTableAppend(modifiedText) {
     const tableLines = lines.slice(1);
     if (!tableLines.every(line => line.trim().startsWith('|'))) return null;
     const separator = tableLines[1].replace(/\s+/g, '');
-    if (!/^\|:?-{3,}:?(\|:?-{3,}:?)+\|?$/.test(separator)) return null;
+    if (!/^\|:?-{3,}:?(?:(\|:?-{3,}:?)+\|?|\|)$/.test(separator)) return null;
     return { paragraphMarkdown: lines[0].trim(), tableText: tableLines.join('\n') };
 }

package/services/operation-preflight.js

@@ -4,7 +4,7 @@
 
 import { parseOoxmlSafe } from '../adapters/xml-adapter.js';
 import { getDefaultAuthor } from '../adapters/config.js';
-import { containsTrackedChanges, getTrackedChangeAuthors } from '../core/word-xml.js';
+import { containsTrackedChanges, getTrackedChangeAuthors, hasUnattributedTrackedChange, resolveExistingRevisionsPolicy } from '../core/word-xml.js';
 import { NS_W } from '../core/types.js';
 import { extractCanonicalParagraphText } from '../core/paragraph-text.js';
 import {
@@ -273,42 +273,49 @@ export function preflightOperations(documentXml, operations, author, options = {
                 : null;
             const anchorFound = anchor == null
                 || (anchorResolution ? anchorResolution.found : paragraphText.includes(anchor));
+            // The paragraphs from the target through targetEnd (just the target without one); null when the
+            // end does not resolve after the start.
+            const rangeParagraphs = opType => {
+                if (operation.targetEndRef) {
+                    return resolveParagraphRangeByRefs(xmlDoc, operation.targetRef, operation.targetEndRef, {
+                        opType,
+                        targetRefSnapshot: options.targetRefSnapshot || null,
+                        onInfo: options.onInfo,
+                        onWarn: options.onWarn
+                    });
+                }
+                if (!operation.targetEndDescriptor) return [paragraph];
+                const endResolved = resolveTargetParagraph(xmlDoc, {
+                    targetText: operation.targetEndDescriptor.text,
+                    targetRef: operation.targetEndDescriptor.index,
+                    targetDescriptor: operation.targetEndDescriptor,
+                    opType,
+                    strictAmbiguity: strictTargets,
+                    paragraphMetadataIndex: currentMetadataIndex,
+                    metadataIndices,
+                    onInfo: options.onInfo,
+                    onWarn: options.onWarn
+                });
+                const allParagraphs = getDocumentParagraphNodes(xmlDoc);
+                const startIndex = allParagraphs.indexOf(paragraph);
+                const endIndex = allParagraphs.indexOf(endResolved?.paragraph);
+                return startIndex >= 0 && endIndex >= startIndex
+                    ? allParagraphs.slice(startIndex, endIndex + 1)
+                    : null;
+            };
             const hasRevisions = containsTrackedChanges(paragraph);
-            const existingPolicy = operation.existingRevisions
-                || options.existingRevisions
-                || 'merge-same-author';
+            const requestedPolicy = operation.existingRevisions || options.existingRevisions || 'merge-same-author';
+            const existingPolicy = resolveExistingRevisionsPolicy(requestedPolicy,
+                requestedPolicy === 'auto' && operation.operationKind === 'redline' && (operation.targetEndRef || operation.targetEndDescriptor)
+                    ? (rangeParagraphs('redline') || paragraph)
+                    : paragraph,
+                authorUsed);
             const deletingWholeParagraph = operation.operationKind === 'redline' && operation.modified === '';
             const commentIds = deletingWholeParagraph ? getCommentIdsInParagraph(paragraph) : [];
 
             let error = null;
             if (operation.operationKind === 'restore') {
-                let restorationParagraphs = operation.targetEndRef
-                    ? resolveParagraphRangeByRefs(xmlDoc, operation.targetRef, operation.targetEndRef, {
-                        opType: 'restore',
-                        targetRefSnapshot: options.targetRefSnapshot || null,
-                        onInfo: options.onInfo,
-                        onWarn: options.onWarn
-                    })
-                    : [paragraph];
-                if (!operation.targetEndRef && operation.targetEndDescriptor) {
-                    const endResolved = resolveTargetParagraph(xmlDoc, {
-                        targetText: operation.targetEndDescriptor.text,
-                        targetRef: operation.targetEndDescriptor.index,
-                        targetDescriptor: operation.targetEndDescriptor,
-                        opType: 'restore',
-                        strictAmbiguity: strictTargets,
-                        paragraphMetadataIndex: currentMetadataIndex,
-                        metadataIndices,
-                        onInfo: options.onInfo,
-                        onWarn: options.onWarn
-                    });
-                    const allParagraphs = getDocumentParagraphNodes(xmlDoc);
-                    const startIndex = allParagraphs.indexOf(paragraph);
-                    const endIndex = allParagraphs.indexOf(endResolved?.paragraph);
-                    restorationParagraphs = startIndex >= 0 && endIndex >= startIndex
-                        ? allParagraphs.slice(startIndex, endIndex + 1)
-                        : null;
-                }
+                const restorationParagraphs = rangeParagraphs('restore');
                 const replacements = Array.isArray(operation.modified) ? operation.modified : [operation.modified];
                 if (!restorationParagraphs || restorationParagraphs[0] !== paragraph || replacements.length !== restorationParagraphs.length) {
                     error = {
@@ -364,11 +371,13 @@ export function preflightOperations(documentXml, operations, author, options = {
                 if (existingPolicy === 'merge-same-author' || existingPolicy === 'slice-cross-author') {
                     const authors = getTrackedChangeAuthors(paragraph);
                     const opAuthor = String(authorUsed || '').trim().toLowerCase();
-                    const allSame = authors.length > 0 && authors.every(a => a.trim().toLowerCase() === opAuthor);
+                    const allSame = authors.length > 0
+                        && !hasUnattributedTrackedChange(paragraph)
+                        && authors.every(a => a.trim().toLowerCase() === opAuthor);
                     if (!allSame && existingPolicy === 'merge-same-author') {
                         error = {
                             code: 'EXISTING_REVISIONS',
-                            message: `Target paragraph contains tracked changes from another author (${authors.length ? authors.join(', ') : 'unattributed'}). Use existingRevisions: "slice-cross-author" for a surgical edit that preserves reviewer history; accepting or rejecting revisions requires separate authorization.`,
+                            message: `Target paragraph contains tracked changes from another author (${[...authors, ...(hasUnattributedTrackedChange(paragraph) ? ['unattributed'] : [])].join(', ')}). Use existingRevisions: "slice-cross-author" for a surgical edit that preserves reviewer history; accepting or rejecting revisions requires separate authorization.`,
                             revisionAuthors: authors,
                             currentPolicy: existingPolicy
                         };

package/services/revision-fidelity-verifier.js

@@ -200,15 +200,15 @@ function parseNumberingDefinitions(text) {
     const cached = numberingDefinitionCache.get(text);
     if (cached) return cached;
     const abstractLevels = new Map();
-    for (const match of text.matchAll(/<(?:\w+:)?abstractNum([^>]*)>([\s\S]*?)<\/(?:\w+:)?abstractNum>/g)) {
+    for (const match of text.matchAll(/<(?:\w+:)?abstractNum\b([^>]*)>([\s\S]*?)<\/(?:\w+:)?abstractNum>/g)) {
         const id = /abstractNumId="([^"]*)"/.exec(match[1])?.[1];
         if (id == null) continue;
         const levels = abstractLevels.get(id) || new Set();
-        for (const lvl of match[2].matchAll(/<(?:\w+:)?lvl[^>]*?ilvl="([^"]*)"/g)) levels.add(lvl[1]);
+        for (const lvl of match[2].matchAll(/<(?:\w+:)?lvl\b[^>]*?ilvl="([^"]*)"/g)) levels.add(lvl[1]);
         abstractLevels.set(id, levels);
     }
     const numToAbstract = new Map();
-    for (const match of text.matchAll(/<(?:\w+:)?num([^>]*)>([\s\S]*?)<\/(?:\w+:)?num>/g)) {
+    for (const match of text.matchAll(/<(?:\w+:)?num\b([^>]*)>([\s\S]*?)<\/(?:\w+:)?num>/g)) {
         const id = /numId="([^"]*)"/.exec(match[1])?.[1];
         const abstractId = /abstractNumId[^>]*?val="([^"]*)"/.exec(match[2])?.[1];
         if (id != null && abstractId != null) numToAbstract.set(id, abstractId);
@@ -231,7 +231,7 @@ function parseNumberingDefinitions(text) {
  * @param {Document} input.after - post-mutation DOM
  * @param {Array<string|null|undefined>} input.numberingXmls - numbering part texts available at the seam
  */
-export function verifyNumberingReferences({ before, after, numberingXmls, beforeViews = null, afterViews = null }) {
+export function verifyNumberingReferences({ before, after, numberingXmls }) {
     const references = documentNode => {
         const found = new Map();
         for (const numIdNode of getAllReferencedNumIdElements(documentNode)) {
@@ -247,21 +247,7 @@ export function verifyNumberingReferences({ before, after, numberingXmls, before
     const used = references(after);
     if (used.size === 0) return { ok: true };
     const known = references(before);
-    const text = (numberingXmls || []).filter(Boolean).join('\n');
-    const abstractLevels = new Map();
-    for (const match of text.matchAll(/<(?:\w+:)?abstractNum\b([^>]*)>([\s\S]*?)<\/(?:\w+:)?abstractNum>/g)) {
-        const id = /abstractNumId="([^"]*)"/.exec(match[1])?.[1];
-        if (id == null) continue;
-        const levels = abstractLevels.get(id) || new Set();
-        for (const lvl of match[2].matchAll(/<(?:\w+:)?lvl\b[^>]*?ilvl="([^"]*)"/g)) levels.add(lvl[1]);
-        abstractLevels.set(id, levels);
-    }
-    const numToAbstract = new Map();
-    for (const match of text.matchAll(/<(?:\w+:)?num\b([^>]*)>([\s\S]*?)<\/(?:\w+:)?num>/g)) {
-        const id = /numId="([^"]*)"/.exec(match[1])?.[1];
-        const abstractId = /abstractNumId[^>]*?val="([^"]*)"/.exec(match[2])?.[1];
-        if (id != null && abstractId != null) numToAbstract.set(id, abstractId);
-    }
+    const { abstractLevels, numToAbstract } = parseNumberingDefinitions((numberingXmls || []).filter(Boolean).join('\n'));
     const violations = [];
     for (const [numId, levels] of used) {
         if (known.has(numId)) continue;

package/services/standalone-docx-plumbing.js

@@ -310,12 +310,47 @@ export async function ensureNumberingArtifactsInZip(zip, numberingXmlList, optio
     }
 }
 
+/**
+ * Merges incoming comment definitions into an existing comments.xml string. With no
+ * existing part, or `replaceExisting`, the incoming part is returned as is (unparsed).
+ * Otherwise throws a `PARSE_ERROR` for malformed XML and a `DUPLICATE_COMMENT_ID` for an
+ * incoming id the existing part (or an earlier incoming comment) already uses. An incoming
+ * part with no comments leaves the existing string as is.
+ *
+ * @param {string|null|undefined} existingXml
+ * @param {string} commentsXml
+ * @param {{ replaceExisting?: boolean }} [options]
+ * @returns {string}
+ */
+export function mergeCommentsPartXml(existingXml, commentsXml, options = {}) {
+    if (!existingXml || options.replaceExisting === true) return commentsXml;
+    const existingDoc = parseXmlStrictStandalone(existingXml, 'word/comments.xml (existing)');
+    const incomingDoc = parseXmlStrictStandalone(commentsXml, 'word/comments.xml (incoming)');
+    const incomingComments = Array.from(incomingDoc.documentElement.getElementsByTagNameNS(NS_W, 'comment'));
+    if (incomingComments.length === 0) return existingXml;
+    const existingRoot = existingDoc.documentElement;
+    const usedIds = new Set(
+        Array.from(existingRoot.getElementsByTagNameNS(NS_W, 'comment'))
+            .map(comment => comment.getAttribute('w:id') || comment.getAttribute('id'))
+            .filter(Boolean)
+    );
+    for (const incomingComment of incomingComments) {
+        const id = incomingComment.getAttribute('w:id') || incomingComment.getAttribute('id');
+        if (id && usedIds.has(id)) {
+            throw Object.assign(new Error(`Duplicate comment id: ${id}`), { code: 'DUPLICATE_COMMENT_ID', commentId: id });
+        }
+        if (id) usedIds.add(id);
+        existingRoot.appendChild(existingDoc.importNode(incomingComment, true));
+    }
+    return createSerializer().serializeToString(existingDoc);
+}
+
 /**
  * Ensures comments part + package metadata exist and merges incoming comments.
  *
  * @param {any} zip
  * @param {string|null|undefined} commentsXml
- * @param {{ onInfo?: (message: string) => void }} [options]
+ * @param {{ onInfo?: (message: string) => void, replaceExisting?: boolean }} [options]
  */
 export async function ensureCommentsArtifactsInZip(zip, commentsXml, options = {}) {
     const onInfo = typeof options?.onInfo === 'function' ? options.onInfo : () => {};
@@ -323,27 +358,8 @@ export async function ensureCommentsArtifactsInZip(zip, commentsXml, options = {
 
     const serializer = createSerializer();
     const existingText = await readZipText(zip, COMMENTS_PATH);
-    if (!existingText || options.replaceExisting === true) {
-        onInfo('[Demo] Adding comments.xml');
-        zip.file(COMMENTS_PATH, commentsXml);
-    } else {
-        const existingDoc = parseXmlStrictStandalone(existingText, 'word/comments.xml (existing)');
-        const incomingDoc = parseXmlStrictStandalone(commentsXml, 'word/comments.xml (incoming)');
-        const existingRoot = existingDoc.documentElement;
-        const existingIds = new Set(
-            Array.from(existingRoot.getElementsByTagNameNS(NS_W, 'comment'))
-                .map(comment => comment.getAttribute('w:id') || comment.getAttribute('id'))
-                .filter(Boolean)
-        );
-        for (const incomingComment of Array.from(incomingDoc.documentElement.getElementsByTagNameNS(NS_W, 'comment'))) {
-            const id = incomingComment.getAttribute('w:id') || incomingComment.getAttribute('id');
-            if (id && existingIds.has(id)) {
-                throw new Error(`Duplicate comment id: ${id}`);
-            }
-            existingRoot.appendChild(existingDoc.importNode(incomingComment, true));
-        }
-        zip.file(COMMENTS_PATH, serializer.serializeToString(existingDoc));
-    }
+    if (!existingText || options.replaceExisting === true) onInfo('[Demo] Adding comments.xml');
+    zip.file(COMMENTS_PATH, mergeCommentsPartXml(existingText, commentsXml, options));
 
     const ctText = await readZipText(zip, CONTENT_TYPES_PATH);
     if (ctText) {

package/services/table-reconciliation.js

@@ -8,7 +8,12 @@ import { computeWordLevelDiffOps } from '../pipeline/diff-engine.js';
 import { splitRunsAtDiffBoundaries, applyPatches } from '../pipeline/patching.js';
 import { serializeToOoxml } from '../pipeline/serialization.js';
 import { createRevisionMetadata, escapeXml, RunKind } from '../core/types.js';
-import { preprocessMarkdown } from '../pipeline/markdown-processor.js';
+import { preprocessMarkdown } from '../pipeline/markdown-processor.js';
+
+// A caller's structuredContent: false (options.plainTextContent) keeps cell text literal: no inline Markdown.
+const cellMarkdown = (text, options) => (options?.plainTextContent === true
+    ? { cleanText: String(text ?? ''), formatHints: [] }
+    : preprocessMarkdown(text));
 import { paragraphMarkPPrXml } from '../engine/paragraph-mark-revisions.js';
 
 /**
@@ -64,7 +69,7 @@ export function generateTableOoxml(tableData, options = {}) {
 
         for (let c = 0; c < numCols; c++) {
             const cellText = row[c] || '';
-            const { cleanText, formatHints } = preprocessMarkdown(cellText);
+            const { cleanText, formatHints } = cellMarkdown(cellText, options);
 
             // Build run model for the cell
             const runModel = [{
@@ -239,7 +244,7 @@ export function serializeVirtualGridToOoxml(grid, operations, options) {
         const rowInsertMeta = generateRedlines ? createRevisionMetadata(author, revisionIdAllocator) : null;
 
         for (const cellText of op.cells) {
-            const { cleanText, formatHints } = preprocessMarkdown(cellText);
+            const { cleanText, formatHints } = cellMarkdown(cellText, options);
             // Simple run model for new cell
             const runModel = [{
                 kind: generateRedlines ? RunKind.INSERTION : RunKind.TEXT,
@@ -340,7 +345,7 @@ function reconcileMultiBlockCellContent(cell, newText, options) {
             }
             return;
         }
-        const { cleanText, formatHints } = preprocessMarkdown(line);
+        const { cleanText, formatHints } = cellMarkdown(line, options);
         const diffOps = computeWordLevelDiffOps(block.acceptedText, cleanText);
         const model = applyPatches(splitRunsAtDiffBoundaries(block.runModel, diffOps), diffOps, {
             generateRedlines, author, formatHints
@@ -349,7 +354,7 @@ function reconcileMultiBlockCellContent(cell, newText, options) {
     });
 
     for (let i = cell.blocks.length; i < lines.length; i++) {
-        const { cleanText, formatHints } = preprocessMarkdown(lines[i]);
+        const { cleanText, formatHints } = cellMarkdown(lines[i], options);
         const runModel = [{
             kind: generateRedlines ? RunKind.INSERTION : RunKind.TEXT,
             text: cleanText, rPrXml: '', author, startOffset: 0, endOffset: cleanText.length
@@ -365,7 +370,7 @@ function reconcileCellContent(cell, newText, options) {
         return reconcileMultiBlockCellContent(cell, newText, options);
     }
     const { generateRedlines, author, revisionIdAllocator = null } = options;
-    const { cleanText, formatHints } = preprocessMarkdown(newText);
+    const { cleanText, formatHints } = cellMarkdown(newText, options);
 
     // For now, satisfy with single block or join blocks
     // In a full implementation, we'd diff paragraphs within the cell