@ansonlai/docx-redline-js 0.5.4 → 0.6.1

package/services/batch-operation-orchestrator.js

@@ -19,10 +19,12 @@ import {
     computeDocumentPartsRevisionToken,
     areRevisionTokensEqual
 } from './revision-token.js';
-import {
-    createEmptyReceipt,
-    reconcileReceiptsAgainstOutput
-} from './receipt-collector.js';
+import {
+    createEmptyReceipt,
+    reconcileReceiptsAgainstOutput
+} from './receipt-collector.js';
+import { compileOperationBatch } from './operation-batch-compiler.js';
+import { createRetryPlan } from './error-recovery.js';
 
 const NS_W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
 
@@ -70,9 +72,10 @@ export function buildOperationDependencyPlan(operations = []) {
     }
 
     // 2. Build dependency edges
-    const inDegrees = new Array(list.length).fill(0);
-    const dependents = Array.from({ length: list.length }, () => new Set());
-    const dependencies = Array.from({ length: list.length }, () => new Set());
+    const inDegrees = new Array(list.length).fill(0);
+    const dependents = Array.from({ length: list.length }, () => new Set());
+    const dependencies = Array.from({ length: list.length }, () => new Set());
+    const mutatingCaptureConsumers = new Map();
 
     for (let i = 0; i < list.length; i++) {
         const op = list[i];
@@ -107,13 +110,40 @@ export function buildOperationDependencyPlan(operations = []) {
                     }
                 };
             }
-            if (!dependencies[i].has(producerIndex)) {
-                dependencies[i].add(producerIndex);
-                dependents[producerIndex].add(i);
-                inDegrees[i]++;
-            }
-        }
-    }
+            if (!dependencies[i].has(producerIndex)) {
+                dependencies[i].add(producerIndex);
+                dependents[producerIndex].add(i);
+                inDegrees[i]++;
+            }
+            const kind = normalizeDocumentOperation(op).operationKind;
+            if (kind !== 'comment' && kind !== 'comment_reply') {
+                if (!mutatingCaptureConsumers.has(ref)) mutatingCaptureConsumers.set(ref, []);
+                mutatingCaptureConsumers.get(ref).push({
+                    index: i,
+                    select: op?.target?.select ?? op?.targetDescriptor?.select ?? null
+                });
+            }
+        }
+    }
+
+    for (const [captureRef, consumers] of mutatingCaptureConsumers) {
+        if (consumers.length < 2) continue;
+        const selectors = consumers.map(consumer => consumer.select);
+        const distinctSelectors = new Set(selectors);
+        if (selectors.every(selector => typeof selector === 'string' && selector.length > 0)
+            && distinctSelectors.size === selectors.length) {
+            continue;
+        }
+        return {
+            valid: false,
+            error: {
+                code: 'CAPTURE_FANOUT_CONFLICT',
+                message: `Capture "${captureRef}" has overlapping or unscoped mutating consumers at operation indices ${consumers.map(consumer => consumer.index + 1).join(', ')}.`,
+                operationIndexes: consumers.map(consumer => consumer.index + 1),
+                captureRef
+            }
+        };
+    }
 
     // 3. Stable topological sort with comment priority among ready nodes
     const ready = [];
@@ -191,62 +221,56 @@ export async function applyOperationsToDocumentXml(documentXml, operations, auth
         i + 1,
         op?.operationId,
         resolveDocumentOperationAuthor(op, author, defaultAuthor),
-        'not_attempted'
+        'not_attempted'
     ));
-
-    if (options.existingRevisions != null && !isExistingRevisionsPolicy(options.existingRevisions)) {
+    const failedBeforeExecution = (error, extra = {}) => {
+        const receipts = emptyReceipts();
         return {
             documentXml,
             hasChanges: false,
             commentsXml: null,
             numberingXmlParts: [],
             results: [],
-            receipts: emptyReceipts(),
+            receipts,
             executionOrder: [],
             authorsUsed: [],
+            ...(options.atomic === true ? { rolledBack: true } : {}),
             status: 'error',
-            error: {
-                code: 'INVALID_OPERATION',
-                message: `Unsupported existingRevisions policy: "${String(options.existingRevisions)}".`
-            }
+            error: normalizeOperationError(error),
+            retryPlan: createRetryPlan({
+                atomic: options.atomic === true,
+                rolledBack: options.atomic === true,
+                results: [],
+                receipts,
+                operationCount: sourceOperations.length
+            }),
+            ...extra
         };
+    };
+
+    if (options.existingRevisions != null && !isExistingRevisionsPolicy(options.existingRevisions)) {
+        return failedBeforeExecution({
+            code: 'INVALID_OPERATION',
+            message: `Unsupported existingRevisions policy: "${String(options.existingRevisions)}".`,
+            field: 'existingRevisions'
+        });
     }
 
     if (options?.expectedRevision) {
         const tokenValidation = validateRevisionToken(options.expectedRevision);
         if (!tokenValidation.valid) {
-            return {
-                documentXml,
-                hasChanges: false,
-                commentsXml: null,
-                numberingXmlParts: [],
-                results: [],
-                receipts: emptyReceipts(),
-                executionOrder: [],
-                authorsUsed: [],
-                status: 'error',
-                error: {
-                    code: tokenValidation.error?.code || 'INVALID_REVISION_TOKEN',
-                    message: tokenValidation.error?.message || 'Invalid revision token.'
-                }
-            };
+            return failedBeforeExecution({
+                code: tokenValidation.error?.code || 'INVALID_REVISION_TOKEN',
+                message: tokenValidation.error?.message || 'Invalid revision token.'
+            });
         }
         if (options.expectedRevision.scope !== 'document-parts') {
-            return {
-                documentXml,
-                hasChanges: false,
-                commentsXml: null,
-                numberingXmlParts: [],
-                results: [],
-                receipts: emptyReceipts(),
-                executionOrder: [],
-                authorsUsed: [],
-                status: 'error',
-                error: {
-                    code: 'REVISION_TOKEN_SCOPE_MISMATCH',
-                    message: `Revision token scope mismatch: expected 'document-parts', got '${options.expectedRevision.scope}'.`
-                }
-            };
+            return failedBeforeExecution({
+                code: 'REVISION_TOKEN_SCOPE_MISMATCH',
+                message: `Revision token scope mismatch: expected 'document-parts', got '${options.expectedRevision.scope}'.`,
+                expectedScope: 'document-parts',
+                actualScope: options.expectedRevision.scope
+            });
         }
         const currentToken = await computeDocumentPartsRevisionToken({
             documentXml,
@@ -256,21 +280,12 @@ export async function applyOperationsToDocumentXml(documentXml, operations, auth
             stylesXml: runtimeContext?.stylesXml || options.stylesXml
         }, options);
         if (!areRevisionTokensEqual(currentToken.value, options.expectedRevision.value)) {
-            return {
-                documentXml,
-                hasChanges: false,
-                commentsXml: null,
-                numberingXmlParts: [],
-                results: [],
-                receipts: emptyReceipts(),
-                executionOrder: [],
-                authorsUsed: [],
-                status: 'error',
-                error: {
-                    code: 'REVISION_MISMATCH',
-                    message: `Document revision mismatch: expected '${options.expectedRevision.value}', current is '${currentToken.value}'.`
-                }
-            };
+            return failedBeforeExecution({
+                code: 'REVISION_MISMATCH',
+                message: `Document revision mismatch: expected '${options.expectedRevision.value}', current is '${currentToken.value}'.`,
+                expectedRevision: options.expectedRevision,
+                currentRevision: currentToken
+            });
         }
     }
 
@@ -281,34 +296,73 @@ export async function applyOperationsToDocumentXml(documentXml, operations, auth
             _deferDocumentSerialization: true
         });
     if (!session.valid) {
-        return {
-            documentXml,
-            hasChanges: false,
-            commentsXml: null,
-            numberingXmlParts: [],
-            results: [],
-            receipts: emptyReceipts(),
-            executionOrder: [],
-            authorsUsed: [],
-            status: 'error',
-            error: session.parseResult.error,
-            warnings: session.parseResult.warnings
-        };
+        return failedBeforeExecution(session.parseResult.error, { warnings: session.parseResult.warnings });
     }
-    const dependencyPlan = buildOperationDependencyPlan(sourceOperations);
+    const compilation = compileOperationBatch(session.document, sourceOperations, {
+        strictTargets: options.strictTargets !== false,
+        onInfo: options.onInfo,
+        onWarn: options.onWarn
+    });
+    session.sourceTargetRegistry = compilation.registry;
+    if (compilation.conflicts.length > 0) {
+        const conflictByIndex = new Map();
+        for (const conflict of compilation.conflicts) {
+            for (const index of conflict.operationIndexes) {
+                if (!conflictByIndex.has(index)) conflictByIndex.set(index, conflict);
+            }
+        }
+        const conflictResults = Array.from(conflictByIndex, ([index, conflict]) => {
+            const operation = sourceOperations[index - 1];
+            const authorUsed = resolveDocumentOperationAuthor(operation, author, defaultAuthor);
+            const normalizedConflict = normalizeOperationError(conflict, {
+                operationIndex: index,
+                ...(operation?.operationId ? { operationId: operation.operationId } : {})
+            });
+            return {
+                index,
+                type: operation?.type || 'redline',
+                operationType: normalizeDocumentOperation(operation).operationKind,
+                status: 'error',
+                authorUsed,
+                error: normalizedConflict,
+                receipt: createEmptyReceipt(index, operation?.operationId, authorUsed, 'refused')
+            };
+        }).sort((left, right) => left.index - right.index);
+        const receipts = sourceOperations.map((operation, index) => {
+            const conflictResult = conflictResults.find(result => result.index === index + 1);
+            return conflictResult?.receipt || createEmptyReceipt(
+                index + 1,
+                operation?.operationId,
+                resolveDocumentOperationAuthor(operation, author, defaultAuthor),
+                'not_attempted'
+            );
+        });
+        return {
+            documentXml,
+            hasChanges: false,
+            commentsXml: null,
+            numberingXmlParts: [],
+            results: conflictResults,
+            receipts,
+            executionOrder: [],
+            authorsUsed: [],
+            rolledBack: options.atomic === true,
+            status: 'error',
+            error: normalizeOperationError(compilation.conflicts[0]),
+            conflicts: compilation.conflicts.map(conflict => normalizeOperationError(conflict)),
+            retryPlan: createRetryPlan({
+                atomic: options.atomic === true,
+                rolledBack: options.atomic === true,
+                results: conflictResults,
+                receipts,
+                operationCount: sourceOperations.length
+            })
+        };
+    }
+    const executableOperations = compilation.compiledOperations;
+    const dependencyPlan = buildOperationDependencyPlan(executableOperations);
     if (!dependencyPlan.valid) {
-        return {
-            documentXml,
-            hasChanges: false,
-            commentsXml: null,
-            numberingXmlParts: [],
-            results: [],
-            receipts: emptyReceipts(),
-            executionOrder: [],
-            authorsUsed: [],
-            status: 'error',
-            error: dependencyPlan.error
-        };
+        return failedBeforeExecution(dependencyPlan.error);
     }
     const scheduled = dependencyPlan.scheduled;
 
@@ -332,9 +386,37 @@ export async function applyOperationsToDocumentXml(documentXml, operations, auth
     const authorsUsed = session.authorsUsed;
     let operationFailed = false;
 
-    for (const { operation, index } of scheduled) {
-        executionOrder.push(index + 1);
-        try {
+    for (const { operation, index } of scheduled) {
+        executionOrder.push(index + 1);
+        const sourceBinding = compilation.bindings[index];
+        if (sourceBinding?.error) {
+            operationFailed = true;
+            const authorUsed = resolveDocumentOperationAuthor(operation, author, defaultAuthor);
+            const errorReceipt = createEmptyReceipt(
+                index + 1,
+                operation?.operationId,
+                authorUsed,
+                'refused'
+            );
+            const normalizedBindingError = normalizeOperationError(sourceBinding.error, {
+                operationIndex: index + 1,
+                ...(operation?.operationId ? { operationId: operation.operationId } : {})
+            });
+            errorReceipt.warnings.push(normalizedBindingError.message);
+            results.push({
+                index: index + 1,
+                type: operation?.type || 'redline',
+                status: 'error',
+                operationType: normalizeDocumentOperation(operation).operationKind,
+                authorUsed,
+                warnings: [normalizedBindingError.message],
+                error: normalizedBindingError,
+                receipt: errorReceipt
+            });
+            if (!continueOnError) break;
+            continue;
+        }
+        try {
             const result = await applyOperationToDocumentXml(
                 session.currentDocumentXml,
                 operation,
@@ -374,8 +456,11 @@ export async function applyOperationsToDocumentXml(documentXml, operations, auth
                 ...(result.receipt ? { receipt: result.receipt } : {})
             });
             if (isError && !continueOnError) break;
-        } catch (error) {
-            const normalizedError = normalizeOperationError(error);
+        } catch (error) {
+            const normalizedError = normalizeOperationError(error, {
+                operationIndex: index + 1,
+                ...(operation?.operationId ? { operationId: operation.operationId } : {})
+            });
             operationFailed = true;
             const authorUsed = resolveDocumentOperationAuthor(operation, author, getDefaultAuthor());
             const errorReceipt = createEmptyReceipt(
@@ -476,8 +561,8 @@ export async function applyOperationsToDocumentXml(documentXml, operations, auth
 
     if (!rolledBack) commitBatchRuntimeContext(runtimeContext, context);
 
-    return {
-        documentXml: rolledBack ? session.rollback() : outputDocumentXml,
+    const batchResult = {
+        documentXml: rolledBack ? session.rollback() : outputDocumentXml,
         hasChanges: rolledBack ? false : hasChanges,
         commentsXml: rolledBack ? null : session.commentsXml,
         commentsExtendedXml: rolledBack ? null : session.commentsExtendedXml,
@@ -491,23 +576,33 @@ export async function applyOperationsToDocumentXml(documentXml, operations, auth
         ...(rolledBack ? {
             rolledBack: true,
             status: 'error',
-            error: {
-                code: reconciliationError ? reconciliationError.code : (serializationError ? 'DOCUMENT_SERIALIZATION_FAILED' : 'BATCH_OPERATION_FAILED'),
-                message: reconciliationError?.message
-                    || serializationError?.message
-                    || 'Atomic batch rolled back because one or more operations failed.'
-            }
-        } : (reconciliationError ? {
-            status: 'error',
-            error: reconciliationError
-        } : (operationFailed ? {
-            status: hasChanges ? 'partial' : 'error',
-            error: {
-                code: 'BATCH_OPERATION_FAILED',
-                message: 'One or more operations failed.'
-            }
-        } : {
-            status: 'ok'
-        })))
-    };
-}
+            error: normalizeOperationError({
+                code: reconciliationError ? reconciliationError.code : (serializationError ? 'DOCUMENT_SERIALIZATION_FAILED' : 'BATCH_OPERATION_FAILED'),
+                message: reconciliationError?.message
+                    || serializationError?.message
+                    || 'Atomic batch rolled back because one or more operations failed.'
+            })
+        } : (reconciliationError ? {
+            status: 'error',
+            error: normalizeOperationError(reconciliationError)
+        } : (operationFailed ? {
+            status: hasChanges ? 'partial' : 'error',
+            error: normalizeOperationError({
+                code: 'BATCH_OPERATION_FAILED',
+                message: 'One or more operations failed.'
+            })
+        } : {
+            status: 'ok'
+        })))
+    };
+    if (batchResult.status === 'error' || batchResult.status === 'partial') {
+        batchResult.retryPlan = createRetryPlan({
+            atomic,
+            rolledBack,
+            results: batchResult.results,
+            receipts: batchResult.receipts,
+            operationCount: sourceOperations.length
+        });
+    }
+    return batchResult;
+}

package/services/document-inspection.js

@@ -183,6 +183,80 @@ function collectDocumentCommentAnchors(paragraphNodes, revisionView) {
     return anchors;
 }
 
+function selectInspectionParagraphs(allParagraphs, options) {
+    let matches = allParagraphs;
+    if (options.revisedOnly) matches = matches.filter(item => item.hasRevisions);
+    if (options.inTable != null) matches = matches.filter(item => item.inTable === !!options.inTable);
+    if (options.skipEmpty) matches = matches.filter(item => item.text.length > 0);
+    if (options.search) {
+        const needle = String(options.search).toLowerCase();
+        matches = matches.filter(item => item.text.toLowerCase().includes(needle));
+    }
+    if (Array.isArray(options.indexes)) {
+        const indexes = new Set(options.indexes);
+        matches = matches.filter(item => indexes.has(item.index));
+    }
+    let rangeStart = 1;
+    let rangeEnd = allParagraphs.length;
+    if (options.range) {
+        rangeStart = Number(options.range.start ?? options.range[0]);
+        rangeEnd = Number(options.range.end ?? options.range[1]);
+        matches = matches.filter(item => item.index >= rangeStart && item.index <= rangeEnd);
+    }
+
+    const totalMatches = matches.length;
+    const after = Number.isInteger(options.after) && options.after > 0 ? options.after : null;
+    const remaining = after == null ? matches : matches.filter(item => item.index > after);
+    const limit = Number.isInteger(options.limit) && options.limit > 0 ? options.limit : null;
+    const selectedMatches = limit == null ? remaining : remaining.slice(0, limit);
+    const truncated = selectedMatches.length < remaining.length;
+    const around = Number.isInteger(options.around) && options.around > 0 ? options.around : 0;
+    const exposeSelection = !!options.search || around > 0 || limit != null || after != null;
+
+    let paragraphs = selectedMatches;
+    if (around > 0 && options.search) {
+        const directIndexes = new Set(selectedMatches.map(item => item.index));
+        const contextFor = new Map();
+        for (const match of selectedMatches) {
+            const start = Math.max(rangeStart, match.index - around);
+            const end = Math.min(rangeEnd, match.index + around);
+            for (let index = start; index <= end; index++) {
+                if (directIndexes.has(index)) continue;
+                const owners = contextFor.get(index) || [];
+                owners.push(match.index);
+                contextFor.set(index, owners);
+            }
+        }
+        const returnedIndexes = new Set([...directIndexes, ...contextFor.keys()]);
+        paragraphs = allParagraphs
+            .filter(item => returnedIndexes.has(item.index))
+            .map(item => directIndexes.has(item.index)
+                ? { ...item, selectionRole: 'match' }
+                : { ...item, selectionRole: 'context', contextFor: contextFor.get(item.index) || [] });
+    } else if (exposeSelection) {
+        paragraphs = selectedMatches.map(item => ({ ...item, selectionRole: 'match' }));
+    }
+
+    return {
+        paragraphs,
+        ...(exposeSelection ? {
+            selection: {
+                ...(options.search ? { search: String(options.search), caseSensitive: false } : {}),
+                totalMatches,
+                returnedMatches: selectedMatches.length,
+                returnedParagraphs: paragraphs.length,
+                truncated,
+                nextAfter: truncated && selectedMatches.length > 0
+                    ? selectedMatches[selectedMatches.length - 1].index
+                    : null,
+                ...(limit != null ? { limit } : {}),
+                ...(after != null ? { after } : {}),
+                ...(around > 0 ? { around } : {})
+            }
+        } : {})
+    };
+}
+
 /** Read-only, stable document-parts inspection for agents and package adapters. */
 export function inspectDocumentParts(parts, options = {}) {
     const documentPart = parseXml(parts?.documentXml, 'word/document.xml', true);
@@ -199,9 +273,10 @@ export function inspectDocumentParts(parts, options = {}) {
     const resolveNumbering = createNumberingResolver(numberingPart.doc);
     let nearestHeading = null;
     const paragraphNodes = getDocumentParagraphNodes(documentPart.doc);
-    const commentAnchors = collectDocumentCommentAnchors(paragraphNodes, options.revisionView || 'accepted');
+    const revisionView = options.revisionView === 'rejected' ? 'rejected' : 'accepted';
+    const commentAnchors = collectDocumentCommentAnchors(paragraphNodes, revisionView);
     let paragraphs = paragraphNodes.map((paragraph, zeroIndex) => {
-        const text = extractCanonicalParagraphText(paragraph, { revisionView: options.revisionView || 'accepted' });
+        const text = extractCanonicalParagraphText(paragraph, { revisionView });
         const level = headingLevel(paragraph);
         if (level) nearestHeading = { level, text };
         const ids = [...new Set([...descendants(paragraph, 'commentRangeStart'), ...descendants(paragraph, 'commentReference')].map(node => attr(node, 'id')).filter(Boolean))];
@@ -212,11 +287,17 @@ export function inspectDocumentParts(parts, options = {}) {
         const index = zeroIndex + 1;
         const provision = list?.label && list.format !== 'bullet' ? list.label : null;
         const headingText = nearestHeading?.text || null;
-        const humanReference = [provision, headingText, text.slice(0, options.excerptLength || 120)].filter(Boolean).join(' — ');
+        const excerpt = text.slice(0, options.excerptLength || 120);
+        const humanReference = level
+            ? text
+            : (provision
+                ? [provision, headingText].filter(Boolean).join(' — ')
+                : (headingText ? [headingText, excerpt].filter(Boolean).join(' — ') : excerpt));
         const segments = extractParagraphRevisionSegments(paragraph);
         return {
-            index, ref: `P${index}`, paragraphId: getParagraphId(paragraph), fingerprint: createParagraphFingerprint(paragraph),
-            text, exactText: text, excerpt: text.slice(0, options.excerptLength || 120), humanReference, inTable: hasAncestor(paragraph, 'tc'), table: structure.table,
+            index, ref: `P${index}`, paragraphId: getParagraphId(paragraph),
+            fingerprint: createParagraphFingerprint(paragraph, { text, index, revisionView }), revisionView,
+            text, exactText: text, excerpt, humanReference, provision, inTable: hasAncestor(paragraph, 'tc'), table: structure.table,
             styleId, headingLevel: level, nearestHeading, list, structuralReferences: structure.references, hasRevisions: authors.length > 0, revisionAuthors: authors, commentIds: ids,
             segments
         };
@@ -227,12 +308,8 @@ export function inspectDocumentParts(parts, options = {}) {
         definition.anchoredText ??= commentAnchors.get(id) || paragraph.text;
         comments.set(id, definition);
     }
-    if (options.revisedOnly) paragraphs = paragraphs.filter(item => item.hasRevisions);
-    if (options.inTable != null) paragraphs = paragraphs.filter(item => item.inTable === !!options.inTable);
-    if (options.skipEmpty) paragraphs = paragraphs.filter(item => item.text.length > 0);
-    if (options.search) { const needle = String(options.search).toLowerCase(); paragraphs = paragraphs.filter(item => item.text.toLowerCase().includes(needle)); }
-    if (Array.isArray(options.indexes)) { const indexes = new Set(options.indexes); paragraphs = paragraphs.filter(item => indexes.has(item.index)); }
-    if (options.range) { const start = Number(options.range.start ?? options.range[0]); const end = Number(options.range.end ?? options.range[1]); paragraphs = paragraphs.filter(item => item.index >= start && item.index <= end); }
+    const selected = selectInspectionParagraphs(paragraphs, options);
+    paragraphs = selected.paragraphs;
     const allRevisionAuthors = [...new Set(paragraphs.flatMap(item => item.revisionAuthors))].sort();
     const coveredEntries = extractDocumentPartsEntries(parts);
     const coveredParts = coveredEntries.map(e => e.name).sort();
@@ -249,6 +326,7 @@ export function inspectDocumentParts(parts, options = {}) {
         revisionToken,
         coveredParts,
         paragraphs,
+        ...(selected.selection ? { selection: selected.selection } : {}),
         comments: [...comments.values()],
         revisionAuthors: allRevisionAuthors,
         commentAuthors: [...new Set([...comments.values()].map(item => item.author).filter(Boolean))].sort(),