@ansonlai/docx-redline-js 0.4.0 → 0.5.0

package/services/document-operation-session.js

@@ -0,0 +1,258 @@
+import { createSerializer, parseOoxmlSafe } from '../adapters/xml-adapter.js';
+import {
+    RevisionIdAllocator,
+    seedRevisionIdsFromDocument,
+    setRevisionIdAllocatorForDocument
+} from '../core/types.js';
+import {
+    buildParagraphMetadataIndex,
+    buildTargetReferenceSnapshot
+} from '../core/paragraph-targeting.js';
+import { ReceiptCollector } from './receipt-collector.js';
+
+/**
+ * Owns the document state used by one standalone operation or batch.
+ *
+ * The session keeps accuracy-sensitive mutation decisions unchanged while a
+ * batch shares one live DOM. Savepoints protect against partial failed/no-op
+ * mutations, and the original input string remains the rollback authority.
+ */
+export class DocumentOperationSession {
+    constructor(documentXml, options = {}) {
+        this.originalDocumentXml = typeof documentXml === 'string' ? documentXml : '';
+        this.currentDocumentXml = this.originalDocumentXml;
+        this.serializer = createSerializer();
+        this.parseResult = parseOoxmlSafe(this.originalDocumentXml, 'application/xml');
+        this.document = this.parseResult.doc || null;
+        this.revisionIdAllocator = null;
+        this.initialTargetReferenceSnapshot = null;
+        this.paragraphIndex = null;
+        this.invalidated = false;
+        this.hasChanges = false;
+        this.documentHasChanges = false;
+        this.deferSerialization = options?._deferDocumentSerialization === true;
+        this.instrumentation = options?._sessionInstrumentation || null;
+        this.runtimeContext = null;
+        this.commentsXml = null;
+        this.commentsExtendedXml = null;
+        this.commentsXmlMode = 'merge';
+        this.commentsExtendedXmlMode = 'merge';
+        this.numberingXmlParts = [];
+        this.results = [];
+        this.executionOrder = [];
+        this.authorsUsed = new Set();
+        this.captureTable = new Map();
+        this.nextCaptureParaId = 1;
+        this.receiptCollector = new ReceiptCollector();
+
+        if (this.document) {
+            this.instrumentation?.onDocumentParse?.(this.originalDocumentXml);
+            this.revisionIdAllocator = options?._revisionIdAllocator instanceof RevisionIdAllocator
+                ? options._revisionIdAllocator
+                : new RevisionIdAllocator();
+            this.revisionIdAllocator._receiptCollector = this.receiptCollector;
+            seedRevisionIdsFromDocument(this.document, this.revisionIdAllocator);
+            setRevisionIdAllocatorForDocument(this.document, this.revisionIdAllocator);
+            const paragraphIndex = this.getParagraphMetadataIndex();
+            this.initialTargetReferenceSnapshot = buildTargetReferenceSnapshot(this.document, paragraphIndex);
+        }
+    }
+
+    get valid() {
+        return !!this.document && !this.parseResult.error;
+    }
+
+    setDocumentXml(documentXml) {
+        this.currentDocumentXml = documentXml;
+        this.invalidateParagraphIndex();
+    }
+
+    invalidateParagraphIndex() {
+        this.invalidated = true;
+        this.paragraphIndex = null;
+    }
+
+    serialize() {
+        if (!this.document) return this.currentDocumentXml;
+        this.instrumentation?.onDocumentSerialize?.(this.document);
+        return this.serializer.serializeToString(this.document);
+    }
+
+    serializeCurrent() {
+        if (!this.hasChanges) return this.originalDocumentXml;
+        if (!this.documentHasChanges) return this.currentDocumentXml;
+        this.currentDocumentXml = this.serialize();
+        return this.currentDocumentXml;
+    }
+
+    markMutationCommitted(documentChanged = true) {
+        this.hasChanges = true;
+        this.documentHasChanges = this.documentHasChanges || documentChanged;
+        if (documentChanged) this.invalidateParagraphIndex();
+    }
+
+    generateParagraphId() {
+        return (0x40000000 + (this.nextCaptureParaId++)).toString(16).toUpperCase();
+    }
+
+    createSavepoint() {
+        if (!this.document) return null;
+        return {
+            document: this.document.cloneNode(true),
+            allocatorNextId: this.revisionIdAllocator?.nextId,
+            allocatorOccupiedIds: this.revisionIdAllocator?.occupiedIds instanceof Set
+                ? new Set(this.revisionIdAllocator.occupiedIds)
+                : null,
+            hasChanges: this.hasChanges,
+            documentHasChanges: this.documentHasChanges,
+            currentDocumentXml: this.currentDocumentXml,
+            commentsXml: this.commentsXml,
+            commentsExtendedXml: this.commentsExtendedXml,
+            commentsXmlMode: this.commentsXmlMode,
+            commentsExtendedXmlMode: this.commentsExtendedXmlMode,
+            captureTable: cloneCaptureTable(this.captureTable),
+            nextCaptureParaId: this.nextCaptureParaId,
+            receiptCollector: this.receiptCollector ? this.receiptCollector.createSavepoint() : null
+        };
+    }
+
+    restoreSavepoint(savepoint) {
+        if (!savepoint?.document) return;
+        this.document = savepoint.document;
+        this.hasChanges = savepoint.hasChanges;
+        this.documentHasChanges = savepoint.documentHasChanges === true;
+        this.currentDocumentXml = savepoint.currentDocumentXml;
+        this.commentsXml = savepoint.commentsXml;
+        this.commentsExtendedXml = savepoint.commentsExtendedXml;
+        this.commentsXmlMode = savepoint.commentsXmlMode || 'merge';
+        this.commentsExtendedXmlMode = savepoint.commentsExtendedXmlMode || 'merge';
+        this.captureTable = savepoint.captureTable ? cloneCaptureTable(savepoint.captureTable) : new Map();
+        if (typeof savepoint.nextCaptureParaId === 'number') {
+            this.nextCaptureParaId = savepoint.nextCaptureParaId;
+        }
+        if (this.revisionIdAllocator) {
+            this.revisionIdAllocator.nextId = savepoint.allocatorNextId;
+            if (savepoint.allocatorOccupiedIds instanceof Set) {
+                this.revisionIdAllocator.occupiedIds = new Set(savepoint.allocatorOccupiedIds);
+            }
+            this.revisionIdAllocator._receiptCollector = this.receiptCollector;
+            setRevisionIdAllocatorForDocument(this.document, this.revisionIdAllocator);
+        }
+        if (savepoint.receiptCollector && this.receiptCollector) {
+            this.receiptCollector.restoreSavepoint(savepoint.receiptCollector);
+        }
+        this.invalidateParagraphIndex();
+    }
+
+    getParagraphIndex() {
+        return this.getParagraphMetadataIndex().entries;
+    }
+
+    getParagraphMetadataIndex() {
+        if (this.paragraphIndex) return this.paragraphIndex;
+        this.paragraphIndex = buildParagraphMetadataIndex(this.document);
+        this.invalidated = false;
+        return this.paragraphIndex;
+    }
+
+    rollback() {
+        this.currentDocumentXml = this.originalDocumentXml;
+        this.hasChanges = false;
+        this.documentHasChanges = false;
+        this.captureTable.clear();
+        this.receiptCollector?.clear();
+        return this.originalDocumentXml;
+    }
+}
+
+function cloneCaptureTable(table) {
+    const cloned = new Map();
+    if (table instanceof Map) {
+        for (const [k, v] of table.entries()) {
+            cloned.set(k, JSON.parse(JSON.stringify(v)));
+        }
+    }
+    return cloned;
+}
+
+export function prepareRevisionAllocator(xmlDoc, options = {}) {
+    const allocator = options?._revisionIdAllocator instanceof RevisionIdAllocator
+        ? options._revisionIdAllocator
+        : new RevisionIdAllocator();
+    if (options?._documentOperationSession?.receiptCollector) {
+        allocator._receiptCollector = options._documentOperationSession.receiptCollector;
+    }
+    seedRevisionIdsFromDocument(xmlDoc, allocator);
+    setRevisionIdAllocatorForDocument(xmlDoc, allocator);
+    return allocator;
+}
+
+export function cloneBatchRuntimeContext(runtimeContext) {
+    if (!runtimeContext || typeof runtimeContext !== 'object') return {};
+
+    const context = { ...runtimeContext };
+    if (runtimeContext.listFallbackSharedNumIdByKey instanceof Map) {
+        context.listFallbackSharedNumIdByKey = new Map(runtimeContext.listFallbackSharedNumIdByKey);
+    }
+    if (runtimeContext.tableStructuralRedlineKeys instanceof Set) {
+        context.tableStructuralRedlineKeys = new Set(runtimeContext.tableStructuralRedlineKeys);
+    }
+    if (runtimeContext.numberingIdState && typeof runtimeContext.numberingIdState === 'object') {
+        context.numberingIdState = {
+            ...runtimeContext.numberingIdState,
+            usedNumIds: runtimeContext.numberingIdState.usedNumIds instanceof Set
+                ? new Set(runtimeContext.numberingIdState.usedNumIds)
+                : runtimeContext.numberingIdState.usedNumIds,
+            usedAbstractNumIds: runtimeContext.numberingIdState.usedAbstractNumIds instanceof Set
+                ? new Set(runtimeContext.numberingIdState.usedAbstractNumIds)
+                : runtimeContext.numberingIdState.usedAbstractNumIds
+        };
+    }
+    if (runtimeContext.listFallbackSequenceState && typeof runtimeContext.listFallbackSequenceState === 'object') {
+        context.listFallbackSequenceState = {
+            ...runtimeContext.listFallbackSequenceState,
+            explicitByNumberingKey: runtimeContext.listFallbackSequenceState.explicitByNumberingKey instanceof Map
+                ? new Map(runtimeContext.listFallbackSequenceState.explicitByNumberingKey)
+                : runtimeContext.listFallbackSequenceState.explicitByNumberingKey
+        };
+    }
+    return context;
+}
+
+export function commitBatchRuntimeContext(runtimeContext, context) {
+    if (!runtimeContext || typeof runtimeContext !== 'object') return;
+
+    if (runtimeContext.listFallbackSharedNumIdByKey instanceof Map && context.listFallbackSharedNumIdByKey instanceof Map) {
+        runtimeContext.listFallbackSharedNumIdByKey.clear();
+        for (const entry of context.listFallbackSharedNumIdByKey) runtimeContext.listFallbackSharedNumIdByKey.set(...entry);
+        context.listFallbackSharedNumIdByKey = runtimeContext.listFallbackSharedNumIdByKey;
+    }
+    if (runtimeContext.tableStructuralRedlineKeys instanceof Set && context.tableStructuralRedlineKeys instanceof Set) {
+        runtimeContext.tableStructuralRedlineKeys.clear();
+        for (const value of context.tableStructuralRedlineKeys) runtimeContext.tableStructuralRedlineKeys.add(value);
+        context.tableStructuralRedlineKeys = runtimeContext.tableStructuralRedlineKeys;
+    }
+    if (runtimeContext.numberingIdState && context.numberingIdState) {
+        for (const key of ['usedNumIds', 'usedAbstractNumIds']) {
+            if (runtimeContext.numberingIdState[key] instanceof Set && context.numberingIdState[key] instanceof Set) {
+                runtimeContext.numberingIdState[key].clear();
+                for (const value of context.numberingIdState[key]) runtimeContext.numberingIdState[key].add(value);
+                context.numberingIdState[key] = runtimeContext.numberingIdState[key];
+            }
+        }
+        Object.assign(runtimeContext.numberingIdState, context.numberingIdState);
+        context.numberingIdState = runtimeContext.numberingIdState;
+    }
+    if (runtimeContext.listFallbackSequenceState && context.listFallbackSequenceState) {
+        const originalMap = runtimeContext.listFallbackSequenceState.explicitByNumberingKey;
+        const updatedMap = context.listFallbackSequenceState.explicitByNumberingKey;
+        if (originalMap instanceof Map && updatedMap instanceof Map) {
+            originalMap.clear();
+            for (const entry of updatedMap) originalMap.set(...entry);
+            context.listFallbackSequenceState.explicitByNumberingKey = originalMap;
+        }
+        Object.assign(runtimeContext.listFallbackSequenceState, context.listFallbackSequenceState);
+        context.listFallbackSequenceState = runtimeContext.listFallbackSequenceState;
+    }
+    Object.assign(runtimeContext, context);
+}

package/services/numbering-service.js

@@ -5,6 +5,11 @@
  */
 
 import { NumberFormat, NumberSuffix } from '../core/types.js';
+
+function isUsableNumId(numId) {
+    const normalized = String(numId ?? '');
+    return /^\d+$/.test(normalized) && Number.parseInt(normalized, 10) > 0;
+}
 
 export class NumberingService {
     constructor() {
@@ -19,8 +24,10 @@ export class NumberingService {
      * @param {string} signature - Format signature (e.g., 'bullet' or 'decimal')
      * @param {string} numId - Existing numId from Word
      */
-    registerExistingNumId(signature, numId) {
-        this.contextMap.set(signature, numId);
+    registerExistingNumId(signature, numId) {
+        if (isUsableNumId(numId)) {
+            this.contextMap.set(signature, String(numId));
+        }
     }
 
     /**
@@ -34,15 +41,17 @@ export class NumberingService {
         const requestedType = formatConfig.type || NumberFormat.BULLET;
 
         // Priority 1: Use existing context if it matches the requested type
-        if (existingContext && existingContext.numId) {
+        if (existingContext && isUsableNumId(existingContext.numId)) {
             if (existingContext.type === requestedType || existingContext.type === 'unknown') {
                 return existingContext.numId;
             }
         }
 
         // Priority 2: Use cached numId for this format
-        if (this.contextMap.has(requestedType)) {
-            return this.contextMap.get(requestedType);
+        if (this.contextMap.has(requestedType)) {
+            const cachedNumId = this.contextMap.get(requestedType);
+            if (isUsableNumId(cachedNumId)) return cachedNumId;
+            this.contextMap.delete(requestedType);
         }
 
         // Priority 3: Special Handling for Outline (recursive 1.1.1)

package/services/operation-heuristics.js

@@ -0,0 +1,173 @@
+import {
+    getParagraphText,
+    normalizeWhitespaceForTargeting
+} from '../core/paragraph-targeting.js';
+import {
+    getParagraphListInfo,
+    stripRedundantLeadingListMarkers
+} from '../core/list-targeting.js';
+
+const LIST_LINE_REGEX = /^(\s*)((?:\d+(?:\.\d+)*\.?|\((?:\d+|[a-zA-Z]|[ivxlcIVXLC]+)\)|[a-zA-Z]\.|[ivxlcIVXLC]+\.|[-*+\u2022]))\s+(.*)$/;
+const INLINE_LIST_MARKER_REGEX = /(?:^|\s)(?:\d+(?:\.\d+)*\.?|[A-Za-z]\.|[ivxlcIVXLC]+\.)\s+/g;
+
+function parseOutlineLevelFromMarker(marker) {
+    const normalized = String(marker || '').trim();
+    if (!/^\d+(?:\.\d+)+\.?$/.test(normalized)) return null;
+    const parts = normalized.replace(/\.$/, '').split('.');
+    return Math.max(0, parts.length - 1);
+}
+
+function parseModifiedListLines(modifiedText) {
+    const lines = String(modifiedText || '')
+        .split(/\r?\n/g)
+        .map(line => line.trimEnd())
+        .filter(line => line.trim().length > 0);
+    if (lines.length < 2) return null;
+
+    const parsed = [];
+    for (const line of lines) {
+        const markerMatch = line.match(LIST_LINE_REGEX);
+        if (!markerMatch) return null;
+        const marker = markerMatch[2];
+        const markerType = /^[-*+\u2022]$/.test(marker) ? 'bullet' : 'numbered';
+        parsed.push({
+            marker,
+            markerType,
+            level: Math.floor((markerMatch[1] || '').length / 2),
+            outlineLevel: markerType === 'numbered' ? parseOutlineLevelFromMarker(marker) : null,
+            text: stripRedundantLeadingListMarkers(markerMatch[3])
+        });
+    }
+    return parsed.length >= 2 ? parsed : null;
+}
+
+export function buildExplicitRangeInsertionEntries(explicitRangeParagraphs, modifiedText) {
+    if (!Array.isArray(explicitRangeParagraphs) || explicitRangeParagraphs.length === 0) return null;
+    const parsedLines = parseModifiedListLines(modifiedText);
+    if (!parsedLines) return null;
+
+    const originalTexts = explicitRangeParagraphs.map(paragraph =>
+        normalizeWhitespaceForTargeting(getParagraphText(paragraph))
+    );
+    const modifiedTexts = parsedLines.map(item => normalizeWhitespaceForTargeting(item.text));
+    if (originalTexts.some(text => !text) || modifiedTexts.some(text => !text)) return null;
+
+    const listInfos = explicitRangeParagraphs.map(paragraph => getParagraphListInfo(paragraph));
+    if (listInfos.some(info => !info || !info.numId)) return null;
+    const baselineNumId = String(listInfos[0].numId);
+    if (listInfos.some(info => String(info.numId) !== baselineNumId)) return null;
+
+    const matchedPairs = [];
+    let originalIndex = 0;
+    for (let modifiedIndex = 0; modifiedIndex < modifiedTexts.length && originalIndex < originalTexts.length; modifiedIndex += 1) {
+        if (modifiedTexts[modifiedIndex] === originalTexts[originalIndex]) {
+            matchedPairs.push({ originalIndex, modifiedIndex });
+            originalIndex += 1;
+        }
+    }
+    if (originalIndex !== originalTexts.length) return null;
+
+    const matchedModifiedIndexes = new Set(matchedPairs.map(pair => pair.modifiedIndex));
+    const insertedIndexes = [];
+    for (let idx = 0; idx < parsedLines.length; idx += 1) {
+        if (!matchedModifiedIndexes.has(idx)) insertedIndexes.push(idx);
+    }
+    if (insertedIndexes.length === 0) return null;
+
+    const baseIndentLevel = parsedLines[0]?.level || 0;
+    return insertedIndexes.map(modifiedIndex => {
+        const nextMatch = matchedPairs.find(pair => pair.modifiedIndex > modifiedIndex) || null;
+        const prevMatch = [...matchedPairs].reverse().find(pair => pair.modifiedIndex < modifiedIndex) || null;
+        const referenceMatch = nextMatch || prevMatch;
+        if (!referenceMatch) return null;
+        const referenceListInfo = listInfos[referenceMatch.originalIndex] || listInfos[0];
+        if (!referenceListInfo) return null;
+
+        const entry = parsedLines[modifiedIndex];
+        const relativeLevel = Math.max(0, entry.level - baseIndentLevel);
+        const explicitOutlineLevel = Number.isInteger(entry.outlineLevel) ? entry.outlineLevel : null;
+        return {
+            text: entry.text,
+            markerType: entry.markerType,
+            ilvl: explicitOutlineLevel != null
+                ? explicitOutlineLevel
+                : Math.max(0, (referenceListInfo.ilvl || 0) + relativeLevel),
+            numId: String(referenceListInfo.numId),
+            insertBeforeOriginalIndex: nextMatch ? nextMatch.originalIndex : null
+        };
+    }).filter(Boolean);
+}
+
+function countWords(text) {
+    return String(text || '').trim().split(/\s+/).filter(Boolean).length;
+}
+
+function hasMultipleInlineListMarkers(text) {
+    const source = String(text || '');
+    if (!source) return false;
+    let count = 0;
+    const regex = new RegExp(INLINE_LIST_MARKER_REGEX.source, INLINE_LIST_MARKER_REGEX.flags);
+    while (regex.exec(source)) {
+        count += 1;
+        if (count >= 2) return true;
+    }
+    return false;
+}
+
+export function deriveSingleParagraphListAdjacencyInsertion(currentParagraphText, modifiedText) {
+    const rawCurrent = String(currentParagraphText || '').trim();
+    const rawModified = String(modifiedText || '').trim();
+    if (!rawCurrent || !rawModified || rawModified === rawCurrent || rawModified.includes('\n')) return null;
+    const normalizedCurrent = normalizeWhitespaceForTargeting(rawCurrent);
+    const sanitizeCandidate = text => stripRedundantLeadingListMarkers(String(text || '').trim()).trim();
+    const buildCandidate = (position, text) => {
+        const cleanedText = sanitizeCandidate(text);
+        const cleanedNormalized = normalizeWhitespaceForTargeting(cleanedText);
+        if (!cleanedText || cleanedText === rawCurrent || countWords(cleanedText) < 6) return null;
+        if (hasMultipleInlineListMarkers(cleanedText)) return null;
+        if (normalizedCurrent && cleanedNormalized.includes(normalizedCurrent)) return null;
+        return { position, text: cleanedText };
+    };
+
+    if (rawModified.endsWith(rawCurrent)) {
+        const candidate = buildCandidate('before', rawModified.slice(0, -rawCurrent.length));
+        if (candidate) return candidate;
+    }
+    if (rawModified.startsWith(rawCurrent)) {
+        const candidate = buildCandidate('after', rawModified.slice(rawCurrent.length));
+        if (candidate) return candidate;
+    }
+
+    const normalizedModified = normalizeWhitespaceForTargeting(rawModified);
+    if (!normalizedCurrent || normalizedCurrent === normalizedModified) return null;
+    if (normalizedModified.endsWith(normalizedCurrent)) {
+        const candidate = buildCandidate('before', normalizedModified.slice(0, -normalizedCurrent.length));
+        if (candidate) return candidate;
+    }
+    if (normalizedModified.startsWith(normalizedCurrent)) {
+        const candidate = buildCandidate('after', normalizedModified.slice(normalizedCurrent.length));
+        if (candidate) return candidate;
+    }
+    return null;
+}
+
+export function deriveSingleParagraphPlainAdjacencyInsertion(currentParagraphText, modifiedText) {
+    const rawCurrent = String(currentParagraphText || '').trim();
+    const rawModified = String(modifiedText || '');
+    if (!rawCurrent || !rawModified || !rawModified.includes('\n')) return null;
+
+    const lines = rawModified.split(/\r?\n/g).map(line => String(line || '').trim()).filter(Boolean);
+    if (lines.length < 2) return null;
+    const normalize = value => normalizeWhitespaceForTargeting(String(value || ''));
+    const normalizedCurrent = normalize(rawCurrent);
+
+    if (normalize(lines[lines.length - 1]) === normalizedCurrent) {
+        const paragraphs = lines.slice(0, -1).filter(Boolean);
+        if (paragraphs.length > 0) return { position: 'before', paragraphs };
+    }
+    if (normalize(lines[0]) === normalizedCurrent) {
+        const paragraphs = lines.slice(1).filter(Boolean);
+        if (paragraphs.length > 0) return { position: 'after', paragraphs };
+    }
+    return null;
+}