@ansonlai/docx-redline-js 0.6.2 → 0.7.1

package/services/operation-batch-compiler.js

@@ -9,15 +9,23 @@ import {
     normalizeTargetDescriptor,
     validateDocumentOperation
 } from './document-operation-contract.js';
+import { compileExactReplacements } from './localized-replacement-compiler.js';
 
 const TEXT_WRITE_KINDS = new Set(['redline', 'restore', 'rejected-insert']);
 const FORMAT_WRITE_KINDS = new Set(['highlight', 'format', 'paragraph-format']);
 
 function normalizedError(error) {
+    const details = {};
+    if (error && typeof error === 'object') {
+        for (const [key, value] of Object.entries(error)) {
+            if (key === 'name' || key === 'stack' || key === 'message' || key === 'code') continue;
+            details[key] = value;
+        }
+    }
     return {
         code: typeof error?.code === 'string' && error.code ? error.code : 'OPERATION_ERROR',
         message: error?.message || String(error),
-        ...(Array.isArray(error?.candidates) ? { candidates: error.candidates } : {})
+        ...details
     };
 }
 
@@ -266,6 +274,39 @@ export function compileOperationBatch(xmlDoc, operations = [], options = {}) {
                 compiled._compiledResolvedBy = start.resolvedBy;
                 if (binding.warnings.length > 0) compiled._compiledWarnings = binding.warnings;
 
+                if (Array.isArray(operation.replacements)) {
+                    const patchCompilation = compileExactReplacements(
+                        start.metadata.text,
+                        operation.replacements
+                    );
+                    if (!patchCompilation.ok) {
+                        throw Object.assign(new Error(patchCompilation.error.message), patchCompilation.error);
+                    }
+                    compiled.modified = patchCompilation.desiredText;
+                    delete compiled.replacements;
+                    compiled._localizedReplacementCompilation = {
+                        sourceText: start.metadata.text,
+                        desiredText: patchCompilation.desiredText,
+                        replacements: patchCompilation.replacements
+                    };
+                    const canonicalValidation = validateDocumentOperation(compiled);
+                    if (!canonicalValidation.valid) {
+                        throw Object.assign(
+                            new Error(canonicalValidation.error.message),
+                            canonicalValidation.error
+                        );
+                    }
+                } else if (operation.operationKind === 'restore' && sourceOperation.modified === undefined) {
+                    compiled.modified = start.metadata.text;
+                    const canonicalValidation = validateDocumentOperation(compiled);
+                    if (!canonicalValidation.valid) {
+                        throw Object.assign(
+                            new Error(canonicalValidation.error.message),
+                            canonicalValidation.error
+                        );
+                    }
+                }
+
                 const targetEndDescriptor = operation.targetEndDescriptor
                     || (operation.targetEndRef != null
                         ? normalizeTargetDescriptor(null, operation.targetEndRef, operation.targetDescriptor.revisionView)

package/services/operation-preflight.js

@@ -136,11 +136,16 @@ export function preflightOperations(documentXml, operations, author, options = {
     let commentsRequired = false;
     let numberingRequired = false;
 
-    for (let index = 0; index < sourceOperations.length; index++) {
-        const sourceOperation = sourceOperations[index];
-        const validation = validateDocumentOperation(sourceOperation);
-        const fallbackOperation = normalizeDocumentOperation(sourceOperation);
-        const operation = validation.operation || fallbackOperation;
+    for (let index = 0; index < sourceOperations.length; index++) {
+        const sourceOperation = sourceOperations[index];
+        const compiledBinding = batchCompilation.bindings[index];
+        const compiledOperation = batchCompilation.compiledOperations[index];
+        const operationInput = !compiledBinding?.error && compiledOperation?._localizedReplacementCompilation
+            ? compiledOperation
+            : sourceOperation;
+        const validation = validateDocumentOperation(operationInput);
+        const fallbackOperation = normalizeDocumentOperation(sourceOperation);
+        const operation = validation.operation || fallbackOperation;
         const authorUsed = resolveDocumentOperationAuthor(operation, author, getDefaultAuthor());
         authorsUsed.add(authorUsed);
 
@@ -187,7 +192,6 @@ export function preflightOperations(documentXml, operations, author, options = {
             continue;
         }
 
-        const compiledBinding = batchCompilation.bindings[index];
         if (compiledBinding?.error) {
             results.push({
                 index: index + 1,

package/services/standalone-operation-runner.d.ts

@@ -31,6 +31,12 @@ export interface RejectedTextInsertionAnchor {
   offset: number;
 }
 
+export interface LocalizedReplacement {
+  find: string;
+  replace: string;
+  occurrence?: number;
+}
+
 export interface DocumentOperationBase {
   operationId?: string;
   captureKey?: string;
@@ -43,9 +49,7 @@ export interface DocumentOperationBase {
   insertionAffinity?: InsertionAffinity;
 }
 
-export interface RedlineDocumentOperation extends DocumentOperationBase {
-  type: 'redline' | 'replace' | 'format' | 'list-change' | 'table-reconciliation' | 'insert';
-  modified: string;
+interface RedlineDocumentOperationCommon extends DocumentOperationBase {
   structuredContent?: boolean;
   targetEnd?: ParagraphTargetDescriptor;
   targetEndRef?: number | string | null;
@@ -53,13 +57,50 @@ export interface RedlineDocumentOperation extends DocumentOperationBase {
   anchor?: RejectedTextInsertionAnchor;
 }
 
-export interface RestoreDocumentOperation extends DocumentOperationBase {
+export type RedlineDocumentOperation =
+  | (RedlineDocumentOperationCommon & {
+      type: 'redline' | 'replace';
+      modified: string;
+      replacements?: never;
+    })
+  | (RedlineDocumentOperationCommon & {
+      type: 'redline' | 'replace';
+      modified?: never;
+      /** Exact, case-sensitive replacements in one batch-start accepted-view paragraph. */
+      replacements: LocalizedReplacement[];
+    })
+  | (RedlineDocumentOperationCommon & {
+      type: 'format' | 'list-change' | 'table-reconciliation' | 'insert';
+      modified: string;
+      replacements?: never;
+    });
+
+interface RestoreDocumentOperationCommon extends DocumentOperationBase {
   type: 'restore';
-  modified: string | string[];
-  targetEnd?: ParagraphTargetDescriptor;
-  targetEndRef?: number | string | null;
 }
 
+export type RestoreDocumentOperation =
+  | (RestoreDocumentOperationCommon & {
+      modified: string | string[];
+      replacements?: never;
+      targetEnd?: ParagraphTargetDescriptor;
+      targetEndRef?: number | string | null;
+    })
+  | (RestoreDocumentOperationCommon & {
+      modified?: never;
+      /** Exact, case-sensitive replacements in one strong rejected-view paragraph. */
+      replacements: LocalizedReplacement[];
+      targetEnd?: never;
+      targetEndRef?: never;
+    })
+  | (RestoreDocumentOperationCommon & {
+      /** Omit modified to restore one strong rejected-view paragraph verbatim. */
+      modified?: never;
+      replacements?: never;
+      targetEnd?: never;
+      targetEndRef?: never;
+    });
+
 export interface DeleteDocumentOperation extends DocumentOperationBase {
   type: 'delete';
   modified?: '';
@@ -133,6 +174,7 @@ export interface ResolvedDocumentTarget {
   paragraphId: string | null;
   text: string;
   fingerprint?: string;
+  revisionView?: 'accepted' | 'rejected';
   inTable?: boolean;
   targetTextMatch?: {
     mode: 'exact' | 'space_equivalent' | 'normalized';
@@ -190,6 +232,34 @@ export interface MutationReceipt {
   warnings: string[];
 }
 
+export interface LocalizedReplacementChange {
+  kind: 'localized_replacement';
+  committed: boolean;
+  finalDisposition: 'applied' | 'rolled_back';
+  target: {
+    paragraphId?: string;
+    index?: number;
+    fingerprint?: string;
+    humanReference?: string;
+  };
+  context?: {
+    search?: string;
+    range?: string;
+    anchorMatchCount?: number;
+    humanReference?: string;
+  };
+  replacements: Array<{
+    find: string;
+    replace: string;
+    occurrence?: number;
+    beforeExcerpt: string;
+    afterExcerpt: string;
+  }>;
+  verification: {
+    acceptedViewMatchesCompiledText: boolean;
+  };
+}
+
 export interface DocumentOperationResult {
   documentXml: string;
   hasChanges: boolean;
@@ -207,6 +277,7 @@ export interface DocumentOperationResult {
   resolvedTarget?: ResolvedDocumentTarget;
   resolvedAnchor?: ResolvedCommentAnchor;
   receipt?: MutationReceipt;
+  change?: LocalizedReplacementChange;
 }
 
 export interface BatchOperationItemResult {
@@ -221,6 +292,7 @@ export interface BatchOperationItemResult {
   warnings?: string[];
   error?: RedlineError;
   receipt?: MutationReceipt;
+  change?: LocalizedReplacementChange;
 }
 
 export interface DocumentOperationBatchResult {