docrev 0.9.7 → 0.9.11

package/lib/commands/verify-anchors.ts

@@ -23,7 +23,7 @@ import {
   jsonOutput,
 } from './context.js';
 import type { Command } from 'commander';
-import { findAnchorInText, classifyStrategy, type AnchorMatchQuality } from '../anchor-match.js';
+import { findAnchorInText, classifyStrategy, scoreContextAt, type AnchorMatchQuality } from '../anchor-match.js';
 import type { CommentAnchorData } from '../word-extraction.js';
 import { computeSectionBoundaries } from './section-boundaries.js';
 
@@ -71,10 +71,12 @@ export function register(program: Command): void {
       let comments;
       let anchors;
       let headings;
+      let fullDocText = '';
       try {
         comments = await extractWordComments(docxPath);
         const result = await extractCommentAnchors(docxPath);
         anchors = result.anchors;
+        fullDocText = result.fullDocText;
         headings = await extractHeadings(docxPath);
       } catch (err) {
         const error = err as Error;
@@ -88,7 +90,7 @@ export function register(program: Command): void {
         return;
       }
 
-      const boundaries = computeSectionBoundaries(config.sections, headings);
+      const boundaries = computeSectionBoundaries(config.sections, headings, fullDocText.length);
 
       // Cache section markdown contents on first read
       const sectionCache = new Map<string, string>();
@@ -165,7 +167,16 @@ export function register(program: Command): void {
         const search = findAnchorInText(anchor.anchor, md, anchor.before, anchor.after);
         let quality: AnchorMatchQuality | 'ambiguous' = classifyStrategy(search.strategy, search.occurrences.length);
         if (quality === 'clean' && search.occurrences.length > 1) {
-          quality = 'ambiguous';
+          // Multiple direct hits — only flag as ambiguous when before/after
+          // context can't pick a clear winner. If one candidate scores
+          // strictly higher than the others, sync will place it correctly.
+          const anchorLen = anchor.anchor.length;
+          const scores = search.occurrences.map(p => scoreContextAt(p, md, anchor.before, anchor.after, anchorLen));
+          const max = Math.max(...scores);
+          const winners = scores.filter(s => s === max).length;
+          if (max === 0 || winners > 1) {
+            quality = 'ambiguous';
+          }
         }
 
         reports.push({
@@ -239,7 +250,7 @@ function printReport(docxPath: string, reports: CommentReport[]): void {
   if (totals.unmatched > 0 || totals.ambiguous > 0) {
     console.log();
     console.log(chalk.dim('Comments flagged "unmatched" or "ambiguous" need manual placement.'));
-    console.log(chalk.dim('Run "rev sync --no-overwrite" to import the matched ones without touching prose.'));
+    console.log(chalk.dim('Run "rev sync --comments-only" to import the matched ones without touching prose.'));
   }
 }
 

package/lib/comment-realign.ts

@@ -370,7 +370,7 @@ export async function realignComments(
 
   // Strip ALL comments (both authors) from markdown to start fresh
   let markdown = originalMarkdown;
-  markdown = markdown.replace(/\s*\{>>[^<]+<<\}/g, '');
+  markdown = markdown.replace(/\s*\{>>[\s\S]+?<<\}/g, '');
   console.log(`Stripped all comments from markdown`);
 
   // Parse markdown paragraphs
@@ -469,7 +469,7 @@ export async function realignMarkdown(
     );
 
     // Strip ALL comments from markdown
-    let result = markdown.replace(/\s*\{>>[^<]+<<\}/g, '');
+    let result = markdown.replace(/\s*\{>>[\s\S]+?<<\}/g, '');
 
     // Parse markdown paragraphs
     const mdParagraphs = parseMdParagraphs(result);

package/lib/import.ts

@@ -36,7 +36,65 @@ import {
   parseVisibleComments,
   convertVisibleComments,
 } from './restore-references.js';
-import { findAnchorInText } from './anchor-match.js';
+import { findAnchorInText, findAllOccurrences } from './anchor-match.js';
+
+/**
+ * Pick the best position from candidate `occurrences` given the
+ * surrounding `before` / `after` context from the docx, while
+ * respecting `usedPositions` to avoid stacking distinct comments at
+ * the same anchor instance.
+ *
+ * Returns the chosen position, or -1 if every candidate is already used.
+ */
+function pickBestOccurrence(
+  occurrences: number[],
+  result: string,
+  before: string,
+  after: string,
+  anchorLen: number,
+  usedPositions: Set<number>,
+): number {
+  if (occurrences.length === 0) return -1;
+  if (occurrences.length === 1) {
+    return usedPositions.has(occurrences[0]) ? -1 : occurrences[0];
+  }
+
+  let bestIdx = occurrences.find(p => !usedPositions.has(p)) ?? -1;
+  if (bestIdx < 0) return -1;
+  let bestScore = -1;
+
+  for (const pos of occurrences) {
+    if (usedPositions.has(pos)) continue;
+    let score = 0;
+
+    if (before) {
+      const contextBefore = result.slice(Math.max(0, pos - before.length - 20), pos).toLowerCase();
+      const beforeLower = before.toLowerCase();
+      const beforeWords = beforeLower.split(/\s+/).filter(w => w.length > 3);
+      for (const word of beforeWords) {
+        if (contextBefore.includes(word)) score += 2;
+      }
+      if (contextBefore.includes(beforeLower.slice(-30))) score += 5;
+    }
+
+    if (after) {
+      const contextAfter = result.slice(pos + anchorLen, pos + anchorLen + after.length + 20).toLowerCase();
+      const afterLower = after.toLowerCase();
+      const afterWords = afterLower.split(/\s+/).filter(w => w.length > 3);
+      for (const word of afterWords) {
+        if (contextAfter.includes(word)) score += 2;
+      }
+      if (contextAfter.includes(afterLower.slice(0, 30))) score += 5;
+    }
+
+    if (score > bestScore || (score === bestScore && pos < bestIdx)) {
+      bestScore = score;
+      bestIdx = pos;
+    }
+  }
+
+  return bestIdx;
+}
 
 // Re-export everything so existing imports from './import.js' still work
 export {
@@ -100,6 +158,14 @@ export interface InsertCommentsOptions {
    * comments sharing one anchor don't produce nested broken markup.
    */
   wrapAnchor?: boolean;
+  /**
+   * Mutable output: when provided, the function fills in counters so callers
+   * can distinguish placement outcomes in their summary. `placed` counts new
+   * insertions, `deduped` counts comments that were already present at their
+   * anchor (skipped to avoid duplication on re-sync), `unmatched` counts
+   * comments whose anchor couldn't be located.
+   */
+  outStats?: { placed: number; deduped: number; unmatched: number };
 }
 
 export interface CommentWithPos {
@@ -175,6 +241,34 @@ export interface MoveExtractedMediaResult {
 // Functions
 // ============================================
 
+/**
+ * If `pos` lands inside a section file's leading `# Heading` line (or the
+ * blank line right after it), advance past the first paragraph break so
+ * the comment stays inside the section. A comment authored at the very
+ * start of a Word section maps to `pos === 0`, but inserting at column 0
+ * of a markdown file that begins with `# Heading` puts the `{>>...<<}`
+ * before the heading marker — Pandoc then treats the line as ordinary
+ * paragraph text and the comment renders in the previous section.
+ */
+function pushPastSectionHeading(text: string, pos: number): number {
+  if (pos > 0) {
+    const headingMatch = text.match(/^#{1,6}\s.+$/m);
+    if (!headingMatch || headingMatch.index === undefined) return pos;
+    const headingEnd = headingMatch.index + headingMatch[0].length;
+    if (pos >= headingEnd) return pos;
+  }
+  // pos is at-or-before the first heading line. Advance to the first
+  // non-blank position after the heading paragraph.
+  const headingLine = text.match(/^#{1,6}\s.+(?:\n|$)/m);
+  if (!headingLine || headingLine.index === undefined) return pos;
+  let after = headingLine.index + headingLine[0].length;
+  // Skip blank lines so we land at the start of the first body paragraph.
+  while (after < text.length && (text[after] === '\n' || text[after] === '\r')) {
+    after++;
+  }
+  return after;
+}
+
 /**
  * Insert comments into markdown text based on anchor texts with context
  */
@@ -184,9 +278,10 @@ export function insertCommentsIntoMarkdown(
   anchors: Map<string, CommentAnchorData | string>,
   options: InsertCommentsOptions = {}
 ): string {
-  const { quiet = false, sectionBoundary = null, wrapAnchor = true } = options;
+  const { quiet = false, sectionBoundary = null, wrapAnchor = true, outStats } = options;
   let result = markdown;
   let unmatchedCount = 0;
+  let placedCount = 0;
   const duplicateWarnings: string[] = [];
   const usedPositions = new Set<number>(); // For tie-breaking: track used positions
 
@@ -222,6 +317,18 @@ export function insertCommentsIntoMarkdown(
         const proportion = Math.min(relativePos / sectionLength, 1.0);
         const markdownPos = Math.floor(proportion * result.length);
 
+        // For empty anchors, before/after context is the only signal that
+        // pinpoints the original split — without it, proportional placement
+        // can land mid-word or split unrelated phrases. Try context match
+        // first; only fall through to proportional when context is gone.
+        if ((!anchor || isEmpty) && (before || after)) {
+          const ctx = findAnchorInText('', result, before, after);
+          if (ctx.occurrences.length > 0) {
+            const pos = pushPastSectionHeading(result, ctx.occurrences[0]);
+            return { ...c, pos, anchorText: null, isEmpty: true, strategy: `ctx:${ctx.strategy}` };
+          }
+        }
+
         let insertPos = markdownPos;
 
         // Look for nearby word boundary
@@ -231,26 +338,52 @@ export function insertCommentsIntoMarkdown(
           insertPos = Math.max(0, markdownPos - 25) + spaceIdx;
         }
 
-        // If we have anchor text, try to find it near this position
+        // If we have anchor text, try to find it near this position.
+        // Collect ALL occurrences in the local window, then disambiguate
+        // via before/after context + usedPositions — otherwise two
+        // comments sharing the same anchor word would both collide at
+        // the leftmost match. The context-scoring helper handles the
+        // "repeated formulaic prose" case using docx-side context, which
+        // is a stronger signal than raw distance to the proportional
+        // insertPos (insertPos is itself an approximation).
         if (anchor && !isEmpty) {
           const searchStart = Math.max(0, insertPos - 200);
           const searchEnd = Math.min(result.length, insertPos + 200);
           const localSearch = result.slice(searchStart, searchEnd).toLowerCase();
           const anchorLower = anchor.toLowerCase();
-          const localIdx = localSearch.indexOf(anchorLower);
-          if (localIdx !== -1) {
-            return { ...c, pos: searchStart + localIdx, anchorText: anchor, anchorEnd: searchStart + localIdx + anchor.length, strategy: 'position+text' };
+
+          const localHits = findAllOccurrences(localSearch, anchorLower).map(i => searchStart + i);
+          if (localHits.length > 0) {
+            const chosen = pickBestOccurrence(localHits, result, before, after, anchor.length, usedPositions);
+            if (chosen >= 0) {
+              if (localHits.length > 1) {
+                duplicateWarnings.push(`"${anchor.slice(0, 40)}${anchor.length > 40 ? '...' : ''}" appears ${localHits.length} times in section window`);
+              }
+              usedPositions.add(chosen);
+              return { ...c, pos: chosen, anchorText: anchor, anchorEnd: chosen + anchor.length, strategy: 'position+text' };
+            }
           }
+
           // Try first few words
           const words = anchor.split(/\s+/).slice(0, 4).join(' ').toLowerCase();
           if (words.length >= 10) {
-            const partialIdx = localSearch.indexOf(words);
-            if (partialIdx !== -1) {
-              return { ...c, pos: searchStart + partialIdx, anchorText: words, anchorEnd: searchStart + partialIdx + words.length, strategy: 'position+partial' };
+            const partialHits = findAllOccurrences(localSearch, words).map(i => searchStart + i);
+            if (partialHits.length > 0) {
+              const chosen = pickBestOccurrence(partialHits, result, before, after, words.length, usedPositions);
+              if (chosen >= 0) {
+                usedPositions.add(chosen);
+                return { ...c, pos: chosen, anchorText: words, anchorEnd: chosen + words.length, strategy: 'position+partial' };
+              }
             }
           }
         }
 
+        // A docPosition at the very start of a section maps to markdownPos=0,
+        // which sits before the file's `# Heading` line and gets rendered in
+        // the previous section. Push past the heading line so the comment
+        // stays inside the section it was authored in.
+        insertPos = pushPastSectionHeading(result, insertPos);
+
         return { ...c, pos: insertPos, anchorText: null, strategy: 'position-only' };
       }
     }
@@ -290,46 +423,14 @@ export function insertCommentsIntoMarkdown(
       duplicateWarnings.push(`"${matchedAnchor.slice(0, 40)}${matchedAnchor.length > 40 ? '...' : ''}" appears ${occurrences.length} times`);
     }
 
-    let bestIdx = occurrences.find(p => !usedPositions.has(p)) ?? occurrences[0];
-    let bestScore = -1;
-
-    for (const pos of occurrences) {
-      if (usedPositions.has(pos)) continue;
-
-      let score = 0;
-
-      if (before) {
-        const contextBefore = result.slice(Math.max(0, pos - before.length - 20), pos).toLowerCase();
-        const beforeLower = before.toLowerCase();
-        const beforeWords = beforeLower.split(/\s+/).filter(w => w.length > 3);
-        for (const word of beforeWords) {
-          if (contextBefore.includes(word)) score += 2;
-        }
-        if (contextBefore.includes(beforeLower.slice(-30))) score += 5;
-      }
-
-      if (after) {
-        const contextAfter = result.slice(pos + anchorLen, pos + anchorLen + after.length + 20).toLowerCase();
-        const afterLower = after.toLowerCase();
-        const afterWords = afterLower.split(/\s+/).filter(w => w.length > 3);
-        for (const word of afterWords) {
-          if (contextAfter.includes(word)) score += 2;
-        }
-        if (contextAfter.includes(afterLower.slice(0, 30))) score += 5;
-      }
-
-      if (score > bestScore || (score === bestScore && pos < bestIdx)) {
-        bestScore = score;
-        bestIdx = pos;
-      }
-    }
-
-    usedPositions.add(bestIdx);
+    const bestIdx = pickBestOccurrence(occurrences, result, before, after, anchorLen, usedPositions);
+    const finalIdx = bestIdx >= 0 ? bestIdx : occurrences[0];
+    usedPositions.add(finalIdx);
 
     if (matchedAnchor) {
-      return { ...c, pos: bestIdx, anchorText: matchedAnchor, anchorEnd: bestIdx + anchorLen };
+      return { ...c, pos: finalIdx, anchorText: matchedAnchor, anchorEnd: finalIdx + anchorLen };
     } else {
-      return { ...c, pos: bestIdx, anchorText: null };
+      return { ...c, pos: finalIdx, anchorText: null };
     }
   });
 
@@ -352,8 +453,21 @@ export function insertCommentsIntoMarkdown(
   // original Word comment range. Without it, the comment block is inserted
   // adjacent to the anchor and prose stays untouched — required for
   // comments-only sync where multiple comments may share one anchor.
+  // Skip insertion when an identical comment already lives near the target.
+  // Re-running sync against the same docx would otherwise stack duplicate
+  // CriticMarkup blocks (`{>>R1: ...<<}{>>R1: ...<<}...`) on each invocation.
+  // A 200-char window catches both wrapped (`{>>...<<}[anchor]{.mark}`) and
+  // bare (`{>>...<<}anchor`) forms while ignoring incidental matches farther
+  // away.
+  let dedupedCount = 0;
   for (const c of matched) {
     const comment = `{>>${c.author}: ${c.text}<<}`;
+    const windowStart = Math.max(0, c.pos - 200);
+    const windowEnd = Math.min(result.length, c.pos + 200);
+    if (result.slice(windowStart, windowEnd).includes(comment)) {
+      dedupedCount++;
+      continue;
+    }
     if (wrapAnchor && c.anchorText && c.anchorEnd) {
       const before = result.slice(0, c.pos);
       const anchor = result.slice(c.pos, c.anchorEnd);
@@ -366,6 +480,13 @@ export function insertCommentsIntoMarkdown(
       // verify that --comments-only didn't touch the original).
       result = result.slice(0, c.pos) + comment + result.slice(c.pos);
     }
+    placedCount++;
+  }
+
+  if (outStats) {
+    outStats.placed = placedCount;
+    outStats.deduped = dedupedCount;
+    outStats.unmatched = unmatchedCount;
   }
 
   // Log warnings unless quiet mode
@@ -373,6 +494,9 @@ export function insertCommentsIntoMarkdown(
     if (unmatchedCount > 0) {
       console.warn(`Warning: ${unmatchedCount} comment(s) could not be matched to anchor text`);
     }
+    if (dedupedCount > 0) {
+      console.warn(`Note: ${dedupedCount} comment(s) already present at anchor — skipped to avoid duplication`);
+    }
     if (duplicateWarnings.length > 0) {
       console.warn(`Warning: Duplicate anchor text found (using context & tie-breaks for placement):`);
       for (const w of duplicateWarnings) {

package/lib/response.ts

@@ -46,7 +46,7 @@ export function parseCommentsWithReplies(text: string, file: string = ''): Comme
     if (matches.length === 0) continue;
 
     // Get context (surrounding text without comments)
-    const contextLine = line.replace(/\{>>[^<]+<<\}/g, '').trim();
+    const contextLine = line.replace(/\{>>[\s\S]+?<<\}/g, '').trim();
     const context = contextLine.slice(0, 100) + (contextLine.length > 100 ? '...' : '');
 
     // First match is the original comment, rest are replies