@ansonlai/docx-redline-js 0.8.4 → 0.9.0

package/services/document-operation-applier.js

@@ -1,6 +1,7 @@
 import { getDefaultAuthor } from '../adapters/config.js';
 import {
     normalizeDocumentOperation,
+    normalizeTargetDescriptor,
     resolveDocumentOperationAuthor,
     validateDocumentOperation
 } from './document-operation-contract.js';
@@ -16,8 +17,10 @@ import {
     applyFormattingToParagraphByExactText,
     applyHighlightToParagraphByExactText,
     applyParagraphFormatToParagraphByExactText,
+    applyListFormatToParagraphByExactText,
     insertIntoRejectedDeletedText,
     restoreDeletedParagraphByExactText,
+    resolveOperationSourceRange,
     applyToParagraphByExactText
 } from './document-operation-mutations.js';
 import { applyCommentReplyToParts } from './comment-replies.js';
@@ -35,6 +38,18 @@ import { subtractValidationIssueMultiset, validationErrors } from '../core/valid
 import { normalizeErrorWithRecovery } from './error-recovery.js';
 import { extractCanonicalParagraphText } from '../core/paragraph-text.js';
 import { buildLocalizedReplacementChange } from './localized-replacement-compiler.js';
+import {
+    buildRevisionFidelityError,
+    createFidelityViews,
+    resolveRevisionFidelityMode,
+    revisionFidelityBaselineView,
+    isPlainTextIntent,
+    verifyAcceptIntent,
+    verifyNumberingReferences,
+    verifyRevisionFidelity,
+    verifyNoCreatedRevisions,
+    verifyUntrackedLocality
+} from './revision-fidelity-verifier.js';
 
 export function normalizeOperationError(error, context = {}) {
     return normalizeErrorWithRecovery(error, context);
@@ -199,9 +214,36 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
         operation = compiledValidation.operation;
     }
 
+    if (Array.isArray(operation.replacements) && !operation._localizedReplacementCompilation) {
+        // Uncompiled replacements would otherwise reach the mutation with no "modified" text and
+        // delete the paragraph; never apply them without their compiled accepted-text intent.
+        return {
+            documentXml,
+            hasChanges: false,
+            status: 'error',
+            error: normalizeOperationError({
+                code: 'PATCH_ROUNDTRIP_MISMATCH',
+                stage: 'validation',
+                message: 'Localized replacements were not compiled against a batch-start paragraph target, so they were refused instead of applied.'
+            }, errorContext),
+            operationType: operation.operationKind,
+            authorUsed,
+            receipt: createEmptyReceipt(operationIndex, operation.operationId, authorUsed, 'refused')
+        };
+    }
+
     const resolutionCapture = {};
     let localizedChange = null;
     const savepoint = session.createSavepoint();
+    // The previous verified operation's Reject All projection is this operation's baseline
+    // while the live DOM is the one it was computed on (a restored savepoint swaps the DOM).
+    // The memo is consumed here: any path that does not store a fresh one (an unverified commit, an
+    // early return) leaves it empty, so a stale entry can never describe a mutated DOM. The before-state
+    // entry is re-keyed to the savepoint clone, which is the live DOM again after a refusal restores it.
+    const priorViews = session._fidelityViews?.document === session.document ? session._fidelityViews : null;
+    session._fidelityViews = null;
+    const beforeViews = { ...(priorViews || createFidelityViews(null)), document: savepoint.document };
+    const afterViews = createFidelityViews(session.document);
     session.receiptCollector?.beginOperation(
         operationIndex,
         operation.operationId,
@@ -219,12 +261,19 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
         ...(operation._localizedReplacementCompilation && operation.structuredContent !== true ? { literalTextEdit: true } : {}),
         pairReplacements: typeof operation.pairReplacements === 'boolean' ? operation.pairReplacements : (options.pairReplacements !== false),
         ...(operation.insertionAffinity ? { insertionAffinity: operation.insertionAffinity } : {}),
+        ...(operation.listMarkers ? { listMarkers: operation.listMarkers } : {}),
         ...(operation.formattingRevisionPolicy ? { formattingRevisionPolicy: operation.formattingRevisionPolicy } : {}),
         ...(operation.operationKind === 'format' && Number.isInteger(operation.textOccurrence) ? { textOccurrence: operation.textOccurrence } : {}),
         targetDescriptor: operation.targetDescriptor,
         targetEndDescriptor: operation.targetEndDescriptor,
         _compiledSourceId: operation._compiledSourceId || null,
         _compiledSourceEndId: operation._compiledSourceEndId || null,
+        ...(operation.operationKind === 'list-format' && operation.list?.continueFrom && typeof operation.list.continueFrom === 'object'
+            ? {
+                continueFromDescriptor: normalizeTargetDescriptor(operation.list.continueFrom, null, 'accepted'),
+                _compiledContinueFromId: operation._compiledContinueFromId || null
+            }
+            : {}),
         _compiledResolvedBy: operation._compiledResolvedBy || null,
         _sourceTargetRegistry: session.sourceTargetRegistry || null,
         _resolutionCapture: resolutionCapture,
@@ -241,6 +290,23 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
         }
     };
 
+    // Resolve the target range before mutating, for the revision fidelity verifier: the exact accepted scope of an
+    // accept-first range target, and the target of a plain-text redline's ACCEPT_INTENT check.
+    const isRangeTarget = !!(operation.targetEndDescriptor || operation.targetEndRef);
+    const earlyFidelityMode = resolveRevisionFidelityMode(options.verifyRevisionFidelity);
+    const acceptFirstBaseline = revisionFidelityBaselineView(operationOptions.existingRevisions) === 'accepted';
+    const declaresAcceptIntent = operation.operationKind === 'redline'
+        && operationOptions.generateRedlines !== false
+        && !operation._localizedReplacementCompilation
+        && operation.structuredContent !== true
+        && isPlainTextIntent(operation.modified)
+        && !/\r?\n/.test(String(operation.targetDescriptor?.exactText ?? operation.targetDescriptor?.text ?? (typeof operation.target === 'string' ? operation.target : '')));
+    const sourceRange = earlyFidelityMode !== 'off' && session.document
+        && ((isRangeTarget && acceptFirstBaseline) || declaresAcceptIntent)
+        ? resolveOperationSourceRange(session.document, operation.target, operation.targetRef, operation.targetEndRef, runtimeContext, operationOptions)
+        : null;
+    const rangeEndIndex = sourceRange ? sourceRange.to : null;
+
     try {
         let result;
         if (operation.operationKind === 'comment_reply') {
@@ -335,6 +401,17 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
                 runtimeContext,
                 operationOptions
             );
+        } else if (operation.operationKind === 'list-format') {
+            result = await applyListFormatToParagraphByExactText(
+                documentXml,
+                operation.target,
+                operation.list,
+                authorUsed,
+                operation.targetRef,
+                operation.targetEndRef,
+                runtimeContext,
+                operationOptions
+            );
         } else if (operation.operationKind === 'rejected-insert') {
             result = await insertIntoRejectedDeletedText(
                 documentXml,
@@ -437,6 +514,142 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
                     ...resolutionCapture
                 };
             }
+            if (operation._localizedReplacementCompilation && operation.structuredContent !== true) {
+                // Accept-view intent: the target's accepted text must be exactly the compiled
+                // text, whatever path produced it. A tracked whole-paragraph deletion rejects
+                // back to the source, so the Reject All verifier alone cannot see it. Structured (Markdown)
+                // replacement text legitimately differs from its literal accepted text, so it is exempt.
+                let intentText = null;
+                if (operation.operationKind === 'restore') {
+                    const restored = operationOptions._mutationLiveNodes.find(node => node?.localName === 'p');
+                    if (restored) intentText = extractCanonicalParagraphText(restored, { revisionView: 'accepted' });
+                } else if (operation._compiledSourceId && session.sourceTargetRegistry) {
+                    const live = session.sourceTargetRegistry.previewSuccessor(
+                        operation._compiledSourceId,
+                        operationOptions._mutationRemovedNodes,
+                        operationOptions._mutationLiveNodes
+                    );
+                    if (live) intentText = extractCanonicalParagraphText(live, { revisionView: 'accepted' });
+                }
+                if (intentText !== operation._localizedReplacementCompilation.desiredText) {
+                    session.restoreSavepoint(savepoint);
+                    const message = 'The localized replacement did not produce the compiled accepted text, so it was refused before commit to avoid losing content. Re-extract the paragraph and retry with its current text.';
+                    const refusedReceipt = createEmptyReceipt(operationIndex, operation.operationId, authorUsed, 'refused');
+                    refusedReceipt.warnings.push(message);
+                    return {
+                        documentXml,
+                        hasChanges: false,
+                        status: 'error',
+                        error: normalizeOperationError({ code: 'PATCH_ROUNDTRIP_MISMATCH', stage: 'validation', message }, errorContext),
+                        warnings: [message],
+                        operationType: operation.operationKind,
+                        authorUsed,
+                        receipt: refusedReceipt,
+                        ...resolutionCapture
+                    };
+                }
+            }
+            const fidelityMode = resolveRevisionFidelityMode(options.verifyRevisionFidelity);
+            const singleTargetPosition = !operation.targetEndDescriptor && !operation.targetEndRef
+                ? resolutionCapture.resolvedTarget?.index
+                : null;
+            const fidelity = fidelityMode === 'off' ? null
+                : (operationOptions.generateRedlines !== false ? 'tracked' : (Number.isInteger(singleTargetPosition) ? 'untracked' : null));
+            if (fidelity === 'tracked') {
+                const baselineView = revisionFidelityBaselineView(operationOptions.existingRevisions);
+                // Accept-first policies accept revisions in the resolved target only. A range target uses the
+                // end resolved before mutation; if that could not be resolved the verifier falls back to its
+                // weaker region heuristic.
+                const targetPosition = resolutionCapture.resolvedTarget?.index;
+                const acceptedScope = !Number.isInteger(targetPosition) ? null
+                    : !isRangeTarget ? { from: targetPosition - 1, to: targetPosition - 1 }
+                    : (Number.isInteger(rangeEndIndex) && rangeEndIndex >= targetPosition - 1
+                        ? { from: targetPosition - 1, to: rangeEndIndex }
+                        : null);
+                const fidelity = verifyRevisionFidelity({
+                    before: savepoint.document,
+                    after: session.document,
+                    baselineView,
+                    acceptedScope,
+                    beforeViews,
+                    afterViews
+                });
+                const numbering = verifyNumberingReferences({
+                    before: savepoint.document,
+                    after: session.document,
+                    numberingXmls: [runtimeContext?.numberingXml || options.numberingXml, ...(session.numberingXmlParts || []), result.numberingXml],
+                    beforeViews,
+                    afterViews
+                });
+                if (!numbering.ok) {
+                    fidelity.ok = false;
+                    fidelity.violations = [...(fidelity.violations || []), ...numbering.violations];
+                }
+                if (declaresAcceptIntent && sourceRange) {
+                    const intent = verifyAcceptIntent({ before: savepoint.document, after: session.document, range: sourceRange, modified: operation.modified, beforeViews, afterViews });
+                    if (!intent.ok) {
+                        fidelity.ok = false;
+                        fidelity.violations = [...(fidelity.violations || []), ...intent.violations];
+                    }
+                }
+                if (!fidelity.ok) {
+                    const fidelityError = buildRevisionFidelityError(fidelity.violations, { mode: fidelityMode, baselineView });
+                    const logLine = `${fidelityError.code} (operation ${operationIndex}${operation.operationId ? ` "${operation.operationId}"` : ''}): ${fidelityError.message}`;
+                    if (typeof options?.onWarn === 'function') options.onWarn(logLine);
+                    if (fidelityMode === 'enforce') {
+                        session.restoreSavepoint(savepoint);
+                        session._fidelityViews = beforeViews;
+                        const refusedReceipt = createEmptyReceipt(operationIndex, operation.operationId, authorUsed, 'refused');
+                        refusedReceipt.warnings.push(logLine);
+                        return {
+                            documentXml,
+                            hasChanges: false,
+                            status: 'error',
+                            error: normalizeOperationError(fidelityError, errorContext),
+                            warnings: [logLine],
+                            operationType: operation.operationKind,
+                            authorUsed,
+                            receipt: refusedReceipt,
+                            ...resolutionCapture
+                        };
+                    }
+                    result.warnings = [...(Array.isArray(result.warnings) ? result.warnings : []), logLine];
+                    result.revisionFidelityViolations = fidelity.violations;
+                }
+            } else {
+                let locality = fidelity === 'untracked'
+                    ? verifyUntrackedLocality({ before: savepoint.document, after: session.document, targetSourceIndex: singleTargetPosition - 1, beforeViews, afterViews })
+                    : { ok: true };
+                if (locality.ok && fidelityMode !== 'off' && operationOptions.generateRedlines === false) {
+                    locality = verifyNoCreatedRevisions({ before: savepoint.document, after: session.document, beforeViews, afterViews });
+                }
+                if (!locality.ok) {
+                    const fidelityError = buildRevisionFidelityError(locality.violations, { mode: fidelityMode });
+                    const logLine = `${fidelityError.code} (operation ${operationIndex}${operation.operationId ? ` "${operation.operationId}"` : ''}): ${fidelityError.message}`;
+                    if (typeof options?.onWarn === 'function') options.onWarn(logLine);
+                    if (fidelityMode === 'enforce') {
+                        session.restoreSavepoint(savepoint);
+                        session._fidelityViews = beforeViews;
+                        const refusedReceipt = createEmptyReceipt(operationIndex, operation.operationId, authorUsed, 'refused');
+                        refusedReceipt.warnings.push(logLine);
+                        return {
+                            documentXml,
+                            hasChanges: false,
+                            status: 'error',
+                            error: normalizeOperationError(fidelityError, errorContext),
+                            warnings: [logLine],
+                            operationType: operation.operationKind,
+                            authorUsed,
+                            receipt: refusedReceipt,
+                            ...resolutionCapture
+                        };
+                    }
+                    result.warnings = [...(Array.isArray(result.warnings) ? result.warnings : []), logLine];
+                    result.revisionFidelityViolations = locality.violations;
+                }
+            }
+            // Both verified branches leave the after-state's projections as the next operation's baseline.
+            if (fidelity === 'tracked' || fidelity === 'untracked') session._fidelityViews = afterViews;
             session.markMutationCommitted(true);
             if (operation._compiledSourceId && session.sourceTargetRegistry) {
                 session.sourceTargetRegistry.commitMutation(

package/services/document-operation-contract.js

@@ -6,6 +6,8 @@
  */
 
 import { validateExactReplacementRequests } from './localized-replacement-compiler.js';
+import { validateParagraphNumberingShape, findUnknownParagraphFormatKeys, PARAGRAPH_FORMAT_PROPERTY_KEYS } from './list-conversion-diagnostics.js';
+import { validateListFormatShape } from './list-format.js';
 
 const SUPPORTED_OPERATION_TYPES = new Set([
     'redline',
@@ -13,6 +15,7 @@ const SUPPORTED_OPERATION_TYPES = new Set([
     'format',
     'character-format',
     'paragraph-format',
+    'list-format',
     'list-change',
     'table-reconciliation',
     'insert',
@@ -55,6 +58,7 @@ export function getCanonicalOperationType(operation) {
     if (type === 'restore') return 'restore';
     if (type === 'comment' || type === 'comment_reply' || type === 'comment_resolve' || type === 'highlight') return type;
     if (type === 'paragraph-format') return 'paragraph-format';
+    if (type === 'list-format') return 'list-format';
     if (type === 'character-format' || (type === 'format' && (operation?.textToFormat != null || operation?.properties != null))) return 'format';
     return 'redline';
 }
@@ -408,6 +412,13 @@ export function validateDocumentOperation(operation) {
         };
     }
 
+    if (normalized.listMarkers != null && normalized.listMarkers !== 'literal') {
+        return {
+            valid: false,
+            error: { code: 'INVALID_OPERATION', message: 'listMarkers must be "literal" when provided.' }
+        };
+    }
+
     if (normalized.existingRevisions != null && !isExistingRevisionsPolicy(normalized.existingRevisions)) {
         return {
             valid: false,
@@ -534,6 +545,70 @@ export function validateDocumentOperation(operation) {
                 error: { code: 'INVALID_OPERATION', message: 'Paragraph-format operations require a "properties" object.' }
             };
         }
+        const unknownKeys = findUnknownParagraphFormatKeys(normalized.properties);
+        if (unknownKeys.length > 0) {
+            return {
+                valid: false,
+                error: {
+                    code: 'INVALID_OPERATION',
+                    message: `paragraph-format does not support ${unknownKeys.length === 1 ? 'property' : 'properties'} ${unknownKeys.map(key => `"${key}"`).join(', ')}. Supported: ${PARAGRAPH_FORMAT_PROPERTY_KEYS.join(', ')}.`,
+                    field: `properties.${unknownKeys[0]}`,
+                    properties: unknownKeys,
+                    recovery: { action: 'change_request', hint: `Use only: ${PARAGRAPH_FORMAT_PROPERTY_KEYS.join(', ')}.` }
+                }
+            };
+        }
+        if (normalized.properties.numbering !== undefined) {
+            const shapeError = validateParagraphNumberingShape(normalized.properties.numbering);
+            if (shapeError) {
+                return {
+                    valid: false,
+                    error: {
+                        code: 'INVALID_OPERATION',
+                        message: shapeError,
+                        field: 'properties.numbering',
+                        recovery: { action: 'change_request', hint: 'Pass numbering as { "numId": <existing numId from inspect>, "level": 0 } or null.' }
+                    }
+                };
+            }
+        }
+    }
+
+    if (normalized.operationKind === 'list-format') {
+        const shapeError = validateListFormatShape(normalized.list);
+        if (shapeError) {
+            return {
+                valid: false,
+                error: {
+                    code: 'INVALID_OPERATION',
+                    message: shapeError.message,
+                    field: shapeError.field,
+                    recovery: {
+                        action: 'change_request',
+                        hint: 'Pass list as { "mode": "convert-plain" } (optional format, kind, level, strip "marker" | "none", start with strip "none"), { "mode": "change-format", "format": ... } (optional kind, lvlText, start, level, scope "list" | "range") or { "mode": "join", "continueFrom": { "paragraphId": ... } } (optional scope).'
+                    }
+                }
+            };
+        }
+        if (operation.modified !== undefined || operation.replacements !== undefined) {
+            return {
+                valid: false,
+                error: {
+                    code: 'INVALID_OPERATION',
+                    message: 'list-format changes list structure only; express text changes as a separate redline operation.',
+                    field: operation.modified !== undefined ? 'modified' : 'replacements'
+                }
+            };
+        }
+        if (target.captureRef || target.occurrence != null || target.revisionView !== 'accepted') {
+            return {
+                valid: false,
+                error: {
+                    code: 'INVALID_OPERATION',
+                    message: 'list-format v1 targets batch-start accepted-view paragraphs without captures or target occurrence.'
+                }
+            };
+        }
     }
 
     if (normalized.author != null && !nonEmptyString(normalized.author)) {