@ansonlai/docx-redline-js 0.5.3 → 0.6.0

package/services/operation-preflight.js

@@ -29,14 +29,12 @@ import {
     resolveDocumentOperationAuthor,
     validateDocumentOperation
 } from './document-operation-contract.js';
-import { buildOperationDependencyPlan } from './batch-operation-orchestrator.js';
-
-function normalizedError(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 } : {})
-    };
+import { buildOperationDependencyPlan } from './batch-operation-orchestrator.js';
+import { compileOperationBatch } from './operation-batch-compiler.js';
+import { normalizeErrorWithRecovery } from './error-recovery.js';
+
+function normalizedError(error, context = {}) {
+    return normalizeErrorWithRecovery(error, context);
 }
 
 function operationNeedsNumbering(operation) {
@@ -70,10 +68,6 @@ function targetMetadata(xmlDoc, paragraph, resolvedBy, suppliedText, paragraphMe
     };
 }
 
-function buildConflict(code, message, operationIndexes, target) {
-    return { code, message, operationIndexes, target };
-}
-
 function getCommentIdsInParagraph(paragraph) {
     const ids = new Set();
     for (const localName of ['commentRangeStart', 'commentRangeEnd', 'commentReference']) {
@@ -90,10 +84,10 @@ export function preflightOperations(documentXml, operations, author, options = {
         return {
             valid: false,
             status: 'error',
-            error: {
+            error: normalizedError({
                 code: 'INVALID_OPERATION',
                 message: `Unsupported existingRevisions policy: "${String(options.existingRevisions)}".`
-            },
+            }),
             results: [],
             conflicts: [],
             authorsUsed: [],
@@ -105,7 +99,7 @@ export function preflightOperations(documentXml, operations, author, options = {
         return {
             valid: false,
             status: 'error',
-            error: parsed.error,
+            error: normalizedError(parsed.error),
             results: [],
             conflicts: [],
             authorsUsed: [],
@@ -119,19 +113,23 @@ export function preflightOperations(documentXml, operations, author, options = {
         rejected: null
     };
     const sourceOperations = Array.isArray(operations) ? operations : [];
-    const dependencyPlan = buildOperationDependencyPlan(sourceOperations);
-    if (!dependencyPlan.valid) {
+    const batchCompilation = compileOperationBatch(xmlDoc, sourceOperations, {
+        strictTargets: options.strictTargets !== false,
+        onInfo: options.onInfo,
+        onWarn: options.onWarn
+    });
+    const dependencyPlan = buildOperationDependencyPlan(batchCompilation.compiledOperations);
+    if (!dependencyPlan.valid) {
         return {
             valid: false,
             status: 'error',
-            error: dependencyPlan.error,
+            error: normalizedError(dependencyPlan.error),
             results: [],
             conflicts: [],
             authorsUsed: [],
             requiredArtifacts: { comments: false, numbering: false }
         };
-    }
-
+    }
     const strictTargets = options.strictTargets !== false;
     const results = [];
     const authorsUsed = new Set();
@@ -175,7 +173,7 @@ export function preflightOperations(documentXml, operations, author, options = {
             continue;
         }
 
-        if (operation.targetDescriptor?.captureRef) {
+        if (operation.targetDescriptor?.captureRef) {
             results.push({
                 index: index + 1,
                 type: sourceOperation?.type || 'redline',
@@ -186,8 +184,35 @@ export function preflightOperations(documentXml, operations, author, options = {
                 captureRef: operation.targetDescriptor.captureRef,
                 ...(operation.targetDescriptor.select ? { select: operation.targetDescriptor.select } : {})
             });
-            continue;
-        }
+            continue;
+        }
+
+        const compiledBinding = batchCompilation.bindings[index];
+        if (compiledBinding?.error) {
+            results.push({
+                index: index + 1,
+                type: sourceOperation?.type || 'redline',
+                operationType: operation.operationKind,
+                status: 'error',
+                authorUsed,
+                error: compiledBinding.error
+            });
+            continue;
+        }
+        if (compiledBinding?.createdByOperation) {
+            results.push({
+                index: index + 1,
+                type: sourceOperation?.type || 'redline',
+                operationType: operation.operationKind,
+                status: 'deferred',
+                authorUsed,
+                resolvedBy: 'created_content_dependency',
+                captureRef: compiledBinding.captureRef,
+                select: operation.targetDescriptor.text,
+                createdByOperation: compiledBinding.createdByOperation
+            });
+            continue;
+        }
 
         const targetView = operation.targetDescriptor?.revisionView === 'rejected' ? 'rejected' : 'accepted';
         let currentMetadataIndex = targetView === 'rejected'
@@ -195,17 +220,28 @@ export function preflightOperations(documentXml, operations, author, options = {
             : metadataIndices.accepted;
 
         try {
-            const resolved = resolveTargetParagraph(xmlDoc, {
-                targetText: operation.target,
-                targetRef: operation.targetRef,
-                targetDescriptor: operation.targetDescriptor,
-                opType: operation.operationKind,
-                strictAmbiguity: strictTargets,
-                paragraphMetadataIndex: currentMetadataIndex,
-                metadataIndices,
-                onInfo: options.onInfo,
-                onWarn: options.onWarn
-            });
+            let resolved;
+            if (compiledBinding.dynamic) {
+                resolved = resolveTargetParagraph(xmlDoc, {
+                    targetText: operation.target,
+                    targetRef: operation.targetRef,
+                    targetDescriptor: operation.targetDescriptor,
+                    opType: operation.operationKind,
+                    strictAmbiguity: strictTargets,
+                    paragraphMetadataIndex: currentMetadataIndex,
+                    metadataIndices,
+                    onInfo: options.onInfo,
+                    onWarn: options.onWarn
+                });
+            } else {
+                const bound = batchCompilation.registry.resolve(compiledBinding.sourceIds[0], xmlDoc);
+                if (bound.error) throw Object.assign(new Error(bound.error.message), bound.error);
+                resolved = {
+                    paragraph: bound.paragraph,
+                    resolvedBy: compiledBinding.resolvedBy,
+                    warnings: compiledBinding.warnings
+                };
+            }
             const paragraph = resolved.paragraph;
             const metadata = targetMetadata(xmlDoc, paragraph, resolved.resolvedBy, operation.target, currentMetadataIndex, targetView);
             const paragraphText = metadata.resolvedTarget.text;
@@ -313,8 +349,10 @@ export function preflightOperations(documentXml, operations, author, options = {
                     const allSame = authors.length > 0 && 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'}). Pass existingRevisions: "accept-all-first" or resolve revisions first.`
+                            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.`,
+                            revisionAuthors: authors,
+                            currentPolicy: existingPolicy
                         };
                     } else if (allSame) {
                         const mergeCommentIds = getCommentIdsInParagraph(paragraph);
@@ -408,43 +446,24 @@ export function preflightOperations(documentXml, operations, author, options = {
         }
     }
 
-    const conflicts = [];
-    const byTarget = new Map();
-    for (const result of results) {
-        const targetIndex = result.resolvedTarget?.index;
-        if (!targetIndex) continue;
-        if (!byTarget.has(targetIndex)) byTarget.set(targetIndex, []);
-        byTarget.get(targetIndex).push(result);
-    }
-
-    for (const [targetIndex, targetResults] of byTarget) {
-        const redlines = targetResults.filter(result => ['redline', 'restore'].includes(result.operationType));
-        const highlights = targetResults.filter(result => result.operationType === 'highlight');
-        const target = targetResults[0].resolvedTarget;
-        if (redlines.length > 1) {
-            conflicts.push(buildConflict(
-                'OVERLAPPING_TEXT_EDITS',
-                `Multiple text edits target paragraph ${targetIndex}; later operations may use a stale anchor.`,
-                redlines.map(result => result.index),
-                target
-            ));
-        }
-        if (redlines.length > 0 && highlights.length > 0) {
-            conflicts.push(buildConflict(
-                'REVISION_ORDER_CONFLICT',
-                `A text edit and highlight target paragraph ${targetIndex}; operation order can invalidate the target or existing-revision policy.`,
-                [...redlines, ...highlights].map(result => result.index).sort((a, b) => a - b),
-                target
-            ));
-        }
-    }
+    const conflicts = batchCompilation.conflicts;
 
-    const hasErrors = results.some(result => result.status === 'error');
-    return {
-        valid: !hasErrors && conflicts.length === 0,
-        status: !hasErrors && conflicts.length === 0 ? 'ok' : 'error',
-        results,
-        conflicts,
+    const enrichedResults = results.map(result => result.error ? {
+        ...result,
+        error: normalizedError(result.error, {
+            operationIndex: result.index,
+            ...(sourceOperations[result.index - 1]?.operationId
+                ? { operationId: sourceOperations[result.index - 1].operationId }
+                : {})
+        })
+    } : result);
+    const enrichedConflicts = conflicts.map(conflict => normalizedError(conflict));
+    const hasErrors = enrichedResults.some(result => result.status === 'error');
+    return {
+        valid: !hasErrors && enrichedConflicts.length === 0,
+        status: !hasErrors && enrichedConflicts.length === 0 ? 'ok' : 'error',
+        results: enrichedResults,
+        conflicts: enrichedConflicts,
         authorsUsed: Array.from(authorsUsed),
         requiredArtifacts: {
             comments: commentsRequired,

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

@@ -10,9 +10,11 @@ export interface ParagraphTargetDescriptor {
   inTable?: boolean;
   fingerprint?: string;
   sourceFingerprint?: string;
+  /** Defaults to rejected for restore operations and accepted for all other operations. */
   revisionView?: 'accepted' | 'rejected';
   captureRef?: string;
   select?: string;
+  createdByOperation?: number;
 }
 
 export interface InsertionAffinity {
@@ -23,6 +25,12 @@ export interface InsertionAffinity {
   comment?: 'inside' | 'outside';
 }
 
+export interface RejectedTextInsertionAnchor {
+  exactText: string;
+  occurrence?: number;
+  offset: number;
+}
+
 export interface DocumentOperationBase {
   operationId?: string;
   captureKey?: string;
@@ -41,6 +49,8 @@ export interface RedlineDocumentOperation extends DocumentOperationBase {
   structuredContent?: boolean;
   targetEnd?: ParagraphTargetDescriptor;
   targetEndRef?: number | string | null;
+  /** Required when type is insert and target.revisionView is rejected. */
+  anchor?: RejectedTextInsertionAnchor;
 }
 
 export interface RestoreDocumentOperation extends DocumentOperationBase {
@@ -124,6 +134,16 @@ export interface ResolvedDocumentTarget {
   text: string;
   fingerprint?: string;
   inTable?: boolean;
+  targetTextMatch?: {
+    mode: 'exact' | 'space_equivalent' | 'normalized';
+    differences?: Array<{
+      offset: number;
+      sourceCodePoint: string;
+      requestedCodePoint: string;
+    }>;
+    sourceExcerpt?: string;
+    requestedExcerpt?: string;
+  };
 }
 
 export interface ResolvedCommentAnchor {
@@ -220,6 +240,17 @@ export interface DocumentOperationBatchResult {
   status?: RedlineStatus;
   error?: RedlineError;
   warnings?: string[];
+  conflicts?: OperationConflict[];
+  retryPlan?: MutationRetryPlan;
+}
+
+export interface MutationRetryPlan {
+  base: 'original' | 'output';
+  committedIndexes: number[];
+  failedIndexes: number[];
+  unattemptedIndexes: number[];
+  replayWholeBatch: boolean;
+  sameArgumentsSafe: false;
 }
 
 export interface OperationPreflightItemResult {
@@ -253,10 +284,13 @@ export interface OperationPreflightItemResult {
 }
 
 export interface OperationConflict {
-  code: 'OVERLAPPING_TEXT_EDITS' | 'REVISION_ORDER_CONFLICT' | string;
+  code: 'OVERLAPPING_SOURCE_TARGETS' | 'OVERLAPPING_TEXT_EDITS' | 'REVISION_ORDER_CONFLICT' | 'CAPTURE_FANOUT_CONFLICT' | string;
   message: string;
   operationIndexes: number[];
   target: ResolvedDocumentTarget;
+  recoveryVersion?: number;
+  category?: string;
+  recovery?: RedlineError['recovery'];
 }
 
 export interface OperationPreflightResult {