@ansonlai/docx-redline-js 0.6.2 → 0.7.0

package/services/document-operation-applier.js

@@ -4,7 +4,8 @@ import {
     resolveDocumentOperationAuthor,
     validateDocumentOperation
 } from './document-operation-contract.js';
-import { DocumentOperationSession } from './document-operation-session.js';
+import { DocumentOperationSession } from './document-operation-session.js';
+import { compileOperationBatch } from './operation-batch-compiler.js';
 import {
     validateRevisionToken,
     computeDocumentPartsRevisionToken,
@@ -31,6 +32,8 @@ import {
 import { validateRedlineOoxml } from '../core/redline-validation.js';
 import { subtractValidationIssueMultiset, validationErrors } from '../core/validation-delta.js';
 import { normalizeErrorWithRecovery } from './error-recovery.js';
+import { extractCanonicalParagraphText } from '../core/paragraph-text.js';
+import { buildLocalizedReplacementChange } from './localized-replacement-compiler.js';
 
 export function normalizeOperationError(error, context = {}) {
     return normalizeErrorWithRecovery(error, context);
@@ -60,7 +63,7 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
         };
     }
 
-    const operation = validation.operation || normalizeDocumentOperation(op);
+    let operation = validation.operation || normalizeDocumentOperation(op);
     const authorUsed = resolveDocumentOperationAuthor(operation, author, getDefaultAuthor());
 
     if (
@@ -144,7 +147,7 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
     const session = options?._documentOperationSession instanceof DocumentOperationSession
         ? options._documentOperationSession
         : new DocumentOperationSession(documentXml, options);
-    if (!session.valid) {
+    if (!session.valid) {
         return {
             documentXml,
             hasChanges: false,
@@ -154,10 +157,45 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
             operationType: operation.operationKind,
             authorUsed,
             receipt: createEmptyReceipt(operationIndex, operation.operationId, authorUsed, 'refused')
-        };
-    }
-
-    const resolutionCapture = {};
+        };
+    }
+
+    if (Array.isArray(operation.replacements)) {
+        const compilation = compileOperationBatch(session.document, [op], {
+            strictTargets: options.strictTargets !== false,
+            onInfo: options.onInfo,
+            onWarn: options.onWarn
+        });
+        const compilationError = compilation.bindings[0]?.error || compilation.conflicts[0] || null;
+        if (compilationError) {
+            return {
+                documentXml,
+                hasChanges: false,
+                status: 'error',
+                error: normalizeOperationError(compilationError, errorContext),
+                operationType: operation.operationKind,
+                authorUsed,
+                receipt: createEmptyReceipt(operationIndex, operation.operationId, authorUsed, 'refused')
+            };
+        }
+        const compiledValidation = validateDocumentOperation(compilation.compiledOperations[0]);
+        if (!compiledValidation.valid) {
+            return {
+                documentXml,
+                hasChanges: false,
+                status: 'error',
+                error: normalizeOperationError(compiledValidation.error, errorContext),
+                operationType: operation.operationKind,
+                authorUsed,
+                receipt: createEmptyReceipt(operationIndex, operation.operationId, authorUsed, 'refused')
+            };
+        }
+        session.sourceTargetRegistry = compilation.registry;
+        operation = compiledValidation.operation;
+    }
+
+    const resolutionCapture = {};
+    let localizedChange = null;
     const savepoint = session.createSavepoint();
     session.receiptCollector?.beginOperation(
         operationIndex,
@@ -375,6 +413,26 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
                     operationIndex
                 );
             }
+            if (operation._localizedReplacementCompilation) {
+                let outputText = null;
+                if (operation._compiledSourceId && session.sourceTargetRegistry) {
+                    const bound = session.sourceTargetRegistry.resolve(
+                        operation._compiledSourceId,
+                        session.document
+                    );
+                    if (bound.paragraph) {
+                        outputText = extractCanonicalParagraphText(bound.paragraph, {
+                            revisionView: 'accepted'
+                        });
+                    }
+                }
+                localizedChange = buildLocalizedReplacementChange(
+                    operation._localizedReplacementCompilation,
+                    outputText,
+                    resolutionCapture.resolvedTarget || {},
+                    operation._speculativeContext || null
+                );
+            }
             if (operation.captureKey && session.captureTable) {
                 session.captureTable.set(
                     operation.captureKey,
@@ -426,8 +484,9 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
             ...result,
             operationType: operation.operationKind,
             authorUsed,
-            receipt: operationReceipt,
-            ...resolutionCapture
+            receipt: operationReceipt,
+            ...(localizedChange ? { change: localizedChange } : {}),
+            ...resolutionCapture
         };
     } catch (error) {
         session.restoreSavepoint(savepoint);

package/services/document-operation-contract.js

@@ -5,6 +5,8 @@
  * logic can operate on one internal shape.
  */
 
+import { validateExactReplacementRequests } from './localized-replacement-compiler.js';
+
 const SUPPORTED_OPERATION_TYPES = new Set([
     'redline',
     'replace',
@@ -215,11 +217,60 @@ export function validateDocumentOperation(operation) {
         };
     }
 
-    if (normalized.operationKind === 'redline' && typeof normalized.modified !== 'string') {
-        return {
-            valid: false,
-            error: { code: 'INVALID_OPERATION', message: 'Redline operations require a string "modified" field.' }
-        };
+    if (normalized.operationKind === 'redline') {
+        const hasModified = typeof normalized.modified === 'string';
+        const hasReplacements = normalized.replacements !== undefined;
+        if (hasModified === hasReplacements) {
+            return {
+                valid: false,
+                error: {
+                    code: 'INVALID_OPERATION',
+                    message: 'Redline operations require exactly one of string "modified" or non-empty "replacements".'
+                }
+            };
+        }
+        if (hasReplacements) {
+            if (rawType != null && rawType !== '' && !['redline', 'replace'].includes(rawType)) {
+                return {
+                    valid: false,
+                    error: {
+                        code: 'INVALID_OPERATION',
+                        message: 'Localized replacements are supported only for redline or replace operations.'
+                    }
+                };
+            }
+            if (
+                target.revisionView !== 'accepted'
+                || target.captureRef
+                || target.occurrence != null
+                || normalized.captureKey
+                || normalized.targetEndDescriptor
+                || normalized.targetEndRef != null
+                || /\r|\n/.test(target.text || '')
+            ) {
+                return {
+                    valid: false,
+                    error: {
+                        code: 'INVALID_OPERATION',
+                        message: 'Localized replacements v1 require one batch-start accepted-view paragraph target without captures, target occurrence, or a target range.'
+                    }
+                };
+            }
+            const replacementValidation = validateExactReplacementRequests(normalized.replacements);
+            if (!replacementValidation.ok) {
+                return { valid: false, error: replacementValidation.error };
+            }
+            if (replacementValidation.replacements.some(replacement => /\r|\n/.test(replacement.replace))) {
+                return {
+                    valid: false,
+                    error: {
+                        code: 'INVALID_OPERATION',
+                        message: 'Localized replacements v1 cannot insert paragraph breaks.'
+                    }
+                };
+            }
+            normalized.replacements = replacementValidation.replacements;
+        }
     }
 
     if (normalized.operationKind === 'rejected-insert') {

package/services/localized-replacement-compiler.js

@@ -0,0 +1,304 @@
+import { normalizeErrorWithRecovery } from './error-recovery.js';
+
+function invalidReplacement(message, field, invalidCode) {
+    return normalizeErrorWithRecovery({
+        code: invalidCode,
+        message,
+        ...(field ? { field } : {}),
+        recovery: {
+            action: 'change_request',
+            sameArgumentsSafe: false,
+            requiresReinspection: false,
+            requiresUserAuthorization: false
+        }
+    });
+}
+
+function patchError(code, message, field, recoveryAction, details = {}) {
+    return normalizeErrorWithRecovery({
+        code,
+        message,
+        field,
+        ...details,
+        recovery: {
+            action: recoveryAction,
+            sameArgumentsSafe: false,
+            requiresReinspection: false,
+            requiresUserAuthorization: false
+        }
+    });
+}
+
+function occurrenceOffsets(sourceText, find) {
+    const offsets = [];
+    let from = 0;
+    while (from <= sourceText.length - find.length) {
+        const start = sourceText.indexOf(find, from);
+        if (start < 0) break;
+        offsets.push(start);
+        from = start + 1;
+    }
+    return offsets;
+}
+
+function offsetCandidate(sourceText, start, length) {
+    const excerptStart = Math.max(0, start - 40);
+    const excerptEnd = Math.min(sourceText.length, start + length + 40);
+    return {
+        start,
+        end: start + length,
+        excerpt: sourceText.slice(excerptStart, excerptEnd)
+    };
+}
+
+function boundedExcerpt(text, start, end, limit = 120) {
+    const source = String(text ?? '');
+    const safeStart = Math.max(0, Math.min(source.length, start));
+    const safeEnd = Math.max(safeStart, Math.min(source.length, end));
+    const center = Math.floor((safeStart + safeEnd) / 2);
+    let excerptStart = Math.max(0, center - Math.floor(limit / 2));
+    let excerptEnd = Math.min(source.length, excerptStart + limit);
+    excerptStart = Math.max(0, excerptEnd - limit);
+    const prefix = excerptStart > 0 ? '…' : '';
+    const suffix = excerptEnd < source.length ? '…' : '';
+    const available = Math.max(0, limit - prefix.length - suffix.length);
+    return `${prefix}${source.slice(excerptStart, excerptStart + available)}${suffix}`;
+}
+
+/** Validate and normalize exact replacement requests without resolving source ranges. */
+export function validateExactReplacementRequests(
+    replacements,
+    field = 'replacements',
+    { invalidCode = 'INVALID_OPERATION' } = {}
+) {
+    if (!Array.isArray(replacements) || replacements.length === 0) {
+        return {
+            ok: false,
+            error: invalidReplacement('replacements must be a non-empty array.', field, invalidCode)
+        };
+    }
+
+    const normalized = [];
+    for (let index = 0; index < replacements.length; index += 1) {
+        const replacement = replacements[index];
+        const itemField = `${field}[${index}]`;
+        if (!replacement || typeof replacement !== 'object' || Array.isArray(replacement)) {
+            return {
+                ok: false,
+                error: invalidReplacement(`${itemField} must be an object.`, itemField, invalidCode)
+            };
+        }
+        if (typeof replacement.find !== 'string' || replacement.find.length === 0) {
+            return {
+                ok: false,
+                error: invalidReplacement(
+                    `${itemField}.find must be a non-empty string.`,
+                    `${itemField}.find`,
+                    invalidCode
+                )
+            };
+        }
+        if (typeof replacement.replace !== 'string') {
+            return {
+                ok: false,
+                error: invalidReplacement(
+                    `${itemField}.replace must be a string.`,
+                    `${itemField}.replace`,
+                    invalidCode
+                )
+            };
+        }
+        if (replacement.find === replacement.replace) {
+            return {
+                ok: false,
+                error: invalidReplacement(
+                    `${itemField} must change the matched text.`,
+                    itemField,
+                    invalidCode
+                )
+            };
+        }
+        const occurrence = replacement.occurrence == null ? null : Number(replacement.occurrence);
+        if (occurrence != null && (!Number.isInteger(occurrence) || occurrence < 1)) {
+            return {
+                ok: false,
+                error: invalidReplacement(
+                    `${itemField}.occurrence must be a positive integer.`,
+                    `${itemField}.occurrence`,
+                    invalidCode
+                )
+            };
+        }
+        normalized.push({
+            find: replacement.find,
+            replace: replacement.replace,
+            ...(occurrence == null ? {} : { occurrence })
+        });
+    }
+
+    return { ok: true, replacements: normalized };
+}
+
+/**
+ * Compile exact, source-relative replacement intents into complete desired text.
+ * All source ranges are resolved before mutation, so replacements are simultaneous.
+ */
+export function compileExactReplacements(
+    sourceText,
+    replacements,
+    field = 'replacements',
+    options = {}
+) {
+    const invalidCode = options.invalidCode || 'INVALID_OPERATION';
+    if (typeof sourceText !== 'string') {
+        return {
+            ok: false,
+            error: invalidReplacement(
+                'Localized replacements require string source text.',
+                field,
+                invalidCode
+            )
+        };
+    }
+    const validation = validateExactReplacementRequests(replacements, field, { invalidCode });
+    if (!validation.ok) return validation;
+
+    const resolved = [];
+    for (let index = 0; index < validation.replacements.length; index += 1) {
+        const replacement = validation.replacements[index];
+        const itemField = `${field}[${index}]`;
+        const occurrence = replacement.occurrence ?? null;
+        const offsets = occurrenceOffsets(sourceText, replacement.find);
+        if (offsets.length === 0 || (occurrence != null && occurrence > offsets.length)) {
+            return {
+                ok: false,
+                error: patchError(
+                    'PATCH_SOURCE_NOT_FOUND',
+                    occurrence == null
+                        ? `Exact patch source was not found: "${replacement.find}".`
+                        : `Occurrence ${occurrence} of exact patch source was not found: "${replacement.find}".`,
+                    itemField,
+                    'change_patch',
+                    { matchCount: offsets.length }
+                )
+            };
+        }
+        if (occurrence == null && offsets.length > 1) {
+            return {
+                ok: false,
+                error: patchError(
+                    'AMBIGUOUS_PATCH_SOURCE',
+                    `Exact patch source matched ${offsets.length} locations; provide occurrence.`,
+                    itemField,
+                    'choose_occurrence',
+                    { candidates: offsets.map(start => offsetCandidate(sourceText, start, replacement.find.length)) }
+                )
+            };
+        }
+
+        const start = offsets[(occurrence || 1) - 1];
+        resolved.push({
+            requestIndex: index,
+            start,
+            end: start + replacement.find.length,
+            find: replacement.find,
+            replace: replacement.replace,
+            occurrence: occurrence || 1
+        });
+    }
+
+    resolved.sort((left, right) => left.start - right.start || left.end - right.end || left.requestIndex - right.requestIndex);
+    const unique = [];
+    for (const replacement of resolved) {
+        const previous = unique.at(-1);
+        if (previous && replacement.start === previous.start && replacement.end === previous.end) {
+            if (replacement.replace !== previous.replace) {
+                return {
+                    ok: false,
+                    error: patchError(
+                        'CONFLICTING_PATCHES',
+                        `Localized replacements ${previous.requestIndex + 1} and ${replacement.requestIndex + 1} assign different text to the same source range.`,
+                        field,
+                        'combine_patches',
+                        { replacementIndexes: [previous.requestIndex + 1, replacement.requestIndex + 1] }
+                    )
+                };
+            }
+            continue;
+        }
+        if (previous && replacement.start < previous.end) {
+            return {
+                ok: false,
+                error: patchError(
+                    'OVERLAPPING_PATCHES',
+                    `Localized replacements ${previous.requestIndex + 1} and ${replacement.requestIndex + 1} overlap.`,
+                    field,
+                    'combine_patches',
+                    { replacementIndexes: [previous.requestIndex + 1, replacement.requestIndex + 1] }
+                )
+            };
+        }
+        unique.push(replacement);
+    }
+
+    let cursor = 0;
+    let desiredText = '';
+    for (const replacement of unique) {
+        desiredText += sourceText.slice(cursor, replacement.start);
+        desiredText += replacement.replace;
+        cursor = replacement.end;
+    }
+    desiredText += sourceText.slice(cursor);
+
+    return {
+        ok: true,
+        desiredText,
+        replacements: unique.map(replacement => ({
+            requestIndex: replacement.requestIndex + 1,
+            start: replacement.start,
+            end: replacement.end,
+            find: replacement.find,
+            replace: replacement.replace,
+            occurrence: replacement.occurrence,
+            removedLength: replacement.end - replacement.start,
+            insertedLength: replacement.replace.length
+        }))
+    };
+}
+
+/** Build a compact receipt-like summary from actual source and output text. */
+export function buildLocalizedReplacementChange(compilation, outputText, target = {}, context = null) {
+    if (!compilation || typeof compilation !== 'object') return null;
+    const sourceText = String(compilation.sourceText ?? '');
+    const desiredText = String(compilation.desiredText ?? '');
+    const replacements = Array.isArray(compilation.replacements) ? compilation.replacements : [];
+    let delta = 0;
+    const applied = replacements.map(replacement => {
+        const afterStart = replacement.start + delta;
+        const afterEnd = afterStart + replacement.replace.length;
+        delta += replacement.replace.length - (replacement.end - replacement.start);
+        return {
+            find: replacement.find,
+            replace: replacement.replace,
+            occurrence: replacement.occurrence,
+            beforeExcerpt: boundedExcerpt(sourceText, replacement.start, replacement.end),
+            afterExcerpt: boundedExcerpt(desiredText, afterStart, afterEnd)
+        };
+    });
+    return {
+        kind: 'localized_replacement',
+        committed: true,
+        finalDisposition: 'applied',
+        target: {
+            ...(target.paragraphId ? { paragraphId: target.paragraphId } : {}),
+            ...(Number.isInteger(target.index) ? { index: target.index } : {}),
+            ...(target.fingerprint ? { fingerprint: target.fingerprint } : {}),
+            ...(context?.humanReference ? { humanReference: context.humanReference } : {})
+        },
+        ...(context ? { context: { ...context } } : {}),
+        replacements: applied,
+        verification: {
+            acceptedViewMatchesCompiledText: typeof outputText === 'string' && outputText === desiredText
+        }
+    };
+}

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,30 @@ 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
+                        );
+                    }
+                }
+
                 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,6 +57,24 @@ export interface RedlineDocumentOperation extends DocumentOperationBase {
   anchor?: RejectedTextInsertionAnchor;
 }
 
+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;
+    });
+
 export interface RestoreDocumentOperation extends DocumentOperationBase {
   type: 'restore';
   modified: string | string[];
@@ -190,6 +212,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 +257,7 @@ export interface DocumentOperationResult {
   resolvedTarget?: ResolvedDocumentTarget;
   resolvedAnchor?: ResolvedCommentAnchor;
   receipt?: MutationReceipt;
+  change?: LocalizedReplacementChange;
 }
 
 export interface BatchOperationItemResult {
@@ -221,6 +272,7 @@ export interface BatchOperationItemResult {
   warnings?: string[];
   error?: RedlineError;
   receipt?: MutationReceipt;
+  change?: LocalizedReplacementChange;
 }
 
 export interface DocumentOperationBatchResult {