docrev 0.10.2 → 0.11.0

package/lib/word.ts

@@ -6,11 +6,15 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import AdmZip from 'adm-zip';
-import { parseString } from 'xml2js';
-import { promisify } from 'util';
 import type { WordComment, CommentAnchor, WordMetadata, TrackChangesResult } from './types.js';
-
-const parseXml = promisify(parseString);
+import {
+  openDocx,
+  readPartText,
+  buildCommentAnchorModel,
+  extractComments,
+  walkBody,
+  type FlowItem,
+} from './ooxml.js';
 
 // =============================================================================
 // Constants
@@ -41,52 +45,10 @@ export async function extractWordComments(docxPath: string): Promise<WordComment
     throw new Error(`File not found: ${docxPath}`);
   }
 
-  const zip = new AdmZip(docxPath);
-  const commentsEntry = zip.getEntry('word/comments.xml');
-
-  if (!commentsEntry) {
-    return []; // No comments in document
-  }
-
-  const commentsXml = zip.readAsText(commentsEntry);
-  const parsed = await parseXml(commentsXml) as any;
-
-  if (!parsed?.['w:comments'] || !parsed['w:comments']['w:comment']) {
-    return [];
-  }
-
-  const comments: WordComment[] = [];
-  const rawComments = parsed['w:comments']['w:comment'];
-
-  for (const comment of rawComments) {
-    const id = comment.$?.['w:id'];
-    const author = comment.$?.['w:author'] || 'Unknown';
-    const date = comment.$?.['w:date'];
-
-    // Extract text from all paragraphs in comment
-    let text = '';
-    const paragraphs = comment['w:p'] || [];
-    for (const para of paragraphs) {
-      const runs = para['w:r'] || [];
-      for (const run of runs) {
-        const texts = run['w:t'] || [];
-        for (const t of texts) {
-          text += typeof t === 'string' ? t : (t._ || '');
-        }
-      }
-    }
-
-    if (id && text.trim()) {
-      comments.push({
-        id,
-        author,
-        date,
-        text: text.trim(),
-      });
-    }
-  }
-
-  return comments;
+  const zip = openDocx(docxPath);
+  return extractComments(zip)
+    .filter((c) => c.id && c.text)
+    .map((c) => ({ id: c.id, author: c.author, date: c.date, text: c.text }));
 }
 
 /**
@@ -102,63 +64,18 @@ export async function extractCommentAnchors(docxPath: string): Promise<Map<strin
     throw new TypeError(`docxPath must be a string, got ${typeof docxPath}`);
   }
 
-  const zip = new AdmZip(docxPath);
-  const documentEntry = zip.getEntry('word/document.xml');
-
-  if (!documentEntry) {
+  const zip = openDocx(docxPath);
+  if (!zip.getEntry('word/document.xml')) {
     throw new Error('Invalid docx: no document.xml');
   }
 
-  const documentXml = zip.readAsText(documentEntry);
+  const { fullDocText, comments } = buildCommentAnchorModel(zip);
   const anchors = new Map<string, CommentAnchor>();
 
-  // Find commentRangeStart and commentRangeEnd pairs
-  // The text between them is what the comment is anchored to
-  const startPattern = /<w:commentRangeStart w:id="(\d+)"\/>/g;
-  const endPattern = /<w:commentRangeEnd w:id="(\d+)"\/>/g;
-
-  let match: RegExpExecArray | null;
-  const starts = new Map<string, number>();
-  const ends = new Map<string, number>();
-
-  while ((match = startPattern.exec(documentXml)) !== null) {
-    if (match[1]) {
-      starts.set(match[1], match.index);
-    }
-  }
-
-  while ((match = endPattern.exec(documentXml)) !== null) {
-    if (match[1]) {
-      ends.set(match[1], match.index);
-    }
-  }
-
-  // For each comment, extract the text between start and end
-  for (const [id, startPos] of starts) {
-    const endPos = ends.get(id);
-    if (!endPos) continue;
-
-    const segment = documentXml.slice(startPos, endPos);
-
-    // Extract all text content from the segment
-    const textPattern = /<w:t[^>]*>([^<]*)<\/w:t>/g;
-    let text = '';
-    let textMatch: RegExpExecArray | null;
-    while ((textMatch = textPattern.exec(segment)) !== null) {
-      text += textMatch[1] ?? '';
-    }
-
-    // Get surrounding context (text before the anchor)
-    const contextStart = Math.max(0, startPos - CONTEXT_BEFORE_SIZE);
-    const contextSegment = documentXml.slice(contextStart, startPos);
-    let context = '';
-    while ((textMatch = textPattern.exec(contextSegment)) !== null) {
-      context += textMatch[1] ?? '';
-    }
-
-    anchors.set(id, {
-      text: text.trim(),
-      context: context.slice(-ANCHOR_CONTEXT_SIZE),
+  for (const range of comments) {
+    anchors.set(range.id, {
+      text: range.anchor,
+      context: fullDocText.slice(Math.max(0, range.start - CONTEXT_BEFORE_SIZE), range.start).slice(-ANCHOR_CONTEXT_SIZE),
     });
   }
 
@@ -443,118 +360,84 @@ export async function extractPlainTextWithTrackChanges(docxPath: string): Promis
     throw new Error(`File not found: ${docxPath}`);
   }
 
-  const zip = new AdmZip(docxPath);
-  const docEntry = zip.getEntry('word/document.xml');
-
-  if (!docEntry) {
+  const zip = openDocx(docxPath);
+  const docXml = readPartText(zip, 'word/document.xml');
+  if (docXml === null) {
     throw new Error('Invalid docx: no document.xml');
   }
 
-  let xml = docEntry.getData().toString('utf8');
   let insertions = 0;
   let deletions = 0;
-
-  // Use unique markers (null bytes) that won't appear in normal text
-  const INS_S = '\x00IS\x00';
-  const INS_E = '\x00IE\x00';
-  const DEL_S = '\x00DS\x00';
-  const DEL_E = '\x00DE\x00';
-
-  // Step 1: Replace <w:ins> with marker-wrapped text injected as <w:t>
-  // Whitespace-only insertions are kept as plain text (not markers) to preserve spacing.
-  xml = xml.replace(/<w:ins\b[^>]*>([\s\S]*?)<\/w:ins>/g, (_match, content: string) => {
-    const texts: string[] = [];
-    const tPat = /<w:t[^>]*>([^<]*)<\/w:t>/g;
-    let m: RegExpExecArray | null;
-    while ((m = tPat.exec(content)) !== null) {
-      texts.push(m[1] || '');
-    }
-    const text = texts.join('');
-    if (text.trim()) {
-      insertions++;
-      return `<w:r><w:t>${INS_S}${text}${INS_E}</w:t></w:r>`;
-    }
-    // Whitespace-only: preserve as plain text for spacing
-    if (text.length > 0) {
-      return `<w:r><w:t>${text}</w:t></w:r>`;
-    }
-    return '';
-  });
-
-  // Step 2: Replace <w:del> similarly (uses w:delText inside)
-  // Whitespace-only deletions are kept as plain text to preserve spacing.
-  xml = xml.replace(/<w:del\b[^>]*>([\s\S]*?)<\/w:del>/g, (_match, content: string) => {
-    const texts: string[] = [];
-    const tPat = /<w:delText[^>]*>([^<]*)<\/w:delText>|<w:t[^>]*>([^<]*)<\/w:t>/g;
-    let m: RegExpExecArray | null;
-    while ((m = tPat.exec(content)) !== null) {
-      texts.push(m[1] || m[2] || '');
-    }
-    const text = texts.join('');
-    if (text.trim()) {
-      deletions++;
-      return `<w:r><w:t>${DEL_S}${text}${DEL_E}</w:t></w:r>`;
-    }
-    // Whitespace-only: preserve as plain text for spacing
-    if (text.length > 0) {
-      return `<w:r><w:t>${text}</w:t></w:r>`;
-    }
-    return '';
-  });
-
-  // Step 3: Extract text paragraph by paragraph
   const paragraphs: string[] = [];
-  const paraPattern = /<w:p\b[^>]*>([\s\S]*?)<\/w:p>/g;
-  let pm: RegExpExecArray | null;
-
-  while ((pm = paraPattern.exec(xml)) !== null) {
-    const paraXml = pm[1];
 
-    // Detect heading level from paragraph style
-    let headingLevel = 0;
-    const styleMatch = paraXml.match(/<w:pStyle\s+w:val="Heading(\d)"/i);
-    if (styleMatch && styleMatch[1]) {
-      headingLevel = parseInt(styleMatch[1], 10);
+  // One ordered walk drives everything: paragraph and heading boundaries,
+  // run text (entities already decoded, tabs/breaks rendered), and the
+  // track-change spans that become CriticMarkup. Field codes (w:instrText)
+  // never reach the text because the walker only reads w:t / w:delText.
+  let paraOut = '';
+  let headingLevel = 0;
+  let mode: 'normal' | 'ins' | 'del' = 'normal';
+  let buffer = '';
+
+  const flushSpan = (open: string, close: string, isIns: boolean) => {
+    if (buffer.trim()) {
+      if (isIns) insertions++;
+      else deletions++;
+      paraOut += `${open}${buffer}${close}`;
+    } else if (buffer.length > 0) {
+      // Whitespace-only edits are kept as plain text to preserve spacing.
+      paraOut += buffer;
     }
+    buffer = '';
+  };
 
-    // Extract all <w:t> text in order
-    const texts: string[] = [];
-    const tPat = /<w:t[^>]*>([^<]*)<\/w:t>/g;
-    let tm: RegExpExecArray | null;
-    while ((tm = tPat.exec(paraXml)) !== null) {
-      texts.push(tm[1] || '');
+  const endParagraph = () => {
+    let text = mergeAdjacentMarkers(paraOut);
+    text = text.replace(/ {2,}/g, ' ');
+    if (text.trim()) {
+      paragraphs.push(
+        headingLevel >= 1 && headingLevel <= 6 ? '#'.repeat(headingLevel) + ' ' + text.trim() : text,
+      );
     }
+    paraOut = '';
+    headingLevel = 0;
+    mode = 'normal';
+    buffer = '';
+  };
 
-    let paraText = texts.join('');
-
-    // Decode XML entities
-    paraText = paraText
-      .replace(/&amp;/g, '&')
-      .replace(/&lt;/g, '<')
-      .replace(/&gt;/g, '>')
-      .replace(/&quot;/g, '"')
-      .replace(/&apos;/g, "'");
-
-    // Convert markers to CriticMarkup
-    paraText = paraText
-      .split(INS_S).join('{++')
-      .split(INS_E).join('++}')
-      .split(DEL_S).join('{--')
-      .split(DEL_E).join('--}');
-
-    // Merge adjacent del+ins (or ins+del) into substitutions.
-    // Uses a scanner instead of regex to avoid backtracking across marker boundaries.
-    paraText = mergeAdjacentMarkers(paraText);
-
-    // Collapse runs of multiple spaces into single space
-    paraText = paraText.replace(/ {2,}/g, ' ');
-
-    if (paraText.trim()) {
-      if (headingLevel > 0 && headingLevel <= 6) {
-        paragraphs.push('#'.repeat(headingLevel) + ' ' + paraText.trim());
-      } else {
-        paragraphs.push(paraText);
-      }
+  for (const item of walkBody(docXml) as FlowItem[]) {
+    switch (item.kind) {
+      case 'paraStart':
+        paraOut = '';
+        headingLevel = item.level;
+        mode = 'normal';
+        buffer = '';
+        break;
+      case 'paraEnd':
+        endParagraph();
+        break;
+      case 'text':
+        if (mode === 'normal') paraOut += item.text;
+        else buffer += item.text;
+        break;
+      case 'insStart':
+        mode = 'ins';
+        buffer = '';
+        break;
+      case 'insEnd':
+        flushSpan('{++', '++}', true);
+        mode = 'normal';
+        break;
+      case 'delStart':
+        mode = 'del';
+        buffer = '';
+        break;
+      case 'delEnd':
+        flushSpan('{--', '--}', false);
+        mode = 'normal';
+        break;
+      default:
+        break;
     }
   }
 

package/lib/wordcomments.ts

@@ -13,6 +13,7 @@
 import * as fs from 'fs';
 import AdmZip from 'adm-zip';
 import { escapeXml } from './utils.js';
+import { indexTextRuns, type TextRunSlot } from './ooxml.js';
 
 const MARKER_START_PREFIX = '⟦CMS:';
 const MARKER_END_PREFIX = '⟦CME:';
@@ -467,7 +468,25 @@ export async function injectCommentsAtMarkers(
 
     const injectedIds = new Set<string>();
 
-    // Process only parent comments (non-replies) for document ranges
+    // Locate the enclosing run of each marker structurally, so placement never
+    // scans backwards for the nearest `<w:r`. Markers that pandoc duplicated
+    // into attributes (e.g. <wp:docPr descr="...">) are not inside a <w:t>, so
+    // they never appear in the index and cannot mislead the placement.
+    // See: https://github.com/gcol33/docrev/issues/4
+    //
+    // The index is rebuilt each iteration against the current document: two
+    // markers can share one run, so splicing one run invalidates offsets into
+    // it for the next marker.
+    const findMarkerSlot = (slots: TextRunSlot[], marker: string): { slot: TextRunSlot; rel: number } | null => {
+      for (const slot of slots) {
+        const rel = slot.content.indexOf(marker);
+        if (rel >= 0) return { slot, rel };
+      }
+      return null;
+    };
+
+    // Process only parent comments (non-replies) for document ranges, from the
+    // last document position backwards.
     const parentComments = commentsWithIds.filter(c => !c.isReply);
 
     for (let i = parentComments.length - 1; i >= 0; i--) {
@@ -478,85 +497,17 @@ export async function injectCommentsAtMarkers(
       const startMarker = `${MARKER_START_PREFIX}${idx}${MARKER_SUFFIX}`;
       const endMarker = `${MARKER_END_PREFIX}${idx}${MARKER_SUFFIX}`;
 
-      // Pandoc duplicates inline image alt-text into <wp:docPr descr="...">
-      // metadata attributes AND into the visible caption paragraph. A naive
-      // indexOf hits the metadata-attribute occurrence first, where there is
-      // no <w:t> element so dissectRun fails. Skip occurrences whose position
-      // is inside an XML tag (last unbalanced '<' before position).
-      // See: https://github.com/gcol33/docrev/issues/4
-      function findInTextContent(haystack: string, needle: string, fromIdx = 0): number {
-        let i = fromIdx;
-        while (true) {
-          const p = haystack.indexOf(needle, i);
-          if (p < 0) return -1;
-          const lastLt = haystack.lastIndexOf('<', p);
-          const lastGt = haystack.lastIndexOf('>', p);
-          if (lastLt > lastGt) {
-            i = p + 1;
-            continue;
-          }
-          return p;
-        }
-      }
+      const slots = indexTextRuns(documentXml);
+      const startHit = findMarkerSlot(slots, startMarker);
+      const endHit = startHit ? findMarkerSlot(slots, endMarker) : null;
+      if (!startHit || !endHit) continue;
 
-      const startPos = findInTextContent(documentXml, startMarker);
-      const endPos = startPos === -1
-        ? -1
-        : findInTextContent(documentXml, endMarker, startPos + startMarker.length);
-
-      if (startPos === -1 || endPos === -1) continue;
-
-      // Find the runs containing each marker. Pandoc may split a single
-      // markdown anchor across multiple <w:r> blocks when it applies styling
-      // mid-anchor (smart-quote substitution, *italic*, `code`, **bold**).
-      // The same-run path (current happy path) collapses into the multi-run
-      // path when start and end runs coincide.
-      const startRunOpen = Math.max(
-        documentXml.lastIndexOf('<w:r>', startPos),
-        documentXml.lastIndexOf('<w:r ', startPos),
-      );
-      const startRunCloseIdx = documentXml.indexOf('</w:r>', startPos);
-      const endRunOpen = Math.max(
-        documentXml.lastIndexOf('<w:r>', endPos),
-        documentXml.lastIndexOf('<w:r ', endPos),
-      );
-      const endRunCloseIdx = documentXml.indexOf('</w:r>', endPos);
-
-      if (
-        startRunOpen === -1 || startRunCloseIdx === -1 ||
-        endRunOpen === -1 || endRunCloseIdx === -1
-      ) continue;
-
-      const startRunClose = startRunCloseIdx + '</w:r>'.length;
-      const endRunClose = endRunCloseIdx + '</w:r>'.length;
-
-      const startRunFull = documentXml.slice(startRunOpen, startRunClose);
-      const endRunFull = documentXml.slice(endRunOpen, endRunClose);
-
-      // Extract <w:rPr> and <w:t> element shape from each run. Both pieces
-      // are needed verbatim so a textBefore split keeps its original styling
-      // and so the post-anchor textAfter render keeps the end run's styling.
-      function dissectRun(runXml: string, marker: string): {
-        rPr: string;
-        tElement: string;
-        textBefore: string;
-        textAfter: string;
-      } | null {
-        const rPrMatch = runXml.match(/<w:rPr>[\s\S]*?<\/w:rPr>/);
-        const tMatch = runXml.match(/<w:t[^>]*>([\s\S]*?)<\/w:t>/);
-        if (!tMatch) return null;
-        const tOpenMatch = tMatch[0].match(/<w:t[^>]*>/);
-        if (!tOpenMatch) return null;
-        const tContent = tMatch[1] ?? '';
-        const markerInT = tContent.indexOf(marker);
-        if (markerInT === -1) return null;
-        return {
-          rPr: rPrMatch ? rPrMatch[0] : '',
-          tElement: tOpenMatch[0],
-          textBefore: tContent.slice(0, markerInT),
-          textAfter: tContent.slice(markerInT + marker.length),
-        };
-      }
+      const startSlot = startHit.slot;
+      const endSlot = endHit.slot;
+      const startRunOpen = startSlot.runOpenStart;
+      const startRunClose = startSlot.runCloseEnd;
+      const endRunOpen = endSlot.runOpenStart;
+      const endRunClose = endSlot.runCloseEnd;
 
       let replacement = '';
       const replies = commentsWithIds.filter(c => c.isReply && c.parentIdx === comment?.commentIdx);
@@ -579,16 +530,15 @@ export async function injectCommentsAtMarkers(
       };
 
       if (startRunOpen === endRunOpen) {
-        // Same-run path: both markers live inside one <w:t>. Original logic.
-        const startInfo = dissectRun(startRunFull, startMarker);
-        if (!startInfo) continue;
-        const fullText = startInfo.textBefore + startMarker + startInfo.textAfter;
-        const endInTextRel = startInfo.textAfter.indexOf(endMarker);
+        // Same-run path: both markers live inside one <w:t>.
+        const rPr = startSlot.rPr;
+        const tElement = startSlot.tOpenTag;
+        const afterStart = startSlot.content.slice(startHit.rel + startMarker.length);
+        const endInTextRel = afterStart.indexOf(endMarker);
         if (endInTextRel === -1) continue;
-        const anchorTextSame = startInfo.textAfter.slice(0, endInTextRel);
-        let textAfter = startInfo.textAfter.slice(endInTextRel + endMarker.length);
-        let anchorText = anchorTextSame;
-        let textBefore = startInfo.textBefore;
+        let textBefore = startSlot.content.slice(0, startHit.rel);
+        let anchorText = afterStart.slice(0, endInTextRel);
+        let textAfter = afterStart.slice(endInTextRel + endMarker.length);
 
         // Empty anchor: borrow the next word so the comment has something
         // to anchor on. Then normalize the trailing double space.
@@ -602,19 +552,17 @@ export async function injectCommentsAtMarkers(
         if (!anchorText && textBefore.endsWith(' ') && textAfter.startsWith(' ')) {
           textAfter = textAfter.slice(1);
         }
-        // Suppress unused warning for pre-empty-anchor fullText var
-        void fullText;
 
         if (textBefore) {
-          replacement += `<w:r>${startInfo.rPr}${startInfo.tElement}${textBefore}</w:t></w:r>`;
+          replacement += `<w:r>${rPr}${tElement}${textBefore}</w:t></w:r>`;
         }
         emitRangeStarts();
         if (anchorText) {
-          replacement += `<w:r>${startInfo.rPr}${startInfo.tElement}${anchorText}</w:t></w:r>`;
+          replacement += `<w:r>${rPr}${tElement}${anchorText}</w:t></w:r>`;
         }
         emitRangeEnds();
         if (textAfter) {
-          replacement += `<w:r>${startInfo.rPr}${startInfo.tElement}${textAfter}</w:t></w:r>`;
+          replacement += `<w:r>${rPr}${tElement}${textAfter}</w:t></w:r>`;
         }
         documentXml = documentXml.slice(0, startRunOpen) + replacement + documentXml.slice(startRunClose);
         injectedIds.add(comment.id);
@@ -625,26 +573,27 @@ export async function injectCommentsAtMarkers(
       // applied mid-anchor styling. Split the start run at the start marker,
       // keep all middle runs verbatim (they carry the styled anchor portions),
       // split the end run at the end marker.
-      const startInfo = dissectRun(startRunFull, startMarker);
-      const endInfo = dissectRun(endRunFull, endMarker);
-      if (!startInfo || !endInfo) continue;
+      const startTextBefore = startSlot.content.slice(0, startHit.rel);
+      const startTextAfter = startSlot.content.slice(startHit.rel + startMarker.length);
+      const endTextBefore = endSlot.content.slice(0, endHit.rel);
+      const endTextAfter = endSlot.content.slice(endHit.rel + endMarker.length);
 
       const middle = documentXml.slice(startRunClose, endRunOpen);
 
-      if (startInfo.textBefore) {
-        replacement += `<w:r>${startInfo.rPr}${startInfo.tElement}${startInfo.textBefore}</w:t></w:r>`;
+      if (startTextBefore) {
+        replacement += `<w:r>${startSlot.rPr}${startSlot.tOpenTag}${startTextBefore}</w:t></w:r>`;
       }
       emitRangeStarts();
-      if (startInfo.textAfter) {
-        replacement += `<w:r>${startInfo.rPr}${startInfo.tElement}${startInfo.textAfter}</w:t></w:r>`;
+      if (startTextAfter) {
+        replacement += `<w:r>${startSlot.rPr}${startSlot.tOpenTag}${startTextAfter}</w:t></w:r>`;
       }
       replacement += middle;
-      if (endInfo.textBefore) {
-        replacement += `<w:r>${endInfo.rPr}${endInfo.tElement}${endInfo.textBefore}</w:t></w:r>`;
+      if (endTextBefore) {
+        replacement += `<w:r>${endSlot.rPr}${endSlot.tOpenTag}${endTextBefore}</w:t></w:r>`;
       }
       emitRangeEnds();
-      if (endInfo.textAfter) {
-        replacement += `<w:r>${endInfo.rPr}${endInfo.tElement}${endInfo.textAfter}</w:t></w:r>`;
+      if (endTextAfter) {
+        replacement += `<w:r>${endSlot.rPr}${endSlot.tOpenTag}${endTextAfter}</w:t></w:r>`;
       }
 
       documentXml = documentXml.slice(0, startRunOpen) + replacement + documentXml.slice(endRunClose);