@ansonlai/docx-redline-js 0.5.3 → 0.6.0

package/services/document-operation-applier.js

@@ -1,5 +1,5 @@
 import { getDefaultAuthor } from '../adapters/config.js';
-import {
+import {
     normalizeDocumentOperation,
     resolveDocumentOperationAuthor,
     validateDocumentOperation
@@ -15,6 +15,7 @@ import {
     applyFormattingToParagraphByExactText,
     applyHighlightToParagraphByExactText,
     applyParagraphFormatToParagraphByExactText,
+    insertIntoRejectedDeletedText,
     restoreDeletedParagraphByExactText,
     applyToParagraphByExactText
 } from './document-operation-mutations.js';
@@ -26,22 +27,25 @@ import {
 import {
     createEmptyReceipt,
     reconcileReceiptsAgainstOutput
-} from './receipt-collector.js';
-
-export function normalizeOperationError(error) {
-    return {
-        code: typeof error?.code === 'string' && error.code ? error.code : 'OPERATION_ERROR',
-        message: error?.message || String(error),
-        ...(Array.isArray(error?.candidates) ? { candidates: error.candidates } : {})
-    };
-}
+} from './receipt-collector.js';
+import { validateRedlineOoxml } from '../core/redline-validation.js';
+import { subtractValidationIssueMultiset, validationErrors } from '../core/validation-delta.js';
+import { normalizeErrorWithRecovery } from './error-recovery.js';
+
+export function normalizeOperationError(error, context = {}) {
+    return normalizeErrorWithRecovery(error, context);
+}
 
 /**
  * Validates and dispatches one structured operation against full document XML.
  * Result metadata is assembled here so every mutation path exposes the same
  * */
-export async function applyOperationToDocumentXml(documentXml, op, author, runtimeContext = null, options = {}) {
-    const operationIndex = typeof options._operationIndex === 'number' ? options._operationIndex : 1;
+export async function applyOperationToDocumentXml(documentXml, op, author, runtimeContext = null, options = {}) {
+    const operationIndex = typeof options._operationIndex === 'number' ? options._operationIndex : 1;
+    const errorContext = {
+        operationIndex,
+        ...(typeof op?.operationId === 'string' ? { operationId: op.operationId } : {})
+    };
     const validation = validateDocumentOperation(op);
     if (!validation.valid) {
         const authorUsed = resolveDocumentOperationAuthor(op, author, getDefaultAuthor());
@@ -49,7 +53,7 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
             documentXml,
             hasChanges: false,
             status: 'error',
-            error: validation.error,
+            error: normalizeOperationError(validation.error, errorContext),
             operationType: normalizeDocumentOperation(op).operationKind,
             authorUsed,
             receipt: createEmptyReceipt(operationIndex, op?.operationId, authorUsed, 'refused')
@@ -61,6 +65,8 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
 
     if (
         operation.operationKind !== 'comment_reply'
+        && operation.operationKind !== 'rejected-insert'
+        && operation.operationKind !== 'restore'
         && (
             operation.targetDescriptor?.revisionView === 'rejected'
             || operation.targetEndDescriptor?.revisionView === 'rejected'
@@ -70,10 +76,10 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
             documentXml,
             hasChanges: false,
             status: 'error',
-            error: {
-                code: 'UNSUPPORTED_REVISION_VIEW_MUTATION',
-                message: 'Targeting rejected revision view for mutation is not supported yet.'
-            },
+            error: normalizeOperationError({
+                code: 'UNSUPPORTED_REVISION_VIEW_MUTATION',
+                message: 'Targeting rejected revision view for mutation is not supported yet.'
+            }, errorContext),
             operationType: operation.operationKind,
             authorUsed,
             receipt: createEmptyReceipt(operationIndex, operation.operationId, authorUsed, 'refused')
@@ -87,10 +93,10 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
                 documentXml,
                 hasChanges: false,
                 status: 'error',
-                error: {
-                    code: tokenValidation.error?.code || 'INVALID_REVISION_TOKEN',
-                    message: tokenValidation.error?.message || 'Invalid revision token.'
-                },
+                error: normalizeOperationError({
+                    code: tokenValidation.error?.code || 'INVALID_REVISION_TOKEN',
+                    message: tokenValidation.error?.message || 'Invalid revision token.'
+                }, errorContext),
                 operationType: operation.operationKind,
                 authorUsed,
                 receipt: createEmptyReceipt(operationIndex, operation.operationId, authorUsed, 'refused')
@@ -101,10 +107,10 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
                 documentXml,
                 hasChanges: false,
                 status: 'error',
-                error: {
-                    code: 'REVISION_TOKEN_SCOPE_MISMATCH',
-                    message: `Revision token scope mismatch: expected 'document-parts', got '${options.expectedRevision.scope}'.`
-                },
+                error: normalizeOperationError({
+                    code: 'REVISION_TOKEN_SCOPE_MISMATCH',
+                    message: `Revision token scope mismatch: expected 'document-parts', got '${options.expectedRevision.scope}'.`
+                }, errorContext),
                 operationType: operation.operationKind,
                 authorUsed,
                 receipt: createEmptyReceipt(operationIndex, operation.operationId, authorUsed, 'refused')
@@ -122,10 +128,12 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
                 documentXml,
                 hasChanges: false,
                 status: 'error',
-                error: {
-                    code: 'REVISION_MISMATCH',
-                    message: `Document revision mismatch: expected '${options.expectedRevision.value}', current is '${currentToken.value}'.`
-                },
+                error: normalizeOperationError({
+                    code: 'REVISION_MISMATCH',
+                    message: `Document revision mismatch: expected '${options.expectedRevision.value}', current is '${currentToken.value}'.`,
+                    expectedRevision: options.expectedRevision,
+                    currentRevision: currentToken
+                }, errorContext),
                 operationType: operation.operationKind,
                 authorUsed,
                 receipt: createEmptyReceipt(operationIndex, operation.operationId, authorUsed, 'refused')
@@ -141,7 +149,7 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
             documentXml,
             hasChanges: false,
             status: 'error',
-            error: session.parseResult.error,
+            error: normalizeOperationError(session.parseResult.error, errorContext),
             warnings: session.parseResult.warnings,
             operationType: operation.operationKind,
             authorUsed,
@@ -156,7 +164,9 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
         operation.operationId,
         authorUsed
     );
-    const operationWarnings = [];
+    const operationWarnings = Array.isArray(operation._compiledWarnings)
+        ? [...operation._compiledWarnings]
+        : [];
     const operationOptions = {
         ...options,
         ...(typeof operation.generateRedlines === 'boolean' ? { generateRedlines: operation.generateRedlines } : {}),
@@ -168,6 +178,10 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
         ...(operation.formattingRevisionPolicy ? { formattingRevisionPolicy: operation.formattingRevisionPolicy } : {}),
         targetDescriptor: operation.targetDescriptor,
         targetEndDescriptor: operation.targetEndDescriptor,
+        _compiledSourceId: operation._compiledSourceId || null,
+        _compiledSourceEndId: operation._compiledSourceEndId || null,
+        _compiledResolvedBy: operation._compiledResolvedBy || null,
+        _sourceTargetRegistry: session.sourceTargetRegistry || null,
         _resolutionCapture: resolutionCapture,
         _revisionIdAllocator: session.revisionIdAllocator,
         _documentOperationSession: session,
@@ -250,6 +264,17 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
                 runtimeContext,
                 operationOptions
             );
+        } else if (operation.operationKind === 'rejected-insert') {
+            result = await insertIntoRejectedDeletedText(
+                documentXml,
+                operation.target,
+                operation.anchor,
+                operation.modified,
+                authorUsed,
+                operation.targetRef,
+                runtimeContext,
+                operationOptions
+            );
         } else if (operation.operationKind === 'restore') {
             result = await restoreDeletedParagraphByExactText(
                 documentXml,
@@ -311,8 +336,45 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
                     operationReceipt.warnings.push(String(w));
                 }
             }
-        } else {
-            session.markMutationCommitted(operation.operationKind !== 'comment_reply');
+        } else {
+            const beforeValidation = validateRedlineOoxml(savepoint.document);
+            const afterValidation = validateRedlineOoxml(session.document);
+            const generatedIssues = subtractValidationIssueMultiset(afterValidation.issues, beforeValidation.issues);
+            const generatedErrors = validationErrors(generatedIssues);
+            if (generatedErrors.length > 0) {
+                session.restoreSavepoint(savepoint);
+                operationReceipt = createEmptyReceipt(
+                    operationIndex,
+                    operation.operationId,
+                    authorUsed,
+                    'refused'
+                );
+                const codes = [...new Set(generatedErrors.map(issue => issue.code))].join(', ');
+                return {
+                    documentXml,
+                    hasChanges: false,
+                    status: 'error',
+                    error: normalizeOperationError({
+                        code: 'GENERATED_OOXML_INVALID',
+                        stage: 'validation',
+                        message: `Operation introduced invalid OOXML (${codes}).`,
+                        generatedIssues: generatedErrors
+                    }, errorContext),
+                    operationType: operation.operationKind,
+                    authorUsed,
+                    receipt: operationReceipt,
+                    ...resolutionCapture
+                };
+            }
+            session.markMutationCommitted(operation.operationKind !== 'comment_reply');
+            if (operation._compiledSourceId && session.sourceTargetRegistry) {
+                session.sourceTargetRegistry.commitMutation(
+                    operation._compiledSourceId,
+                    operationOptions._mutationRemovedNodes,
+                    operationOptions._mutationLiveNodes,
+                    operationIndex
+                );
+            }
             if (operation.captureKey && session.captureTable) {
                 session.captureTable.set(
                     operation.captureKey,
@@ -349,7 +411,7 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
                         documentXml,
                         hasChanges: false,
                         status: 'error',
-                        error: reconciliation.error,
+                        error: normalizeOperationError(reconciliation.error, errorContext),
                         warnings: [reconciliation.error.message],
                         operationType: operation.operationKind,
                         authorUsed,
@@ -359,7 +421,8 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
                 }
             }
         }
-        return {
+        if (result?.error) result.error = normalizeOperationError(result.error, errorContext);
+        return {
             ...result,
             operationType: operation.operationKind,
             authorUsed,
@@ -368,7 +431,7 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
         };
     } catch (error) {
         session.restoreSavepoint(savepoint);
-        const normalizedError = normalizeOperationError(error);
+        const normalizedError = normalizeOperationError(error, errorContext);
         const operationReceipt = createEmptyReceipt(
             operationIndex,
             operation.operationId,

package/services/document-operation-contract.js

@@ -43,6 +43,7 @@ function nonEmptyString(value) {
 
 export function getCanonicalOperationType(operation) {
     const type = operation?.type;
+    if (type === 'insert' && operation?.target?.revisionView === 'rejected') return 'rejected-insert';
     if (type === 'restore') return 'restore';
     if (type === 'comment' || type === 'comment_reply' || type === 'highlight') return type;
     if (type === 'paragraph-format') return 'paragraph-format';
@@ -50,7 +51,8 @@ export function getCanonicalOperationType(operation) {
     return 'redline';
 }
 
-export function normalizeTargetDescriptor(target, legacyTargetRef = null) {
+export function normalizeTargetDescriptor(target, legacyTargetRef = null, defaultRevisionView = 'accepted') {
+    const fallbackRevisionView = defaultRevisionView === 'rejected' ? 'rejected' : 'accepted';
     if (!isRecord(target)) {
         return {
             text: typeof target === 'string' ? target : '',
@@ -59,7 +61,7 @@ export function normalizeTargetDescriptor(target, legacyTargetRef = null) {
             occurrence: null,
             inTable: null,
             fingerprint: null,
-            revisionView: 'accepted'
+            revisionView: fallbackRevisionView
         };
     }
 
@@ -76,7 +78,9 @@ export function normalizeTargetDescriptor(target, legacyTargetRef = null) {
         fingerprint: nonEmptyString(target.fingerprint)
             ? target.fingerprint.trim()
             : (nonEmptyString(target.sourceFingerprint) ? target.sourceFingerprint.trim() : null),
-        revisionView: target.revisionView === 'rejected' ? 'rejected' : 'accepted',
+        revisionView: target.revisionView === 'rejected'
+            ? 'rejected'
+            : (target.revisionView === 'accepted' ? 'accepted' : fallbackRevisionView),
         captureRef: nonEmptyString(target.captureRef) ? target.captureRef.trim() : null,
         select: typeof target.select === 'string' ? target.select : null
     };
@@ -84,17 +88,24 @@ export function normalizeTargetDescriptor(target, legacyTargetRef = null) {
 
 export function normalizeDocumentOperation(operation) {
     const source = isRecord(operation) ? operation : {};
-    const targetDescriptor = normalizeTargetDescriptor(source.target, source.targetRef);
+    const kind = getCanonicalOperationType(source);
+    const defaultRevisionView = kind === 'restore' ? 'rejected' : 'accepted';
+    const targetDescriptor = normalizeTargetDescriptor(source.target, source.targetRef, defaultRevisionView);
     const targetEndDescriptor = source.targetEnd != null
-        ? normalizeTargetDescriptor(source.targetEnd, source.targetEndRef)
+        ? normalizeTargetDescriptor(source.targetEnd, source.targetEndRef, defaultRevisionView)
         : null;
-    const kind = getCanonicalOperationType(source);
 
     return {
         ...source,
         operationId: nonEmptyString(source.operationId) ? source.operationId.trim() : null,
         captureKey: nonEmptyString(source.captureKey) ? source.captureKey.trim() : null,
         operationKind: kind,
+        anchor: isRecord(source.anchor) ? {
+            exactText: typeof source.anchor.exactText === 'string' ? source.anchor.exactText : '',
+            occurrence: Number.isInteger(source.anchor.occurrence) && source.anchor.occurrence > 0 ? source.anchor.occurrence : 1,
+            occurrenceExplicit: Number.isInteger(source.anchor.occurrence) && source.anchor.occurrence > 0,
+            offset: Number.isInteger(source.anchor.offset) ? source.anchor.offset : null
+        } : null,
         targetDescriptor,
         targetEndDescriptor,
         target: targetDescriptor.text,
@@ -211,6 +222,39 @@ export function validateDocumentOperation(operation) {
         };
     }
 
+    if (normalized.operationKind === 'rejected-insert') {
+        if (!nonEmptyString(normalized.modified)) {
+            return {
+                valid: false,
+                error: { code: 'INVALID_OPERATION', message: 'Rejected-view insert operations require non-empty string "modified" text.' }
+            };
+        }
+        if (
+            !normalized.anchor
+            || !nonEmptyString(normalized.anchor.exactText)
+            || !Number.isInteger(normalized.anchor.offset)
+            || normalized.anchor.offset < 0
+            || normalized.anchor.offset > normalized.anchor.exactText.length
+        ) {
+            return {
+                valid: false,
+                error: {
+                    code: 'INVALID_OPERATION',
+                    message: 'Rejected-view insert operations require anchor.exactText, a positive occurrence, and an offset within the anchor text.'
+                }
+            };
+        }
+        if (normalized.existingRevisions !== 'slice-cross-author') {
+            return {
+                valid: false,
+                error: {
+                    code: 'INVALID_OPERATION',
+                    message: 'Rejected-view insert operations require existingRevisions: "slice-cross-author".'
+                }
+            };
+        }
+    }
+
     if (normalized.operationKind === 'restore') {
         const validSingle = nonEmptyString(normalized.modified);
         const validRange = Array.isArray(normalized.modified)