@ansonlai/docx-redline-js 0.8.4 → 0.10.0

package/services/operation-batch-compiler.js

@@ -10,9 +10,81 @@ import {
     validateDocumentOperation
 } from './document-operation-contract.js';
 import { compileExactReplacements } from './localized-replacement-compiler.js';
+import { getParagraphListInfo } from '../core/list-targeting.js';
+import { parseTypedListMarker } from './list-format.js';
+import { isTrackedDeletedParagraph } from './numbering-helpers.js';
 
-const TEXT_WRITE_KINDS = new Set(['redline', 'restore', 'rejected-insert']);
+// list-format strips typed markers (a text write) and binds numPr (a pPr write). On its own target it conflicts with
+// every other text or format write except one compatible single-paragraph redline (`checkListFormatComposition`).
+const TEXT_WRITE_KINDS = new Set(['redline', 'restore', 'rejected-insert', 'list-format']);
 const FORMAT_WRITE_KINDS = new Set(['highlight', 'format', 'paragraph-format']);
+const WORD_NS = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
+export const LIST_FORMAT_COMPOSITION_CONFLICT = 'LIST_FORMAT_COMPOSITION_CONFLICT';
+const COMPOSABLE_REDLINE_TYPES = new Set(['redline', 'replace']);
+
+/**
+ * The typed-marker prefix of a paragraph text as list-format reads it: the exact text a convert-plain strip removes
+ * ("1. ", "A. ", "- "), `unsupported:<marker>` for a marker shape list-format refuses, or null for no marker.
+ */
+function typedMarkerKey(text) {
+    const value = String(text ?? '');
+    const parsed = parseTypedListMarker(value);
+    if (!parsed) return null;
+    if (parsed.unsupported) return `unsupported:${parsed.marker}`;
+    return value.slice(0, parsed.prefixLength);
+}
+
+/**
+ * Rule for one `redline` and one `list-format` writing the same batch-start paragraph (the list-format targets it, or
+ * rebinds it through `scope: 'list'`). They compose when the redline changes only the paragraph's text after its typed
+ * marker and the list-format owns the marker and numbering: e.g. "1. Old" -> "1. New" as a redline plus
+ * `convert-plain`. Execution order is fixed: the redline runs first (its target binds at batch start), then the
+ * list-format strips the unchanged marker from the redlined paragraph. Returns null when compatible, else a reason.
+ */
+function checkListFormatComposition(redline, sourceText) {
+    const operation = redline.operation;
+    if (!COMPOSABLE_REDLINE_TYPES.has(operation?.type ?? 'redline')
+        || operation.targetEnd != null || operation.targetEndRef != null
+        || operation.anchor != null || operation.structuredContent === true || operation.part != null
+        || operation.target?.revisionView === 'rejected'
+        || typeof operation.modified !== 'string' || /[\r\n]/.test(operation.modified)) {
+        return {
+            reason: 'redline-shape',
+            hint: 'Pair a list-format only with a single-paragraph redline or replace of that paragraph: modified without line breaks, no targetEnd, anchor, part or structuredContent.'
+        };
+    }
+    if (operation.modified === sourceText) {
+        return {
+            reason: 'redline-unchanged',
+            hint: 'The redline does not change the text; drop it and send only the list-format.'
+        };
+    }
+    const before = typedMarkerKey(sourceText);
+    const after = typedMarkerKey(operation.modified);
+    if (before !== after) {
+        return {
+            reason: 'marker-changed',
+            sourceMarker: before,
+            modifiedMarker: after,
+            hint: 'The redline adds, removes or changes the typed marker. Keep the marker text exactly as it is (the list-format strips it), and express a new label through list-format (strip "none" with format/start, or change-format).'
+        };
+    }
+    return null;
+}
+
+/** Live body paragraphs a `scope: 'list'` change-format/join rebinds outside its named target. */
+function listScopeRebindParagraphs(xmlDoc, registry, binding, operation) {
+    const mode = operation.list?.mode;
+    if (mode !== 'change-format' && mode !== 'join') return [];
+    if ((operation.list?.scope || 'list') !== 'list') return [];
+    const targets = binding.sourceIds.map(sourceId => registry.entries.get(sourceId)?.paragraph).filter(Boolean);
+    const info = targets.map(paragraph => getParagraphListInfo(paragraph)).find(Boolean);
+    if (!info) return [];
+    return Array.from(xmlDoc.getElementsByTagNameNS(WORD_NS, 'p')).filter(paragraph => {
+        if (targets.includes(paragraph) || isTrackedDeletedParagraph(paragraph)) return false;
+        return getParagraphListInfo(paragraph)?.numId === info.numId;
+    });
+}
 
 function normalizedError(error) {
     const details = {};
@@ -143,16 +215,24 @@ export class SourceTargetRegistry {
         }
     }
 
-    commitMutation(sourceId, removedNodes, liveNodes, operationIndex) {
+    /** The paragraph that will stand for sourceId once this mutation commits (no state change). */
+    previewSuccessor(sourceId, removedNodes, liveNodes) {
         const entry = this.entries.get(sourceId);
-        if (!entry || !Array.isArray(removedNodes) || !removedNodes.includes(entry.paragraph)) return;
+        if (!entry || !entry.paragraph) return null;
+        if (!Array.isArray(removedNodes) || !removedNodes.includes(entry.paragraph)) return entry.paragraph;
         const candidates = paragraphNodesFromMutation(liveNodes);
         const sameId = entry.paragraphId
             ? candidates.filter(paragraph => getParagraphId(paragraph) === entry.paragraphId)
             : [];
-        const successor = sameId.length === 1
+        return sameId.length === 1
             ? sameId[0]
             : (candidates.length === 1 ? candidates[0] : null);
+    }
+
+    commitMutation(sourceId, removedNodes, liveNodes, operationIndex) {
+        const entry = this.entries.get(sourceId);
+        if (!entry || !Array.isArray(removedNodes) || !removedNodes.includes(entry.paragraph)) return;
+        const successor = this.previewSuccessor(sourceId, removedNodes, liveNodes);
         if (successor) {
             entry.paragraph = successor;
             this.idsByNode.set(successor, sourceId);
@@ -200,17 +280,19 @@ function resolveDescriptor(xmlDoc, descriptor, kind, strictTargets, metadataIndi
     };
 }
 
-function buildConflict(code, message, bindings, target, action) {
+function buildConflict(code, message, bindings, target, action, details = {}, hint = null) {
     return {
         code,
         message,
         operationIndexes: bindings.map(binding => binding.index).sort((a, b) => a - b),
         target,
+        ...details,
         recovery: {
             action,
             sameArgumentsSafe: false,
             requiresReinspection: false,
-            requiresUserAuthorization: false
+            requiresUserAuthorization: false,
+            ...(hint ? { hint } : {})
         }
     };
 }
@@ -246,10 +328,11 @@ export function compileOperationBatch(xmlDoc, operations = [], options = {}) {
         const compositeTextTarget = typeof operation.targetDescriptor?.text === 'string'
             && /\r|\n/.test(operation.targetDescriptor.text)
             && !operation.targetEndDescriptor
-            // A strong paragraph target with localized replacements is one paragraph whose
-            // soft line breaks (w:br) appear as "\n" in text; it still binds at batch start.
-            && !(Array.isArray(operation.replacements)
-                && (operation.targetDescriptor.paragraphId || operation.targetDescriptor.fingerprint));
+            // Localized replacements always address one paragraph (the contract refuses ranges and
+            // captures), so "\n" in the target text is a soft line break (w:br), not a paragraph
+            // boundary. Strong or weak (index + exactText) it binds at batch start; leaving it
+            // dynamic would skip replacement compilation and apply an empty "modified".
+            && !Array.isArray(operation.replacements);
         if (dynamicOccurrence || compositeTextTarget) binding.dynamic = true;
 
         if (
@@ -346,6 +429,28 @@ export function compileOperationBatch(xmlDoc, operations = [], options = {}) {
                     binding.sourceIds = [...new Set(binding.sourceIds)];
                     binding.resolvedTargetEnd = end.metadata;
                 }
+
+                // list-format join reads (never writes) the paragraph it continues; bind it at batch start too.
+                if (operation.operationKind === 'list-format' && operation.list?.continueFrom && typeof operation.list.continueFrom === 'object') {
+                    let continueFrom;
+                    try {
+                        continueFrom = resolveDescriptor(
+                            xmlDoc,
+                            normalizeTargetDescriptor(operation.list.continueFrom, null, 'accepted'),
+                            operation.operationKind,
+                            strictTargets,
+                            metadataIndices,
+                            {
+                                onInfo: options.onInfo,
+                                onWarn: warning => binding.warnings.push(String(warning))
+                            }
+                        );
+                    } catch (error) {
+                        throw Object.assign(error instanceof Error ? error : new Error(String(error)), { field: 'list.continueFrom' });
+                    }
+                    compiled._compiledContinueFromId = registry.register(continueFrom.paragraph, continueFrom.metadata);
+                    binding.resolvedContinueFrom = continueFrom.metadata;
+                }
             } catch (error) {
                 binding.error = normalizedError(error);
             }
@@ -388,17 +493,84 @@ export function compileOperationBatch(xmlDoc, operations = [], options = {}) {
     }
 
     const bySource = new Map();
+    const rebindsBySource = new Map();
     for (const binding of bindings) {
         if (binding.error || binding.dynamic) continue;
         for (const sourceId of binding.sourceIds) {
             if (!bySource.has(sourceId)) bySource.set(sourceId, []);
             bySource.get(sourceId).push(binding);
         }
+        // A scope "list" change-format/join writes pPr on every live item of the target's list, so those items are
+        // registered as format writes of the operation: another write to them must compose or is refused.
+        if (binding.operationKind === 'list-format') {
+            const operation = compiledOperations[binding.index - 1];
+            for (const paragraph of listScopeRebindParagraphs(xmlDoc, registry, binding, operation)) {
+                const sourceId = registry.register(paragraph, metadataIndices.accepted.byParagraph.get(paragraph) || {});
+                if (binding.sourceIds.includes(sourceId)) continue;
+                (binding.rebindSourceIds ||= []).push(sourceId);
+                if (!bySource.has(sourceId)) bySource.set(sourceId, []);
+                if (!rebindsBySource.has(sourceId)) rebindsBySource.set(sourceId, []);
+                rebindsBySource.get(sourceId).push(binding);
+            }
+        }
     }
 
     const conflicts = [];
     const conflictKeys = new Set();
-    for (const [sourceId, sourceBindings] of bySource) {
+    const pushConflict = (key, conflict) => {
+        if (conflictKeys.has(key)) return;
+        conflictKeys.add(key);
+        conflicts.push(conflict);
+    };
+    for (const [sourceId, targetBindings] of bySource) {
+        const rebinds = rebindsBySource.get(sourceId) || [];
+        const writers = [...targetBindings, ...rebinds]
+            .filter(binding => TEXT_WRITE_KINDS.has(binding.operationKind) || FORMAT_WRITE_KINDS.has(binding.operationKind));
+        const listFormats = writers.filter(binding => binding.operationKind === 'list-format');
+        const others = writers.filter(binding => binding.operationKind !== 'list-format');
+        if (listFormats.length === 1 && others.length === 1 && others[0].operationKind === 'redline') {
+            const [listFormat] = listFormats;
+            const [redline] = others;
+            const describedSource = registry.describe(sourceId);
+            const incompatible = checkListFormatComposition(
+                { operation: compiledOperations[redline.index - 1] },
+                redline.resolvedTarget?.text ?? describedSource?.text ?? ''
+            );
+            if (incompatible) {
+                const affected = [redline, listFormat];
+                pushConflict(`list:${affected.map(binding => binding.index).sort().join(',')}`, buildConflict(
+                    LIST_FORMAT_COMPOSITION_CONFLICT,
+                    `Operations ${affected.map(binding => binding.index).sort((a, b) => a - b).join(', ')} combine a redline and a list-format on the same paragraph in a way that does not compose (${incompatible.reason}).`,
+                    affected,
+                    describedSource,
+                    'split_text_and_list_changes',
+                    { reason: incompatible.reason, ...(incompatible.sourceMarker !== undefined ? { sourceMarker: incompatible.sourceMarker, modifiedMarker: incompatible.modifiedMarker } : {}) },
+                    incompatible.hint
+                ));
+                continue;
+            }
+            // Deterministic order: the list-format runs after the redline, whatever the batch order.
+            const compiledListFormat = compiledOperations[listFormat.index - 1];
+            const runAfter = new Set(compiledListFormat._compiledRunAfter || []);
+            runAfter.add(redline.index - 1);
+            compiledListFormat._compiledRunAfter = [...runAfter].sort((a, b) => a - b);
+            listFormat.composedWith = [...new Set([...(listFormat.composedWith || []), redline.index])];
+            redline.composedWith = [...new Set([...(redline.composedWith || []), listFormat.index])];
+            continue;
+        }
+        if (rebinds.length > 0 && writers.length > 1) {
+            pushConflict(`rebind:${writers.map(binding => binding.index).sort().join(',')}`, buildConflict(
+                LIST_FORMAT_COMPOSITION_CONFLICT,
+                `Operation ${rebinds.map(binding => binding.index).join(', ')} (list-format, scope "list") rebinds this list item, and operations ${writers.filter(binding => !rebinds.includes(binding)).map(binding => binding.index).join(', ')} also write it.`,
+                writers,
+                registry.describe(sourceId),
+                'split_text_and_list_changes',
+                { reason: 'list-rebind', rebindingOperationIndexes: rebinds.map(binding => binding.index) },
+                'A list-format with scope "list" rewrites every item of the list; in the same batch only one single-paragraph redline per item can compose with it. Send the other change in a separate apply, or use scope "range".'
+            ));
+            continue;
+        }
+        const sourceBindings = targetBindings;
         const textWrites = sourceBindings.filter(binding => TEXT_WRITE_KINDS.has(binding.operationKind));
         const formatWrites = sourceBindings.filter(binding => FORMAT_WRITE_KINDS.has(binding.operationKind));
         if (textWrites.length > 1) {

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 {
@@ -38,6 +38,7 @@ function normalizedError(error, context = {}) {
 }
 
 function operationNeedsNumbering(operation) {
+    if (operation.operationKind === 'list-format') return true;
     if (operation.operationKind !== 'redline' || typeof operation.modified !== 'string') return false;
     return operation.modified.split(/\r?\n/).some(line => /^\s*(?:[-+*]|\d+[.)])\s+/.test(line));
 }
@@ -272,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 = {
@@ -363,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
                         };