docrev 0.6.7 → 0.6.13

package/README.md

@@ -1,18 +1,14 @@
 # docrev
 
 [![npm](https://img.shields.io/npm/v/docrev)](https://www.npmjs.com/package/docrev)
+[![npm downloads](https://img.shields.io/npm/dm/docrev)](https://www.npmjs.com/package/docrev)
+[![node](https://img.shields.io/node/v/docrev)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/gcol33/docrev/actions/workflows/ci.yml/badge.svg)](https://github.com/gcol33/docrev/actions/workflows/ci.yml)
 
-Write scientific papers in Markdown. Generate Word documents for collaborators. Import their feedback. Repeat.
+A CLI for writing scientific papers in Markdown while collaborating with Word users.
 
-```
-Markdown  ──►  docrev  ──►  Word/PDF  ──►  Collaborators
-    ▲                                           │
-    └───────────  docrev  ◄─────────────────────┘
-                (import feedback)
-```
-
-Scientific papers go through many revision cycles with collaborators and reviewers. Track changes become unreadable, versions multiply, equations break when copying, figures get embedded at wrong resolutions. docrev keeps your source in plain Markdown under version control while generating Word documents for the review cycle. Your collaborators keep using Word as usual. You handle conversion on your end.
+You write in Markdown under version control. Your collaborators use Word. docrev converts between the two, preserving track changes, comments, equations, and cross-references.
 
 ## Install
 
@@ -21,20 +17,20 @@ npm install -g docrev
 brew install pandoc
 ```
 
-## Start a Project
+Pandoc is required for document conversion. On Windows use `winget install JohnMacFarlane.Pandoc`, on Linux use `apt install pandoc`.
 
-From scratch:
-```bash
-rev new my-paper
-cd my-paper
-```
+## Getting Started
+
+### Starting from a Word Document
+
+If you have an existing manuscript in Word:
 
-From existing Word document:
 ```bash
 rev import manuscript.docx
 ```
 
-Project structure:
+This converts your document to markdown, splitting it into sections:
+
 ```
 my-paper/
 ├── introduction.md
@@ -45,130 +41,211 @@ my-paper/
 └── rev.yaml
 ```
 
-## Markdown Basics
+Track changes and comments from the Word document are preserved as annotations in the markdown files (see below).
 
-```markdown
-# Heading
+### Starting from Scratch
 
-Paragraph text. **Bold** and *italic*.
+To start a new paper in markdown:
 
-- Bullet point
-- Another point
+```bash
+rev new my-paper
+cd my-paper
+```
+
+This creates the same project structure with empty section files. Write your paper in the markdown files, then build Word documents to share with collaborators.
+
+## The Revision Cycle
+
+### 1. Build and Share
 
-1. Numbered item
-2. Second item
+Generate a Word document from your markdown:
+
+```bash
+rev build docx
 ```
 
-### Citations
+Send this to your collaborators. They review it in Word, adding comments and track changes as usual.
 
-references.bib:
-```bibtex
-@article{Smith2020,
-  author = {Smith, Jane},
-  title = {Paper Title},
-  journal = {Nature},
-  year = {2020}
-}
+### 2. Import Feedback
+
+When collaborators return the reviewed document, import their feedback:
+
+```bash
+rev sections reviewed.docx
 ```
 
-In text:
+This updates your markdown files with their comments and track changes, converted to inline annotations.
+
+### 3. Review Track Changes
+
+Track changes appear as inline annotations in your markdown:
+
 ```markdown
-Previous studies [@Smith2020] demonstrated this.
+The sample size was {--100--}{++150++} individuals.
+We collected data {~~monthly~>weekly~~} from each site.
 ```
 
-Output: "Previous studies (Smith 2020) demonstrated this."
+- `{++text++}` — inserted text
+- `{--text--}` — deleted text
+- `{~~old~>new~~}` — substitution
 
-### Equations
+To accept a change, keep the new text and delete the markup. To reject it, keep the old text. When you're done, the file is clean markdown.
+
+### 4. Respond to Comments
 
-Inline: `$E = mc^2$`
+Comments appear inline in your markdown:
 
-Display:
 ```markdown
-$$
-\hat{p} = \frac{\sum_d w_d p_d}{\sum_d w_d}
-$$
+We used a random sampling approach.
+{>>Reviewer 2: Please clarify the sampling method.<<}
 ```
 
-### Figures
+List all comments in a file:
 
-```markdown
-![Study site locations](figures/map.png){#fig:map}
+```bash
+rev comments methods.md
+```
+
+Reply from the command line:
 
-Results shown in @fig:map indicate regional variation.
+```bash
+rev config user "Your Name"    # one-time setup
+rev reply methods.md -n 1 -m "Added clarification in paragraph 2"
 ```
 
-Output: "Results shown in Figure 1 indicate regional variation."
+Your reply threads beneath the original:
 
-Figure numbers update automatically when reordered.
+```markdown
+We used a random sampling approach.
+{>>Reviewer 2: Please clarify the sampling method.<<}
+{>>Your Name: Added clarification in paragraph 2.<<}
+```
 
-## Build
+Mark comments as resolved:
 
 ```bash
-rev build docx          # Word document
-rev build pdf           # PDF
-rev build --dual        # Clean + comments versions
-rev watch docx          # Auto-rebuild on save
+rev resolve methods.md -n 1
 ```
 
-## Handle Reviewer Feedback
+### 5. Rebuild with Comment Threads
+
+Generate both a clean version and one showing the comment threads:
 
-Import reviewed document:
 ```bash
-rev sections reviewed.docx
+rev build --dual
+```
+
+This produces:
+- `paper.docx` — clean, for submission
+- `paper_comments.docx` — includes comment threads as Word comments
+
+Your collaborators see the full conversation in the comments pane.
+
+### 6. Repeat
+
+Send the updated Word document. Import new feedback with `rev sections`. Continue until done.
+
+## Before Submission
+
+### Validate Your Bibliography
+
+Check that DOIs in your bibliography resolve correctly:
+
+```bash
+rev doi check references.bib
 ```
 
-View comments:
+Find DOIs for entries missing them:
+
 ```bash
-rev comments methods.md
+rev doi lookup references.bib
 ```
 
-Reply to comment:
+Add a citation directly from a DOI:
+
 ```bash
-rev config user "Your Name"
-rev reply methods.md -n 1 -m "Clarified sampling methodology"
+rev doi add 10.1038/s41586-020-2649-2
 ```
 
-Rebuild with threaded comments:
+### Run Pre-Submission Checks
+
+Check for broken references, missing citations, and common issues:
+
 ```bash
-rev build --dual
+rev check
 ```
 
-Output:
-- `paper.docx` (clean)
-- `paper_comments.docx` (with comment threads)
+## Writing in Markdown
 
-## Commands
+### Citations
+
+Add references to `references.bib`:
+
+```bibtex
+@article{Smith2020,
+  author = {Smith, Jane},
+  title = {Paper Title},
+  journal = {Nature},
+  year = {2020},
+  doi = {10.1038/example}
+}
+```
+
+Cite in text:
+
+```markdown
+Previous work [@Smith2020] established this relationship.
+Multiple sources support this [@Smith2020; @Jones2021].
+```
+
+### Equations
+
+Inline equations use single dollar signs: `$E = mc^2$`
+
+Display equations use double dollar signs:
+
+```markdown
+$$
+\bar{x} = \frac{1}{n} \sum_{i=1}^{n} x_i
+$$
+```
+
+### Figures and Cross-References
+
+```markdown
+![Study site locations](figures/map.png){#fig:map}
+
+Results are shown in @fig:map.
+```
+
+The reference `@fig:map` becomes "Figure 1" in the output. Numbers update automatically when figures are reordered.
+
+Tables and equations work the same way with `@tbl:label` and `@eq:label`.
+
+## Useful Commands
 
 | Task | Command |
 |------|---------|
-| New project | `rev new my-paper` |
-| Import Word | `rev import manuscript.docx` |
+| Start new project | `rev new my-paper` |
+| Import Word document | `rev import manuscript.docx` |
+| Import feedback | `rev sections reviewed.docx` |
+| List comments | `rev comments methods.md` |
+| Reply to comment | `rev reply methods.md -n 1 -m "response"` |
 | Build Word | `rev build docx` |
 | Build PDF | `rev build pdf` |
-| Import feedback | `rev sections reviewed.docx` |
-| View comments | `rev comments methods.md` |
-| Reply to comment | `rev reply methods.md -n 1 -m "text"` |
+| Build both clean and annotated | `rev build --dual` |
+| Check DOIs | `rev doi check references.bib` |
+| Find missing DOIs | `rev doi lookup references.bib` |
 | Word count | `rev word-count` |
-| Validate DOIs | `rev doi check` |
-| Pre-submit check | `rev check` |
+| Pre-submission check | `rev check` |
+| Watch for changes | `rev watch docx` |
 
-Full reference: [docs/commands.md](docs/commands.md)
+Full command reference: [docs/commands.md](docs/commands.md)
 
 ## Requirements
 
 - Node.js 18+
-- Pandoc
-
-```bash
-# macOS
-brew install pandoc
-
-# Windows
-winget install JohnMacFarlane.Pandoc
-
-# Linux
-sudo apt install pandoc
-```
+- Pandoc 2.11+
 
 ## License
 

package/lib/import.js

@@ -268,7 +268,8 @@ export function insertCommentsIntoMarkdown(markdown, comments, anchors, options
 
     if (occurrences.length === 1) {
       // Unique match - easy case
-      return { ...c, pos: occurrences[0] + anchor.length, anchorText: anchor };
+      // Position at START of anchor (comment goes before, anchor gets marked)
+      return { ...c, pos: occurrences[0], anchorText: anchor, anchorEnd: occurrences[0] + anchor.length };
     }
 
     // Multiple occurrences - use context for disambiguation
@@ -321,16 +322,26 @@ export function insertCommentsIntoMarkdown(markdown, comments, anchors, options
     // Mark this position as used for tie-breaking subsequent comments
     usedPositions.add(bestIdx);
 
-    return { ...c, pos: bestIdx + anchor.length, anchorText: anchor };
-  }).filter((c) => c.pos > 0);
+    // Position at START of anchor (comment goes before, anchor gets marked)
+    return { ...c, pos: bestIdx, anchorText: anchor, anchorEnd: bestIdx + anchor.length };
+  }).filter((c) => c.pos >= 0);
 
   // Sort by position descending (insert from end to avoid offset issues)
   commentsWithPositions.sort((a, b) => b.pos - a.pos);
 
-  // Insert each comment
+  // Insert each comment with anchor marking
   for (const c of commentsWithPositions) {
-    const commentMark = ` {>>${c.author}: ${c.text}<<}`;
-    result = result.slice(0, c.pos) + commentMark + result.slice(c.pos);
+    const comment = `{>>${c.author}: ${c.text}<<}`;
+    if (c.anchorText && c.anchorEnd) {
+      // Replace anchor text with: {>>comment<<}[anchor]{.mark}
+      const before = result.slice(0, c.pos);
+      const anchor = result.slice(c.pos, c.anchorEnd);
+      const after = result.slice(c.anchorEnd);
+      result = before + comment + `[${anchor}]{.mark}` + after;
+    } else {
+      // No anchor - just insert comment at position
+      result = result.slice(0, c.pos) + ` ${comment}` + result.slice(c.pos);
+    }
   }
 
   // Log warnings unless quiet mode

package/lib/wordcomments.js

@@ -2,9 +2,9 @@
  * Word comment injection with reply threading
  *
  * Flow:
- * 1. prepareMarkdownWithMarkers() - Parse comments, detect Guy→Gilles reply pairs
- *    - Guy comments get markers: ⟦CMS:n⟧anchor⟦CME:n⟧
- *    - Gilles replies: no markers (they attach to parent comment)
+ * 1. prepareMarkdownWithMarkers() - Parse comments, detect reply relationships
+ *    - First comment in a cluster = parent (gets markers: ⟦CMS:n⟧anchor⟦CME:n⟧)
+ *    - Subsequent adjacent comments = replies (no markers, attach to parent)
  * 2. Pandoc converts to DOCX
  * 3. injectCommentsAtMarkers() - Insert comment ranges for parents only
  *    - Replies go in comments.xml with parent reference in commentsExtended.xml
@@ -71,50 +71,41 @@ export function prepareMarkdownWithMarkers(markdown) {
     return { markedMarkdown: markdown, comments: [] };
   }
 
-  // Detect reply relationships: Gilles immediately following Guy = reply
+  // Detect reply relationships based on adjacency
+  // First comment in a cluster = parent, all subsequent = replies to that parent
   // Comments are "adjacent" if there's only whitespace between them (< 50 chars)
   const ADJACENT_THRESHOLD = 50;
   const comments = [];
-  let lastGuyIdx = -1;
+  let clusterParentIdx = -1;  // Index of first comment in current cluster
   let lastCommentEnd = -1;
 
   for (let i = 0; i < rawMatches.length; i++) {
     const m = rawMatches[i];
-    const isGuy = m.author === 'Guy Colling';
-    const isGilles = m.author === 'Gilles Colling';
 
     // Check if this comment is adjacent to the previous one
     const gap = lastCommentEnd >= 0 ? m.start - lastCommentEnd : Infinity;
     const isAdjacent = gap < ADJACENT_THRESHOLD;
 
-    // Reset lastGuyIdx if there's a gap (comments not in same cluster)
+    // Reset cluster if there's a gap (comments not in same cluster)
     if (!isAdjacent) {
-      lastGuyIdx = -1;
+      clusterParentIdx = -1;
     }
 
-    if (isGuy) {
+    if (clusterParentIdx === -1) {
+      // First comment in cluster = parent (regardless of author)
       comments.push({
         ...m,
         isReply: false,
         parentIdx: null,
         commentIdx: comments.length
       });
-      lastGuyIdx = comments.length - 1;
-    } else if (isGilles && lastGuyIdx >= 0 && isAdjacent) {
-      // Gilles immediately following Guy (same cluster) = reply
-      comments.push({
-        ...m,
-        isReply: true,
-        parentIdx: lastGuyIdx,
-        commentIdx: comments.length
-      });
-      // Don't reset lastGuyIdx - multiple replies could follow
+      clusterParentIdx = comments.length - 1;
     } else {
-      // Standalone comment (not a reply)
+      // Subsequent comment in cluster = reply to first comment
       comments.push({
         ...m,
-        isReply: false,
-        parentIdx: null,
+        isReply: true,
+        parentIdx: clusterParentIdx,
         commentIdx: comments.length
       });
     }
@@ -122,6 +113,21 @@ export function prepareMarkdownWithMarkers(markdown) {
     lastCommentEnd = m.end;
   }
 
+  // Propagate anchors from replies to parents
+  // If a reply has an anchor but its parent doesn't, move the anchor to the parent
+  // Track flags for special handling during marker generation
+  for (const c of comments) {
+    if (c.isReply && c.anchor && c.parentIdx !== null) {
+      const parent = comments[c.parentIdx];
+      if (!parent.anchor) {
+        parent.anchor = c.anchor;
+        parent.anchorFromReply = true;  // Parent's anchor came from a reply (markers placed by reply)
+        c.placesParentMarkers = true;   // This reply should place the parent's markers
+        c.anchor = null;
+      }
+    }
+  }
+
   // Build marked markdown - only parent comments get markers
   // Process from end to start to preserve positions
   let markedMarkdown = markdown;
@@ -131,12 +137,57 @@ export function prepareMarkdownWithMarkers(markdown) {
 
     if (c.isReply) {
       // Reply: remove from document entirely (will be in comments.xml only)
-      markedMarkdown = markedMarkdown.slice(0, c.start) + markedMarkdown.slice(c.end);
+      // Also consume leading whitespace to avoid double spaces
+      let removeStart = c.start;
+      while (removeStart > 0 && /\s/.test(markedMarkdown[removeStart - 1])) {
+        removeStart--;
+      }
+
+      // If this reply places parent's markers (anchor was propagated)
+      if (c.placesParentMarkers && c.parentIdx !== null) {
+        // Extract anchor text from the original match
+        const anchorMatch = c.fullMatch.match(/\[([^\]]+)\]\{\.mark\}$/);
+        if (anchorMatch) {
+          const anchorText = anchorMatch[1];
+          // Output markers with PARENT's index around the anchor text
+          const parentIdx = c.parentIdx;
+          const replacement = `${MARKER_START_PREFIX}${parentIdx}${MARKER_SUFFIX}${anchorText}${MARKER_END_PREFIX}${parentIdx}${MARKER_SUFFIX}`;
+          markedMarkdown = markedMarkdown.slice(0, removeStart) + replacement + markedMarkdown.slice(c.end);
+        } else {
+          markedMarkdown = markedMarkdown.slice(0, removeStart) + markedMarkdown.slice(c.end);
+        }
+      } else {
+        markedMarkdown = markedMarkdown.slice(0, removeStart) + markedMarkdown.slice(c.end);
+      }
     } else {
-      // Parent comment: replace with markers
-      const anchor = c.anchor || '';
-      const replacement = `${MARKER_START_PREFIX}${i}${MARKER_SUFFIX}${anchor}${MARKER_END_PREFIX}${i}${MARKER_SUFFIX}`;
-      markedMarkdown = markedMarkdown.slice(0, c.start) + replacement + markedMarkdown.slice(c.end);
+      // Parent comment
+      if (c.anchorFromReply) {
+        // Anchor markers are placed by the reply, just remove this comment
+        let removeStart = c.start;
+        while (removeStart > 0 && /\s/.test(markedMarkdown[removeStart - 1])) {
+          removeStart--;
+        }
+        markedMarkdown = markedMarkdown.slice(0, removeStart) + markedMarkdown.slice(c.end);
+      } else {
+        // Normal case: replace with markers
+        let anchor = c.anchor || '';
+
+        // If no anchor, try to use the next word as fallback to avoid empty ranges
+        if (!anchor) {
+          const afterComment = markedMarkdown.slice(c.end);
+          // Match the next word (skip leading whitespace/punctuation)
+          const nextWordMatch = afterComment.match(/^\s*([a-zA-Z0-9]+)/);
+          if (nextWordMatch) {
+            anchor = nextWordMatch[1];
+            // Also need to consume the matched text from afterComment
+            c.consumeAfter = nextWordMatch[0].length;
+          }
+        }
+
+        const replacement = `${MARKER_START_PREFIX}${i}${MARKER_SUFFIX}${anchor}${MARKER_END_PREFIX}${i}${MARKER_SUFFIX}`;
+        const endPos = c.end + (c.consumeAfter || 0);
+        markedMarkdown = markedMarkdown.slice(0, c.start) + replacement + markedMarkdown.slice(endPos);
+      }
     }
   }
 
@@ -239,11 +290,7 @@ function createCommentsExtensibleXml(comments) {
   return xml;
 }
 
-// Known Windows Live user IDs for authors (from manual_comments.docx)
-const AUTHOR_USER_IDS = {
-  'Guy Colling': '9ff4d97962428673',
-  'Gilles Colling': '46e930a4c4b85dfd',
-};
+// Generate deterministic user IDs for authors (no hardcoded personal data)
 
 function createPeopleXml(comments) {
   // Extract unique authors
@@ -265,7 +312,7 @@ function createPeopleXml(comments) {
   xml += 'mc:Ignorable="w14 w15 w16se w16cid w16 w16cex w16sdtdh">';
 
   for (const author of authors) {
-    const userId = AUTHOR_USER_IDS[author] || generateUserId(author);
+    const userId = generateUserId(author);
     xml += `<w15:person w15:author="${escapeXml(author)}">`;
     xml += `<w15:presenceInfo w15:providerId="Windows Live" w15:userId="${userId}"/>`;
     xml += `</w15:person>`;
@@ -366,9 +413,14 @@ export async function injectCommentsAtMarkers(docxPath, comments, outputPath) {
       const endInText = fullText.indexOf(endMarker);
       if (startInText === -1 || endInText === -1) continue;
 
-      const textBefore = fullText.slice(0, startInText);
+      let textBefore = fullText.slice(0, startInText);
       const anchorText = fullText.slice(startInText + startMarker.length, endInText);
-      const textAfter = fullText.slice(endInText + endMarker.length);
+      let textAfter = fullText.slice(endInText + endMarker.length);
+
+      // When anchor is empty, normalize double spaces to single space
+      if (!anchorText && textBefore.endsWith(' ') && textAfter.startsWith(' ')) {
+        textAfter = textAfter.slice(1); // Remove leading space from textAfter
+      }
 
       // Build replacement
       let replacement = '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docrev",
-  "version": "0.6.7",
+  "version": "0.6.13",
   "description": "Academic paper revision workflow: Word ↔ Markdown round-trips, DOI validation, reviewer comments",
   "type": "module",
   "types": "types/index.d.ts",