@ansonlai/docx-redline-js 0.4.0 → 0.5.0

package/services/comment-locator.js

@@ -1,32 +1,152 @@
-/**
- * Comment text location and marker injection helpers.
- */
-
+/**
+ * Comment text location and marker injection helpers.
+ */
+
 import { createWordElement } from '../core/word-xml.js';
 import { getElementsByTag, getFirstElementByTag } from '../core/xml-query.js';
-
-/**
- * Builds a paragraph text index in a single pass for repeated lookups.
- *
- * @param {Element} paragraph - w:p element
- * @returns {{ fullText: string, runOffsets: Array<{run: Element, start: number, end: number}> }}
- */
-export function createParagraphTextIndex(paragraph) {
-    const runs = getElementsByTag(paragraph, 'w:r');
-    const runOffsets = [];
-    let fullText = '';
-
-    for (const run of runs) {
-        const start = fullText.length;
-        const textNodes = getElementsByTag(run, 'w:t');
-        for (const textNode of textNodes) {
-            fullText += textNode.textContent || '';
-        }
-        runOffsets.push({ run, start, end: fullText.length });
-    }
-
-    return { fullText, runOffsets };
-}
+import { refreshRunPropertyChangeIds } from '../core/revision-cloning.js';
+import { readCanonicalRunText, isNodeVisibleInRevisionView } from '../core/paragraph-text.js';
+
+/**
+ * Builds a paragraph text index in a single pass for repeated lookups.
+ *
+ * @param {Element} paragraph - w:p element
+ * @param {Object} [options={}] - Options
+ * @param {'accepted'|'rejected'} [options.revisionView='accepted'] - Revision view
+ * @returns {{ fullText: string, runOffsets: Array<{run: Element, start: number, end: number}> }}
+ */
+export function createParagraphTextIndex(paragraph, options = {}) {
+    const revisionView = options.revisionView === 'current' ? 'accepted' : (options.revisionView || 'accepted');
+    const runs = getElementsByTag(paragraph, 'w:r');
+    const runOffsets = [];
+    let fullText = '';
+
+    for (const run of runs) {
+        if (!isNodeVisibleInRevisionView(run, paragraph, revisionView)) continue;
+        const start = fullText.length;
+        const text = readCanonicalRunText(run, { revisionView, boundary: paragraph });
+        fullText += text;
+        runOffsets.push({ run, start, end: fullText.length });
+    }
+
+    return { fullText, runOffsets };
+}
+
+function candidateOffsets(haystack, needle) {
+    if (!needle) return [];
+    const candidates = [];
+    let offset = haystack.indexOf(needle);
+    while (offset !== -1) {
+        candidates.push({ start: offset, end: offset + needle.length });
+        offset = haystack.indexOf(needle, offset + 1);
+    }
+    return candidates;
+}
+
+function spaceEquivalentText(value) {
+    return String(value).replace(/[ \u00a0]/g, ' ');
+}
+
+function anchorError(code, message, candidates = []) {
+    return {
+        code,
+        message,
+        ...(candidates.length > 0 ? { candidates } : {})
+    };
+}
+
+function attachRunOffsets(paragraphIndex, candidate, resolvedBy) {
+    let startRun = null;
+    let endRun = null;
+    let startOffset = 0;
+    let endOffset = 0;
+    for (const { run, start, end } of paragraphIndex.runOffsets) {
+        if (candidate.start >= start && candidate.start < end) {
+            startRun = run;
+            startOffset = candidate.start - start;
+        }
+        if (candidate.end > start && candidate.end <= end) {
+            endRun = run;
+            endOffset = candidate.end - start;
+        }
+    }
+    if (!startRun || !endRun) return null;
+    return { found: true, resolvedBy, ...candidate, startRun, startOffset, endRun, endOffset };
+}
+
+function findAncestorTag(node, tagNames, boundary = null) {
+    let current = node?.parentNode;
+    while (current && current.nodeType === 1 && current !== boundary && (current.localName || current.nodeName.replace(/^.*:/, '')) !== 'p') {
+        const local = current.localName || current.nodeName.replace(/^.*:/, '');
+        if (tagNames.includes(local)) return { node: current, tag: local };
+        current = current.parentNode;
+    }
+    return null;
+}
+
+function validateAnchorLocation(paragraphIndex, location) {
+    if (!location || !location.found) return location;
+
+    const intersectingRuns = paragraphIndex.runOffsets
+        .filter(entry => entry.end > location.start && entry.start < location.end)
+        .map(entry => entry.run);
+
+    for (const run of intersectingRuns) {
+        if (findAncestorTag(run, ['del'])) {
+            return {
+                found: false,
+                error: anchorError('UNSAFE_REVISION_NESTING', 'Refusing to attach comment to pending deletion.', [location])
+            };
+        }
+        if (findAncestorTag(run, ['moveFrom', 'moveTo'])) {
+            return {
+                found: false,
+                error: anchorError('UNSAFE_REVISION_NESTING', 'Refusing to comment on move revision until move lifecycle is designed.', [location])
+            };
+        }
+    }
+
+    return location;
+}
+
+/**
+ * Resolves a unique comment anchor without mutating the paragraph DOM.
+ * Exact matching wins. A one-to-one ASCII-space/NBSP comparison is used only
+ * when no exact match exists, so raw offsets remain stable.
+ */
+export function resolveTextInParagraphIndex(paragraphIndex, searchText) {
+    const needle = String(searchText ?? '');
+    const exactCandidates = candidateOffsets(paragraphIndex.fullText, needle);
+    if (exactCandidates.length > 1) {
+        return {
+            found: false,
+            error: anchorError('AMBIGUOUS_ANCHOR', `Anchor text matched ${exactCandidates.length} locations in the target paragraph.`, exactCandidates)
+        };
+    }
+    if (exactCandidates.length === 1) {
+        const resolved = attachRunOffsets(paragraphIndex, exactCandidates[0], 'exact_anchor');
+        if (resolved) return validateAnchorLocation(paragraphIndex, resolved);
+    }
+
+    const normalizedNeedle = spaceEquivalentText(needle);
+    const normalizedParagraph = spaceEquivalentText(paragraphIndex.fullText);
+    const equivalentCandidates = candidateOffsets(normalizedParagraph, normalizedNeedle);
+    if (equivalentCandidates.length > 1) {
+        return {
+            found: false,
+            error: anchorError('AMBIGUOUS_ANCHOR', `Space-equivalent anchor text matched ${equivalentCandidates.length} locations in the target paragraph.`, equivalentCandidates)
+        };
+    }
+    if (equivalentCandidates.length === 1) {
+        const resolved = attachRunOffsets(paragraphIndex, equivalentCandidates[0], 'space_equivalent_anchor');
+        if (resolved) return validateAnchorLocation(paragraphIndex, resolved);
+    }
+
+    return {
+        found: false,
+        error: anchorError('ANCHOR_NOT_FOUND', `Could not find anchor text in the target paragraph: "${needle}".`)
+    };
+}
 
 /**
  * Finds text within a prebuilt paragraph text index.
@@ -35,42 +155,18 @@ export function createParagraphTextIndex(paragraph) {
  * @param {string} searchText - Text to locate
  * @returns {{ found: boolean, startRun?: Element, startOffset?: number, endRun?: Element, endOffset?: number }}
  */
-export function findTextInParagraphIndex(paragraphIndex, searchText) {
-    const searchIndex = paragraphIndex.fullText.indexOf(searchText);
-    if (searchIndex === -1) {
-        return { found: false };
-    }
-
-    const searchEnd = searchIndex + searchText.length;
-    let startRun = null;
-    let endRun = null;
-    let startOffset = 0;
-    let endOffset = 0;
-
-    for (const { run, start, end } of paragraphIndex.runOffsets) {
-        if (searchIndex >= start && searchIndex < end) {
-            startRun = run;
-            startOffset = searchIndex - start;
-        }
-        if (searchEnd > start && searchEnd <= end) {
-            endRun = run;
-            endOffset = searchEnd - start;
-        }
-    }
-
-    return {
-        found: true,
-        startRun,
-        startOffset,
-        endRun,
-        endOffset
-    };
+export function findTextInParagraphIndex(paragraphIndex, searchText) {
+    return resolveTextInParagraphIndex(paragraphIndex, searchText);
 }
 
-function cloneRunWithText(xmlDoc, rPr, newText) {
+function cloneRunWithText(xmlDoc, rPr, newText, revisionIdAllocator, preserveRevisionIds = false) {
     const newRun = createWordElement(xmlDoc, 'w:r');
-    if (rPr) {
-        newRun.appendChild(rPr.cloneNode(true));
+    if (rPr) {
+        const clonedRPr = rPr.cloneNode(true);
+        if (!preserveRevisionIds) {
+            refreshRunPropertyChangeIds(clonedRPr, revisionIdAllocator);
+        }
+        newRun.appendChild(clonedRPr);
     }
 
     const newTextNode = createWordElement(xmlDoc, 'w:t');
@@ -88,11 +184,12 @@ function cloneRunWithText(xmlDoc, rPr, newText) {
  * @param {string} textToFind - Target text
  * @param {number} commentId - Comment id
  * @param {{ fullText: string, runOffsets: Array<{run: Element, start: number, end: number}> }|null} [paragraphIndex=null] - Optional prebuilt index
- * @returns {boolean}
- */
-export function injectMarkersIntoParagraph(xmlDoc, paragraph, textToFind, commentId, paragraphIndex = null) {
-    const activeIndex = paragraphIndex || createParagraphTextIndex(paragraph);
-    const location = findTextInParagraphIndex(activeIndex, textToFind);
+ * @param {import('../core/types.js').RevisionIdAllocator|null} [revisionIdAllocator=null] - Document-scoped revision ID allocator
+ * @returns {boolean}
+ */
+export function injectMarkersIntoParagraph(xmlDoc, paragraph, textToFind, commentId, paragraphIndex = null, revisionIdAllocator = null, resolvedLocation = null) {
+    const activeIndex = paragraphIndex || createParagraphTextIndex(paragraph);
+    const location = resolvedLocation || resolveTextInParagraphIndex(activeIndex, textToFind);
     if (!location.found || !location.startRun) {
         return false;
     }
@@ -127,12 +224,13 @@ export function injectMarkersIntoParagraph(xmlDoc, paragraph, textToFind, commen
         const beforeText = fullText.substring(0, location.startOffset);
         const highlightedText = fullText.substring(location.startOffset, location.endOffset);
         const afterText = fullText.substring(location.endOffset);
-        const rPr = getFirstElementByTag(run, 'w:rPr');
-        const parent = run.parentNode;
-
-        if (beforeText) {
-            parent.insertBefore(cloneRunWithText(xmlDoc, rPr, beforeText), run);
-        }
+        const rPr = getFirstElementByTag(run, 'w:rPr');
+        const parent = run.parentNode;
+
+        if (beforeText) {
+            parent.insertBefore(cloneRunWithText(xmlDoc, rPr, beforeText, revisionIdAllocator, true), run);
+            refreshRunPropertyChangeIds(rPr, revisionIdAllocator);
+        }
 
         parent.insertBefore(startMarker, run);
         textNode.textContent = highlightedText;
@@ -144,8 +242,8 @@ export function injectMarkersIntoParagraph(xmlDoc, paragraph, textToFind, commen
         }
         parent.insertBefore(referenceRun, endMarker.nextSibling || null);
 
-        if (afterText) {
-            parent.insertBefore(cloneRunWithText(xmlDoc, rPr, afterText), referenceRun.nextSibling || null);
+        if (afterText) {
+            parent.insertBefore(cloneRunWithText(xmlDoc, rPr, afterText, revisionIdAllocator), referenceRun.nextSibling || null);
         }
 
         return true;
@@ -157,9 +255,13 @@ export function injectMarkersIntoParagraph(xmlDoc, paragraph, textToFind, commen
         const beforeText = fullText.substring(0, location.startOffset);
         const highlightedStart = fullText.substring(location.startOffset);
 
-        if (beforeText) {
-            const rPr = getFirstElementByTag(location.startRun, 'w:rPr');
-            location.startRun.parentNode.insertBefore(cloneRunWithText(xmlDoc, rPr, beforeText), location.startRun);
+        if (beforeText) {
+            const rPr = getFirstElementByTag(location.startRun, 'w:rPr');
+            location.startRun.parentNode.insertBefore(
+                cloneRunWithText(xmlDoc, rPr, beforeText, revisionIdAllocator, true),
+                location.startRun
+            );
+            refreshRunPropertyChangeIds(rPr, revisionIdAllocator);
         }
         startTextNode.textContent = highlightedStart;
     }
@@ -176,12 +278,15 @@ export function injectMarkersIntoParagraph(xmlDoc, paragraph, textToFind, commen
         endTextNode.textContent = highlightedEnd;
 
         if (afterText) {
-            const rPr = getFirstElementByTag(endRun, 'w:rPr');
-            if (endRun.nextSibling) {
-                endRun.parentNode.insertBefore(cloneRunWithText(xmlDoc, rPr, afterText), endRun.nextSibling);
-            } else {
-                endRun.parentNode.appendChild(cloneRunWithText(xmlDoc, rPr, afterText));
-            }
+            const rPr = getFirstElementByTag(endRun, 'w:rPr');
+            if (endRun.nextSibling) {
+                endRun.parentNode.insertBefore(
+                    cloneRunWithText(xmlDoc, rPr, afterText, revisionIdAllocator),
+                    endRun.nextSibling
+                );
+            } else {
+                endRun.parentNode.appendChild(cloneRunWithText(xmlDoc, rPr, afterText, revisionIdAllocator));
+            }
         }
     }
 

package/services/comment-replies.js

@@ -0,0 +1,95 @@
+import { createSerializer, parseOoxmlSafe } from '../adapters/xml-adapter.js';
+import { buildCommentElement, buildCommentsExtendedPartXml, createCommentParaId, NS_W14, NS_W15 } from './comment-builders.js';
+
+const NS_W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
+
+function attr(node, qualified, local) {
+    return node?.getAttribute?.(qualified) || node?.getAttribute?.(local) || '';
+}
+
+function parseRequired(xml, partName) {
+    const parsed = parseOoxmlSafe(xml, 'application/xml');
+    if (!parsed.doc || parsed.error) {
+        return { error: { code: 'PARSE_ERROR', message: `Could not parse ${partName}: ${parsed.error?.message || 'invalid XML'}` } };
+    }
+    return { doc: parsed.doc };
+}
+
+function usedParaIds(commentsDoc, extendedDoc) {
+    const ids = new Set();
+    for (const p of Array.from(commentsDoc?.getElementsByTagNameNS('*', 'p') || [])) {
+        const id = attr(p, 'w14:paraId', 'paraId');
+        if (id) ids.add(id.toUpperCase());
+    }
+    for (const ex of Array.from(extendedDoc?.getElementsByTagNameNS('*', 'commentEx') || [])) {
+        const id = attr(ex, 'w15:paraId', 'paraId');
+        if (id) ids.add(id.toUpperCase());
+    }
+    return ids;
+}
+
+function allocateParaId(commentId, occupied) {
+    let candidate = createCommentParaId(commentId);
+    let value = Number.parseInt(candidate, 16) >>> 0;
+    while (occupied.has(candidate)) {
+        value = (value + 1) >>> 0;
+        candidate = value.toString(16).toUpperCase().padStart(8, '0');
+    }
+    occupied.add(candidate);
+    return candidate;
+}
+
+export function applyCommentReplyToParts({ commentsXml, commentsExtendedXml = null, parentCommentId, commentId, commentContent, author, date = new Date().toISOString() }) {
+    if (!commentsXml) return { status: 'error', error: { code: 'COMMENTS_PART_MISSING', message: 'A comment reply requires an existing word/comments.xml part.' } };
+    const commentsParsed = parseRequired(commentsXml, 'word/comments.xml');
+    if (commentsParsed.error) return { status: 'error', error: commentsParsed.error };
+    const commentsDoc = commentsParsed.doc;
+    const parent = Array.from(commentsDoc.getElementsByTagNameNS('*', 'comment')).find(node => attr(node, 'w:id', 'id') === String(parentCommentId));
+    if (!parent) return { status: 'error', error: { code: 'PARENT_COMMENT_NOT_FOUND', message: `Parent comment '${parentCommentId}' was not found.` } };
+
+    let extendedDoc = null;
+    if (commentsExtendedXml) {
+        const parsed = parseRequired(commentsExtendedXml, 'word/commentsExtended.xml');
+        if (parsed.error) return { status: 'error', error: parsed.error };
+        extendedDoc = parsed.doc;
+    }
+    const occupied = usedParaIds(commentsDoc, extendedDoc);
+    const parentParagraph = Array.from(parent.getElementsByTagNameNS(NS_W, 'p'))[0] || Array.from(parent.getElementsByTagNameNS('*', 'p'))[0];
+    if (!parentParagraph) return { status: 'error', error: { code: 'PARENT_COMMENT_INVALID', message: `Parent comment '${parentCommentId}' has no paragraph.` } };
+    let parentParaId = attr(parentParagraph, 'w14:paraId', 'paraId');
+    if (!parentParaId) {
+        parentParaId = allocateParaId(parentCommentId, occupied);
+        parentParagraph.setAttributeNS(NS_W14, 'w14:paraId', parentParaId);
+    } else {
+        parentParaId = parentParaId.toUpperCase();
+    }
+    const replyParaId = allocateParaId(commentId, occupied);
+    const replyParsed = parseRequired(`<w:comments xmlns:w="${NS_W}" xmlns:w14="${NS_W14}">${buildCommentElement(commentId, author, commentContent, date, replyParaId)}</w:comments>`, 'reply comment');
+    commentsDoc.documentElement.appendChild(commentsDoc.importNode(replyParsed.doc.documentElement.firstChild, true));
+
+    if (!extendedDoc) {
+        extendedDoc = parseRequired(buildCommentsExtendedPartXml([]), 'word/commentsExtended.xml').doc;
+    }
+    const root = extendedDoc.documentElement;
+    const entries = Array.from(root.getElementsByTagNameNS('*', 'commentEx'));
+    if (!entries.some(node => attr(node, 'w15:paraId', 'paraId').toUpperCase() === parentParaId)) {
+        const parentEx = extendedDoc.createElementNS(NS_W15, 'w15:commentEx');
+        parentEx.setAttributeNS(NS_W15, 'w15:paraId', parentParaId);
+        parentEx.setAttributeNS(NS_W15, 'w15:done', '0');
+        root.appendChild(parentEx);
+    }
+    const replyEx = extendedDoc.createElementNS(NS_W15, 'w15:commentEx');
+    replyEx.setAttributeNS(NS_W15, 'w15:paraId', replyParaId);
+    replyEx.setAttributeNS(NS_W15, 'w15:paraIdParent', parentParaId);
+    replyEx.setAttributeNS(NS_W15, 'w15:done', '0');
+    root.appendChild(replyEx);
+
+    const serializer = createSerializer();
+    return {
+        status: 'ok', hasChanges: true,
+        commentsXml: serializer.serializeToString(commentsDoc),
+        commentsExtendedXml: serializer.serializeToString(extendedDoc),
+        commentsXmlMode: 'replace', commentsExtendedXmlMode: 'replace',
+        commentId, parentCommentId: String(parentCommentId), paraId: replyParaId, parentParaId
+    };
+}