@ansonlai/docx-redline-js 0.4.0 → 0.5.1

package/services/capture-engine.js

@@ -0,0 +1,226 @@
+/**
+ * Capture entity management, resolution, and validation for batch operations.
+ */
+
+import { NS_W } from '../core/types.js';
+import {
+    createParagraphFingerprint,
+    getDocumentParagraphNodes,
+    getParagraphId,
+    findContainingWordElement
+} from '../core/paragraph-targeting.js';
+import { extractCanonicalParagraphText } from '../core/paragraph-text.js';
+
+function createCaptureError(code, message) {
+    const error = new Error(message);
+    error.code = code;
+    return error;
+}
+
+export function ensureParagraphIdsOnImportedNode(_node, _session) {
+    // Preserves existing paragraph attributes without injecting undeclared namespaces into the document.
+}
+
+/**
+ * Derives a serializable CapturedEntity record from the live DOM nodes produced by an operation.
+ *
+ * @param {import('./document-operation-session.js').DocumentOperationSession} session
+ * @param {object} operation
+ * @param {Array<Element>} liveNodes
+ * @returns {object} CapturedEntity
+ */
+export function deriveCapturedEntity(session, operation, liveNodes) {
+    const paragraphs = [];
+    let hasTable = false;
+    let hasList = false;
+
+    for (const node of (liveNodes || [])) {
+        if (!node) continue;
+        if (node.localName === 'tbl') {
+            hasTable = true;
+            paragraphs.push(...Array.from(node.getElementsByTagNameNS(NS_W, 'p')));
+        } else if (node.localName === 'p') {
+            if (node.getElementsByTagNameNS(NS_W, 'numPr').length > 0) {
+                hasList = true;
+            }
+            paragraphs.push(node);
+        }
+    }
+
+    const kind = hasTable
+        ? 'table'
+        : (hasList ? 'list' : (paragraphs.length > 1 ? 'range' : 'paragraph'));
+
+    const generatedParagraphIds = [];
+    const fingerprints = [];
+    const expectedText = [];
+    const structuralPathHints = [];
+
+    const xmlDoc = session.document;
+    const allDocParagraphs = getDocumentParagraphNodes(xmlDoc);
+
+    for (const p of paragraphs) {
+        const paraId = getParagraphId(p) || '';
+        generatedParagraphIds.push(paraId);
+        const text = extractCanonicalParagraphText(p);
+        expectedText.push(text);
+        const pIndex = allDocParagraphs.indexOf(p) + 1;
+        fingerprints.push(createParagraphFingerprint(p, {
+            text,
+            paragraphId: paraId || null,
+            index: pIndex > 0 ? pIndex : undefined,
+            inTable: hasTable || !!findContainingWordElement(p, 'tbl')
+        }));
+        const parentTag = p.parentNode?.localName || 'body';
+        structuralPathHints.push(`${parentTag}/${p.localName}`);
+    }
+
+    return {
+        captureKey: operation.captureKey,
+        operationIndex: typeof operation.index === 'number' ? operation.index : 0,
+        kind,
+        generatedParagraphIds,
+        fingerprints,
+        expectedText,
+        structuralPathHints,
+        stale: false
+    };
+}
+
+/**
+ * Invalidates any captures in the session capture table that referenced removed or replaced paragraphs.
+ *
+ * @param {Map<string, object>} captureTable
+ * @param {Array<Element>} removedNodes
+ */
+export function invalidateAffectedCaptures(captureTable, removedNodes) {
+    if (!captureTable || !(captureTable instanceof Map) || !Array.isArray(removedNodes) || removedNodes.length === 0) return;
+    const removedIds = new Set();
+    for (const node of removedNodes) {
+        if (!node) continue;
+        if (node.localName === 'p') {
+            const id = getParagraphId(node);
+            if (id) removedIds.add(id);
+        } else if (typeof node.getElementsByTagNameNS === 'function') {
+            for (const p of Array.from(node.getElementsByTagNameNS(NS_W, 'p'))) {
+                const id = getParagraphId(p);
+                if (id) removedIds.add(id);
+            }
+        }
+    }
+    if (removedIds.size === 0) return;
+    for (const [, captured] of captureTable) {
+        if (captured.stale) continue;
+        if (captured.generatedParagraphIds.some(id => id && removedIds.has(id))) {
+            captured.stale = true;
+        }
+    }
+}
+
+/**
+ * Resolves a target paragraph from an existing capture in the session capture table.
+ *
+ * @param {Document} xmlDoc
+ * @param {import('./document-operation-session.js').DocumentOperationSession} session
+ * @param {object} targetDescriptor
+ * @param {string} opType
+ * @param {object} options
+ * @returns {{ paragraph: Element, resolvedBy: 'capture' }}
+ */
+export function resolveTargetFromCapture(xmlDoc, session, targetDescriptor, _opType = 'redline', _options = {}) {
+    const captureRef = targetDescriptor?.captureRef;
+    if (!captureRef) {
+        throw createCaptureError('INVALID_OPERATION', 'Operation target is missing captureRef.');
+    }
+
+    if (!session || !session.captureTable || !session.captureTable.has(captureRef)) {
+        throw createCaptureError('CAPTURE_NOT_FOUND', `Capture "${captureRef}" was not found in the session capture table.`);
+    }
+
+    const captured = session.captureTable.get(captureRef);
+    if (captured.stale) {
+        throw createCaptureError('CAPTURE_STALE', `Capture "${captureRef}" is stale; the captured content was modified or removed.`);
+    }
+
+    const metadataIndex = session.getParagraphMetadataIndex();
+    const liveParagraphs = [];
+
+    for (let i = 0; i < captured.expectedText.length; i++) {
+        const expectedParaId = captured.generatedParagraphIds[i];
+        const expected = captured.expectedText[i];
+        let foundNode = null;
+
+        if (expectedParaId && metadataIndex.byId.has(expectedParaId)) {
+            foundNode = metadataIndex.byId.get(expectedParaId).paragraph;
+        }
+
+        if (!foundNode) {
+            const candidate = metadataIndex.entries.find(entry =>
+                entry.text === expected || entry.fingerprint === captured.fingerprints[i]
+            );
+            if (candidate) foundNode = candidate.paragraph;
+        }
+
+        if (!foundNode || !foundNode.parentNode) {
+            captured.stale = true;
+            throw createCaptureError('CAPTURE_STALE', `Capture "${captureRef}" is stale; paragraph ${i + 1} was removed from the document.`);
+        }
+
+        const currentText = extractCanonicalParagraphText(foundNode);
+        if (currentText !== expected) {
+            captured.stale = true;
+            throw createCaptureError('CAPTURE_STALE', `Capture "${captureRef}" is stale; paragraph ${i + 1} content drifted from "${expected}" to "${currentText}".`);
+        }
+
+        liveParagraphs.push(foundNode);
+    }
+
+    if (liveParagraphs.length === 0) {
+        captured.stale = true;
+        throw createCaptureError('CAPTURE_STALE', `Capture "${captureRef}" is stale; no live paragraphs found.`);
+    }
+
+    const select = targetDescriptor.select;
+    if (select == null || select === '') {
+        if (liveParagraphs.length === 1) {
+            return { paragraph: liveParagraphs[0], resolvedBy: 'capture' };
+        }
+        throw createCaptureError(
+            'AMBIGUOUS_CAPTURE_SELECTION',
+            `Capture "${captureRef}" contains ${liveParagraphs.length} paragraphs; target.select is required to disambiguate.`
+        );
+    }
+
+    let matched = [];
+    const trimmedSelect = String(select).trim();
+    if (trimmedSelect === ':first' || trimmedSelect === 'first') {
+        matched = [liveParagraphs[0]];
+    } else if (trimmedSelect === ':last' || trimmedSelect === 'last') {
+        matched = [liveParagraphs[liveParagraphs.length - 1]];
+    } else if (/^\d+$/.test(trimmedSelect)) {
+        const index1Based = parseInt(trimmedSelect, 10);
+        if (index1Based >= 1 && index1Based <= liveParagraphs.length) {
+            matched = [liveParagraphs[index1Based - 1]];
+        }
+    } else {
+        const exactMatches = liveParagraphs.filter(p => extractCanonicalParagraphText(p).trim() === trimmedSelect);
+        if (exactMatches.length > 0) {
+            matched = exactMatches;
+        } else {
+            matched = liveParagraphs.filter(p => extractCanonicalParagraphText(p).includes(trimmedSelect));
+        }
+    }
+
+    if (matched.length === 0) {
+        throw createCaptureError('TARGET_NOT_FOUND', `Target selection "${select}" was not found in capture "${captureRef}".`);
+    }
+
+    if (matched.length > 1) {
+        throw createCaptureError(
+            'AMBIGUOUS_CAPTURE_SELECTION',
+            `Target selection "${select}" matched ${matched.length} paragraphs in capture "${captureRef}".`
+        );
+    }
+
+    return { paragraph: matched[0], resolvedBy: 'capture' };
+}

package/services/comment-builders.js

@@ -2,7 +2,16 @@
  * Comment XML builders.
  */
 
-import { NS_W, escapeXml } from '../core/types.js';
+import { NS_W, escapeXml } from '../core/types.js';
+
+export const NS_W14 = 'http://schemas.microsoft.com/office/word/2010/wordml';
+export const NS_W15 = 'http://schemas.microsoft.com/office/word/2012/wordml';
+
+export function createCommentParaId(commentId) {
+    const numeric = Number.parseInt(String(commentId), 10);
+    const value = Number.isFinite(numeric) ? (0x70000000 + (numeric >>> 0)) >>> 0 : 0x70000000;
+    return value.toString(16).toUpperCase().padStart(8, '0').slice(-8);
+}
 
 /**
  * Builds a single w:comment element.
@@ -13,13 +22,13 @@ import { NS_W, escapeXml } from '../core/types.js';
  * @param {string} date - ISO date string
  * @returns {string}
  */
-export function buildCommentElement(commentId, author, content, date) {
+export function buildCommentElement(commentId, author, content, date, paraId = createCommentParaId(commentId)) {
     const initials = author.split(' ').map(word => word[0]).join('').toUpperCase() || 'AI';
     const escapedContent = escapeXml(content);
     const escapedAuthor = escapeXml(author);
 
     return `<w:comment w:id="${commentId}" w:author="${escapedAuthor}" w:date="${date}" w:initials="${initials}">
-      <w:p>
+      <w:p w14:paraId="${escapeXml(paraId)}" xmlns:w14="${NS_W14}">
         <w:r><w:t>${escapedContent}</w:t></w:r>
       </w:p>
     </w:comment>`;
@@ -31,19 +40,27 @@ export function buildCommentElement(commentId, author, content, date) {
  * @param {Array<{id:number,content:string,author:string,date:string}>} comments - Placed comments
  * @returns {string}
  */
-export function buildCommentsPartXml(comments) {
+export function buildCommentsPartXml(comments) {
     if (!comments || comments.length === 0) {
         return `<w:comments xmlns:w="${NS_W}"></w:comments>`;
     }
 
     const commentElements = comments.map(comment =>
-        buildCommentElement(comment.id, comment.author, comment.content, comment.date)
+        buildCommentElement(comment.id, comment.author, comment.content, comment.date, comment.paraId)
     ).join('\n    ');
 
     return `<w:comments xmlns:w="${NS_W}">
     ${commentElements}
   </w:comments>`;
-}
+}
+
+export function buildCommentsExtendedPartXml(entries) {
+    const body = (entries || []).map(entry => {
+        const parent = entry.paraIdParent ? ` w15:paraIdParent="${escapeXml(entry.paraIdParent)}"` : '';
+        return `<w15:commentEx w15:paraId="${escapeXml(entry.paraId)}"${parent} w15:done="${entry.done ? '1' : '0'}"/>`;
+    }).join('');
+    return `<w15:commentsEx xmlns:w15="${NS_W15}">${body}</w15:commentsEx>`;
+}
 
 /**
  * Builds inline range/reference markers for a comment id.

package/services/comment-engine.js

@@ -4,13 +4,19 @@
  * Provides pure OOXML-based comment insertion without Word JS API calls.
  */
 
-import { NS_W, getNextRevisionId, getRevisionTimestamp, resetRevisionIdCounter } from '../core/types.js';
+import {
+    NS_W,
+    createRevisionIdAllocator,
+    getNextRevisionId,
+    getRevisionTimestamp,
+    resetRevisionIdCounter
+} from '../core/types.js';
 import { createSerializer, parseOoxmlSafe } from '../adapters/xml-adapter.js';
 import { log, error as logError } from '../adapters/logger.js';
 import { getElementsByTag, getFirstElementByTag, getXmlParseError } from '../core/xml-query.js';
 import { buildCommentElement, buildCommentsPartXml, buildCommentMarkers } from './comment-builders.js';
 import { getDefaultAuthor } from '../adapters/config.js';
-import { createParagraphTextIndex, injectMarkersIntoParagraph } from './comment-locator.js';
+import { createParagraphTextIndex, injectMarkersIntoParagraph, resolveTextInParagraphIndex } from './comment-locator.js';
 import {
     injectCommentsIntoPackage as injectCommentsIntoExistingPackage,
     wrapParagraphWithComments,
@@ -63,7 +69,9 @@ export function injectCommentsIntoOoxml(oxml, comments, options = {}) {
     const author = options?.author || getDefaultAuthor();
     const date = getRevisionTimestamp();
     const warnings = [];
-    const placedComments = [];
+    const placedComments = [];
+    const resolvedAnchors = [];
+    const errors = [];
 
     if (!comments || comments.length === 0) {
         return {
@@ -93,26 +101,29 @@ export function injectCommentsIntoOoxml(oxml, comments, options = {}) {
         };
     }
 
-    const xmlDoc = parseResult.xmlDoc;
-    const paragraphs = getElementsByTag(xmlDoc, 'w:p');
+    const xmlDoc = parseResult.xmlDoc;
+    const revisionIdAllocator = createRevisionIdAllocator(xmlDoc);
+    const paragraphs = getElementsByTag(xmlDoc, 'w:p');
     log(`[CommentEngine] Found ${paragraphs.length} paragraphs, processing ${comments.length} comment requests`);
 
     /** @type {Map<number, number>} */
     const remainingRequestsByParagraph = new Map();
-    for (const request of comments) {
-        const paragraphIndex = request.paragraphIndex - 1;
-        if (paragraphIndex < 0 || paragraphIndex >= paragraphs.length) {
-            warnings.push(`Paragraph ${request.paragraphIndex} out of range (1-${paragraphs.length})`);
-            continue;
-        }
+    for (const request of comments) {
+        const paragraphIndex = request.paragraphIndex - 1;
+        if (paragraphIndex < 0 || paragraphIndex >= paragraphs.length) {
+            const message = `Paragraph ${request.paragraphIndex} out of range (1-${paragraphs.length})`;
+            warnings.push(message);
+            errors.push({ code: 'TARGET_NOT_FOUND', message, paragraphIndex: request.paragraphIndex });
+            continue;
+        }
         remainingRequestsByParagraph.set(paragraphIndex, (remainingRequestsByParagraph.get(paragraphIndex) || 0) + 1);
     }
 
     /** @type {Map<number, { fullText: string, runOffsets: Array<{run: Element, start: number, end: number}> }>} */
     const paragraphIndexes = new Map();
 
-    for (const request of comments) {
-        const paragraphIndex = request.paragraphIndex - 1;
+    for (const [requestIndex, request] of comments.entries()) {
+        const paragraphIndex = request.paragraphIndex - 1;
         if (paragraphIndex < 0 || paragraphIndex >= paragraphs.length) {
             continue;
         }
@@ -124,32 +135,64 @@ export function injectCommentsIntoOoxml(oxml, comments, options = {}) {
             paragraphIndexes.set(paragraphIndex, textIndex);
         }
 
-        const commentId = getNextRevisionId();
-        const success = injectMarkersIntoParagraph(
-            xmlDoc,
-            targetParagraph,
-            request.textToFind,
-            commentId,
-            textIndex
-        );
-
-        const remaining = (remainingRequestsByParagraph.get(paragraphIndex) || 1) - 1;
-        remainingRequestsByParagraph.set(paragraphIndex, remaining);
-
-        if (!success) {
-            warnings.push(`Could not find "${request.textToFind.substring(0, 30)}..." in paragraph ${request.paragraphIndex}`);
-            if (remaining === 0) {
-                paragraphIndexes.delete(paragraphIndex);
-            }
+        const anchorText = String(request.textToFind ?? '');
+        const resolution = resolveTextInParagraphIndex(textIndex, anchorText);
+        const remaining = (remainingRequestsByParagraph.get(paragraphIndex) || 1) - 1;
+        remainingRequestsByParagraph.set(paragraphIndex, remaining);
+        if (!resolution.found) {
+            const error = {
+                ...resolution.error,
+                requestIndex: requestIndex + 1,
+                paragraphIndex: request.paragraphIndex
+            };
+            errors.push(error);
+            warnings.push(error.message);
+            if (remaining === 0) paragraphIndexes.delete(paragraphIndex);
+            continue;
+        }
+
+        const commentId = typeof options.commentIdAllocator === 'function'
+            ? options.commentIdAllocator()
+            : getNextRevisionId();
+        const success = injectMarkersIntoParagraph(
+            xmlDoc,
+            targetParagraph,
+            anchorText,
+            commentId,
+            textIndex,
+            revisionIdAllocator,
+            resolution
+        );
+
+        if (!success) {
+            const error = {
+                code: 'ANCHOR_INSERTION_FAILED',
+                message: `Resolved comment anchor could not be inserted in paragraph ${request.paragraphIndex}.`,
+                requestIndex: requestIndex + 1,
+                paragraphIndex: request.paragraphIndex
+            };
+            errors.push(error);
+            warnings.push(error.message);
+            if (remaining === 0) {
+                paragraphIndexes.delete(paragraphIndex);
+            }
             continue;
         }
 
-        placedComments.push({
+        placedComments.push({
             id: commentId,
             content: request.commentContent,
             author,
-            date
-        });
+            date
+        });
+        resolvedAnchors.push({
+            requestIndex: requestIndex + 1,
+            paragraphIndex: request.paragraphIndex,
+            text: anchorText,
+            resolvedBy: resolution.resolvedBy,
+            start: resolution.start,
+            end: resolution.end
+        });
 
         if (remaining > 0) {
             // Rebuild only when another request still targets this paragraph.
@@ -159,21 +202,26 @@ export function injectCommentsIntoOoxml(oxml, comments, options = {}) {
         }
     }
 
-    if (placedComments.length === 0) {
+    if (placedComments.length === 0) {
         return {
             oxml,
             hasChanges: false,
             commentsApplied: 0,
-            warnings
+            warnings,
+            resolvedAnchors,
+            ...(errors.length > 0 ? { status: 'error', error: errors[0], errors } : {})
         };
-    }
+    }
 
     return {
         oxml: serializer.serializeToString(xmlDoc),
         hasChanges: true,
         commentsXml: buildCommentsPartXml(placedComments),
-        commentsApplied: placedComments.length,
-        warnings
+        commentsApplied: placedComments.length,
+        placedComments,
+        warnings,
+        resolvedAnchors,
+        ...(errors.length > 0 ? { status: 'error', error: errors[0], errors } : {})
     };
 }
 
@@ -187,10 +235,9 @@ export function injectCommentsIntoOoxml(oxml, comments, options = {}) {
  * @param {string} [options.author='AI Assistant'] - Comment author
  * @returns {{ success: boolean, package?: string, warning?: string, commentId?: number }}
  */
-export function injectCommentIntoParagraphOoxml(paragraphOoxml, textToFind, commentContent, options = {}) {
-    const { author = 'AI Assistant' } = options;
-    const date = getRevisionTimestamp();
-    const commentId = getNextRevisionId();
+export function injectCommentIntoParagraphOoxml(paragraphOoxml, textToFind, commentContent, options = {}) {
+    const { author = 'AI Assistant' } = options;
+    const date = getRevisionTimestamp();
 
     const serializer = createSerializer();
     const parseResult = parseDocumentOxml(
@@ -202,15 +249,29 @@ export function injectCommentIntoParagraphOoxml(paragraphOoxml, textToFind, comm
         return { success: false, warning: parseResult.warning };
     }
 
-    const xmlDoc = parseResult.xmlDoc;
-    const paragraphs = getElementsByTag(xmlDoc, 'w:p');
+    const xmlDoc = parseResult.xmlDoc;
+    const revisionIdAllocator = createRevisionIdAllocator(xmlDoc);
+    const paragraphs = getElementsByTag(xmlDoc, 'w:p');
     if (paragraphs.length === 0) {
         return { success: false, warning: 'No paragraph found in OOXML' };
     }
 
-    const paragraph = paragraphs[0];
-    const paragraphIndex = createParagraphTextIndex(paragraph);
-    const success = injectMarkersIntoParagraph(xmlDoc, paragraph, textToFind, commentId, paragraphIndex);
+    const paragraph = paragraphs[0];
+    const paragraphIndex = createParagraphTextIndex(paragraph);
+    const resolution = resolveTextInParagraphIndex(paragraphIndex, textToFind);
+    if (!resolution.found) {
+        return { success: false, warning: resolution.error.message, error: resolution.error };
+    }
+    const commentId = getNextRevisionId();
+    const success = injectMarkersIntoParagraph(
+        xmlDoc,
+        paragraph,
+        textToFind,
+        commentId,
+        paragraphIndex,
+        revisionIdAllocator,
+        resolution
+    );
     if (!success) {
         return { success: false, warning: `Could not find "${textToFind.substring(0, 30)}..." in paragraph` };
     }