docrev 0.7.8 → 0.8.0

package/lib/build.js

@@ -213,7 +213,7 @@ export function combineSections(directory, config, options = {}) {
   // Resolve forward references (refs that appear before their anchor definition)
   // This fixes pandoc-crossref limitation with multi-file documents
   if (hasPandocCrossref()) {
-    const registry = buildRegistry(directory);
+    const registry = buildRegistry(directory, sections);
     const { text, resolved } = resolveForwardRefs(paperContent, registry);
     if (resolved.length > 0) {
       paperContent = text;
@@ -280,7 +280,8 @@ export function prepareForFormat(paperPath, format, config, options = {}) {
   let content = fs.readFileSync(paperPath, 'utf-8');
 
   // Build crossref registry for reference conversion
-  const registry = buildRegistry(directory);
+  // Pass sections from config to ensure correct file ordering
+  const registry = buildRegistry(directory, config.sections);
 
   if (format === 'pdf' || format === 'tex') {
     // Strip all annotations for clean output

package/lib/commands/build.js

@@ -704,6 +704,21 @@ export function register(program, pkg) {
           }
         }
 
+        // Store base document for three-way merge (only for DOCX, not dual)
+        const docxResult = results.find(r => r.format === 'docx' && r.success);
+        if (docxResult && !options.dual) {
+          try {
+            const { storeBaseDocument } = await import('../merge.js');
+            storeBaseDocument(dir, docxResult.outputPath);
+            console.log(chalk.dim(`\n  Saved as .rev/base.docx for merge`));
+          } catch (err) {
+            // Non-fatal - just log if DEBUG
+            if (process.env.DEBUG) {
+              console.log(chalk.dim(`\n  Could not store base document: ${err.message}`));
+            }
+          }
+        }
+
         console.log(chalk.green('\nBuild complete!'));
       } catch (err) {
         spin.stop();

package/lib/commands/sections.js

@@ -727,26 +727,31 @@ export function register(program) {
     });
 
   // ==========================================================================
-  // MERGE command - Combine feedback from multiple reviewers
+  // MERGE command - Combine feedback from multiple reviewers (three-way merge)
   // ==========================================================================
 
   program
     .command('merge')
-    .description('Merge feedback from multiple Word documents')
-    .argument('<original>', 'Original markdown file')
+    .description('Merge feedback from multiple Word documents using three-way merge')
     .argument('<docx...>', 'Word documents from reviewers')
-    .option('-o, --output <file>', 'Output file (default: original-merged.md)')
+    .option('-b, --base <file>', 'Base document (original sent to reviewers). Auto-detected if not specified.')
+    .option('-o, --output <file>', 'Output file (default: writes to section files)')
     .option('--names <names>', 'Reviewer names (comma-separated, in order of docx files)')
-    .option('--auto', 'Auto-resolve conflicts by taking first change')
+    .option('--strategy <strategy>', 'Conflict resolution: first, latest, or interactive (default)', 'interactive')
+    .option('--diff-level <level>', 'Diff granularity: sentence or word (default: sentence)', 'sentence')
     .option('--dry-run', 'Show conflicts without writing')
-    .action(async (original, docxFiles, options) => {
-      const { mergeReviewerDocs, formatConflict, resolveConflict } = await import('../merge.js');
-
-      if (!fs.existsSync(original)) {
-        console.error(fmt.status('error', `Original file not found: ${original}`));
-        process.exit(1);
-      }
-
+    .option('--sections', 'Split merged output back to section files')
+    .action(async (docxFiles, options) => {
+      const {
+        mergeThreeWay,
+        formatConflict,
+        resolveConflict,
+        getBaseDocument,
+        checkBaseMatch,
+        saveConflicts,
+      } = await import('../merge.js');
+
+      // Validate reviewer files exist
       for (const docx of docxFiles) {
         if (!fs.existsSync(docx)) {
           console.error(fmt.status('error', `Reviewer file not found: ${docx}`));
@@ -754,14 +759,50 @@ export function register(program) {
         }
       }
 
+      // Determine base document
+      let basePath = options.base;
+      let baseSource = 'specified';
+
+      if (!basePath) {
+        // Try to use .rev/base.docx
+        const projectDir = process.cwd();
+        basePath = getBaseDocument(projectDir);
+
+        if (basePath) {
+          baseSource = 'auto (.rev/base.docx)';
+        } else {
+          console.log(chalk.yellow('\n  No base document found in .rev/base.docx'));
+          console.log(chalk.dim('  Tip: Run "rev build docx" to automatically save the base document.\n'));
+          console.error(fmt.status('error', 'Base document required. Use --base <file.docx>'));
+          process.exit(1);
+        }
+      }
+
+      if (!fs.existsSync(basePath)) {
+        console.error(fmt.status('error', `Base document not found: ${basePath}`));
+        process.exit(1);
+      }
+
+      // Check similarity between base and reviewer docs
+      const { matches, similarity } = await checkBaseMatch(basePath, docxFiles[0]);
+      if (!matches) {
+        console.log(chalk.yellow(`\n  Warning: Base document may not match reviewer file (${Math.round(similarity * 100)}% similar)`));
+        console.log(chalk.dim('  If this is wrong, use --base to specify the correct original document.\n'));
+      }
+
+      // Parse reviewer names
       const names = options.names
         ? options.names.split(',').map(n => n.trim())
-        : docxFiles.map((f, i) => `Reviewer ${i + 1}`);
+        : docxFiles.map((f, i) => {
+          // Try to extract name from filename (e.g., paper_reviewer_A.docx)
+          const basename = path.basename(f, '.docx');
+          const match = basename.match(/_([A-Za-z]+)$/);
+          return match ? match[1] : `Reviewer ${i + 1}`;
+        });
 
-      if (names.length < docxFiles.length) {
-        for (let i = names.length; i < docxFiles.length; i++) {
-          names.push(`Reviewer ${i + 1}`);
-        }
+      // Pad names if needed
+      while (names.length < docxFiles.length) {
+        names.push(`Reviewer ${names.length + 1}`);
       }
 
       const reviewerDocs = docxFiles.map((p, i) => ({
@@ -769,21 +810,23 @@ export function register(program) {
         name: names[i],
       }));
 
-      console.log(fmt.header('Multi-Reviewer Merge'));
+      console.log(fmt.header('Three-Way Merge'));
       console.log();
-      console.log(chalk.dim(`  Original: ${original}`));
+      console.log(chalk.dim(`  Base: ${path.basename(basePath)} (${baseSource})`));
       console.log(chalk.dim(`  Reviewers: ${names.join(', ')}`));
+      console.log(chalk.dim(`  Diff level: ${options.diffLevel}`));
       console.log();
 
       const spin = fmt.spinner('Analyzing changes...').start();
 
       try {
-        const { merged, conflicts, stats, originalText } = await mergeReviewerDocs(original, reviewerDocs, {
-          autoResolve: options.auto,
+        const { merged, conflicts, stats, baseText } = await mergeThreeWay(basePath, reviewerDocs, {
+          diffLevel: options.diffLevel,
         });
 
         spin.stop();
 
+        // Display stats
         console.log(fmt.table(['Metric', 'Count'], [
           ['Total changes', stats.totalChanges.toString()],
           ['Non-conflicting', stats.nonConflicting.toString()],
@@ -792,21 +835,33 @@ export function register(program) {
         ]));
         console.log();
 
+        let finalMerged = merged;
+
+        // Handle conflicts
         if (conflicts.length > 0) {
           console.log(chalk.yellow(`Found ${conflicts.length} conflict(s):\n`));
 
-          let resolvedMerged = merged;
-
-          for (let i = 0; i < conflicts.length; i++) {
-            const conflict = conflicts[i];
-            console.log(chalk.bold(`Conflict ${i + 1}/${conflicts.length}:`));
-            console.log(formatConflict(conflict, originalText));
-            console.log();
+          if (options.strategy === 'first') {
+            // Auto-resolve: take first reviewer's change
+            for (const conflict of conflicts) {
+              console.log(chalk.dim(`  Conflict ${conflict.id}: using ${conflict.changes[0].reviewer}'s change`));
+              resolveConflict(conflict, 0);
+            }
+          } else if (options.strategy === 'latest') {
+            // Auto-resolve: take last reviewer's change
+            for (const conflict of conflicts) {
+              const lastIdx = conflict.changes.length - 1;
+              console.log(chalk.dim(`  Conflict ${conflict.id}: using ${conflict.changes[lastIdx].reviewer}'s change`));
+              resolveConflict(conflict, lastIdx);
+            }
+          } else if (!options.dryRun) {
+            // Interactive resolution
+            for (let i = 0; i < conflicts.length; i++) {
+              const conflict = conflicts[i];
+              console.log(chalk.bold(`\nConflict ${i + 1}/${conflicts.length} (${conflict.id}):`));
+              console.log(formatConflict(conflict, baseText));
+              console.log();
 
-            if (options.auto) {
-              console.log(chalk.dim(`  Auto-resolved: using ${conflict.changes[0].reviewer}'s change`));
-              resolvedMerged = resolveConflict(resolvedMerged, conflict, 0, originalText);
-            } else if (!options.dryRun) {
               const rl = await import('readline');
               const readline = rl.createInterface({
                 input: process.stdin,
@@ -821,36 +876,50 @@ export function register(program) {
               if (answer.toLowerCase() !== 's' && !isNaN(parseInt(answer))) {
                 const choice = parseInt(answer) - 1;
                 if (choice >= 0 && choice < conflict.changes.length) {
-                  resolvedMerged = resolveConflict(resolvedMerged, conflict, choice, originalText);
-                  console.log(chalk.green(`  Applied: ${conflict.changes[choice].reviewer}'s change`));
+                  resolveConflict(conflict, choice);
+                  console.log(chalk.green(`  ✓ Applied: ${conflict.changes[choice].reviewer}'s change`));
                 }
               } else {
-                console.log(chalk.dim('  Skipped'));
+                console.log(chalk.dim('  Skipped (will need manual resolution)'));
               }
-              console.log();
             }
           }
 
-          if (!options.dryRun) {
-            const outPath = options.output || original.replace(/\.md$/, '-merged.md');
-            fs.writeFileSync(outPath, resolvedMerged, 'utf-8');
-            console.log(fmt.status('success', `Merged output written to ${outPath}`));
+          // Save unresolved conflicts for later
+          const unresolved = conflicts.filter(c => c.resolved === null);
+          if (unresolved.length > 0) {
+            saveConflicts(process.cwd(), conflicts, basePath);
+            console.log(chalk.yellow(`\n  ${unresolved.length} unresolved conflict(s) saved to .rev/conflicts.json`));
+            console.log(chalk.dim('  Run "rev conflicts" to view, "rev merge-resolve" to resolve'));
           }
-        } else {
-          if (!options.dryRun) {
-            const outPath = options.output || original.replace(/\.md$/, '-merged.md');
-            fs.writeFileSync(outPath, merged, 'utf-8');
-            console.log(fmt.status('success', `Merged output written to ${outPath}`));
+        }
+
+        // Write output
+        if (!options.dryRun) {
+          if (options.output) {
+            // Write to single file
+            fs.writeFileSync(options.output, finalMerged, 'utf-8');
+            console.log(fmt.status('success', `Merged output written to ${options.output}`));
+          } else if (options.sections) {
+            // Split to section files (TODO: implement section splitting)
+            console.log(chalk.yellow('  Section splitting not yet implemented'));
+            console.log(chalk.dim('  Use -o to specify output file'));
           } else {
-            console.log(fmt.status('info', 'Dry run - no output written'));
+            // Default: write to merged.md
+            const outPath = 'merged.md';
+            fs.writeFileSync(outPath, finalMerged, 'utf-8');
+            console.log(fmt.status('success', `Merged output written to ${outPath}`));
           }
-        }
 
-        if (!options.dryRun && stats.nonConflicting > 0) {
           console.log();
           console.log(chalk.dim('Next steps:'));
-          console.log(chalk.dim('  1. rev review <merged.md>  - Review all changes'));
-          console.log(chalk.dim('  2. rev comments <merged.md> - Address comments'));
+          console.log(chalk.dim('  1. rev review merged.md     - Accept/reject changes'));
+          console.log(chalk.dim('  2. rev comments merged.md   - Address comments'));
+          if (conflicts.some(c => c.resolved === null)) {
+            console.log(chalk.dim('  3. rev merge-resolve        - Resolve remaining conflicts'));
+          }
+        } else {
+          console.log(fmt.status('info', 'Dry run - no output written'));
         }
       } catch (err) {
         spin.stop();
@@ -859,4 +928,151 @@ export function register(program) {
         process.exit(1);
       }
     });
+
+  // ==========================================================================
+  // CONFLICTS command - List unresolved conflicts
+  // ==========================================================================
+
+  program
+    .command('conflicts')
+    .description('List unresolved merge conflicts')
+    .action(async () => {
+      const { loadConflicts, formatConflict } = await import('../merge.js');
+      const projectDir = process.cwd();
+      const data = loadConflicts(projectDir);
+
+      if (!data) {
+        console.log(fmt.status('info', 'No conflicts file found'));
+        return;
+      }
+
+      const unresolved = data.conflicts.filter(c => c.resolved === null);
+
+      if (unresolved.length === 0) {
+        console.log(fmt.status('success', 'All conflicts resolved!'));
+        return;
+      }
+
+      console.log(fmt.header(`Unresolved Conflicts (${unresolved.length})`));
+      console.log();
+      console.log(chalk.dim(`  Base: ${data.base}`));
+      console.log(chalk.dim(`  Merged: ${data.merged}`));
+      console.log();
+
+      for (const conflict of unresolved) {
+        console.log(chalk.bold(`Conflict ${conflict.id}:`));
+        // Show abbreviated info
+        console.log(chalk.dim(`  Original: "${conflict.original.slice(0, 50)}${conflict.original.length > 50 ? '...' : ''}"`));
+        console.log(chalk.dim(`  Options: ${conflict.changes.map(c => c.reviewer).join(', ')}`));
+        console.log();
+      }
+
+      console.log(chalk.dim('Run "rev merge-resolve" to resolve conflicts interactively'));
+    });
+
+  // ==========================================================================
+  // MERGE-RESOLVE command - Interactively resolve merge conflicts
+  // ==========================================================================
+
+  program
+    .command('merge-resolve')
+    .alias('mresolve')
+    .description('Resolve merge conflicts interactively')
+    .option('--theirs', 'Accept all changes from last reviewer')
+    .option('--ours', 'Accept all changes from first reviewer')
+    .action(async (options) => {
+      const { loadConflicts, saveConflicts, clearConflicts, resolveConflict, formatConflict } = await import('../merge.js');
+      const projectDir = process.cwd();
+      const data = loadConflicts(projectDir);
+
+      if (!data) {
+        console.log(fmt.status('info', 'No conflicts to resolve'));
+        return;
+      }
+
+      const unresolved = data.conflicts.filter(c => c.resolved === null);
+
+      if (unresolved.length === 0) {
+        console.log(fmt.status('success', 'All conflicts already resolved!'));
+        clearConflicts(projectDir);
+        return;
+      }
+
+      console.log(fmt.header(`Resolving ${unresolved.length} Conflict(s)`));
+      console.log();
+
+      if (options.theirs) {
+        // Accept all from last reviewer
+        for (const conflict of unresolved) {
+          const lastIdx = conflict.changes.length - 1;
+          resolveConflict(conflict, lastIdx);
+          console.log(chalk.dim(`  ${conflict.id}: accepted ${conflict.changes[lastIdx].reviewer}'s change`));
+        }
+        saveConflicts(projectDir, data.conflicts, data.base);
+        console.log(fmt.status('success', `Resolved ${unresolved.length} conflicts (--theirs)`));
+      } else if (options.ours) {
+        // Accept all from first reviewer
+        for (const conflict of unresolved) {
+          resolveConflict(conflict, 0);
+          console.log(chalk.dim(`  ${conflict.id}: accepted ${conflict.changes[0].reviewer}'s change`));
+        }
+        saveConflicts(projectDir, data.conflicts, data.base);
+        console.log(fmt.status('success', `Resolved ${unresolved.length} conflicts (--ours)`));
+      } else {
+        // Interactive resolution
+        // Read base text for context display
+        let baseText = '';
+        try {
+          const { extractFromWord } = await import('../import.js');
+          const { text } = await extractFromWord(data.base);
+          baseText = text;
+        } catch {
+          // Can't read base, show without context
+        }
+
+        for (let i = 0; i < unresolved.length; i++) {
+          const conflict = unresolved[i];
+          console.log(chalk.bold(`\nConflict ${i + 1}/${unresolved.length} (${conflict.id}):`));
+          console.log(formatConflict(conflict, baseText));
+          console.log();
+
+          const rl = await import('readline');
+          const readline = rl.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+          });
+
+          const answer = await new Promise((resolve) =>
+            readline.question(chalk.cyan(`  Choose (1-${conflict.changes.length}, s=skip, q=quit): `), resolve)
+          );
+          readline.close();
+
+          if (answer.toLowerCase() === 'q') {
+            console.log(chalk.dim('\n  Saving progress...'));
+            break;
+          }
+
+          if (answer.toLowerCase() !== 's' && !isNaN(parseInt(answer))) {
+            const choice = parseInt(answer) - 1;
+            if (choice >= 0 && choice < conflict.changes.length) {
+              resolveConflict(conflict, choice);
+              console.log(chalk.green(`  ✓ Applied: ${conflict.changes[choice].reviewer}'s change`));
+            }
+          } else {
+            console.log(chalk.dim('  Skipped'));
+          }
+        }
+
+        saveConflicts(projectDir, data.conflicts, data.base);
+
+        const remaining = data.conflicts.filter(c => c.resolved === null).length;
+        if (remaining === 0) {
+          console.log(fmt.status('success', '\nAll conflicts resolved!'));
+          clearConflicts(projectDir);
+        } else {
+          console.log(chalk.yellow(`\n  ${remaining} conflict(s) remaining`));
+        }
+      }
+    });
+
 }

package/lib/crossref.js

@@ -11,6 +11,49 @@ import * as fs from 'fs';
 import * as path from 'path';
 import YAML from 'yaml';
 
+/**
+ * Discover section files from a directory by reading config files
+ * Only returns files explicitly defined in rev.yaml or sections.yaml
+ * Returns empty array if no config found (caller should handle this)
+ *
+ * @param {string} directory
+ * @returns {string[]} Ordered list of section filenames, or empty if no config
+ */
+function discoverSectionFiles(directory) {
+  // Try rev.yaml first
+  const revYamlPath = path.join(directory, 'rev.yaml');
+  if (fs.existsSync(revYamlPath)) {
+    try {
+      const config = YAML.parse(fs.readFileSync(revYamlPath, 'utf-8'));
+      if (config.sections && Array.isArray(config.sections) && config.sections.length > 0) {
+        return config.sections.filter(f => fs.existsSync(path.join(directory, f)));
+      }
+    } catch {
+      // Ignore yaml errors, try next option
+    }
+  }
+
+  // Try sections.yaml
+  const sectionsPath = path.join(directory, 'sections.yaml');
+  if (fs.existsSync(sectionsPath)) {
+    try {
+      const config = YAML.parse(fs.readFileSync(sectionsPath, 'utf-8'));
+      if (config.sections) {
+        const sectionOrder = Object.entries(config.sections)
+          .sort((a, b) => (a[1].order ?? 999) - (b[1].order ?? 999))
+          .map(([file]) => file);
+        return sectionOrder.filter(f => fs.existsSync(path.join(directory, f)));
+      }
+    } catch {
+      // Ignore yaml errors
+    }
+  }
+
+  // No config found - return empty array
+  // Caller must handle this (either error or use explicit sections)
+  return [];
+}
+
 /**
  * Patterns for detecting hardcoded references
  * Matches complex patterns including:
@@ -208,8 +251,14 @@ export function parseReferenceList(listStr) {
  * Build a registry of figure/table labels from .md files
  * Scans for {#fig:label} and {#tbl:label} anchors
  *
+ * IMPORTANT: This function requires either explicit sections or a rev.yaml/sections.yaml config.
+ * It will NOT guess by scanning all .md files, as this leads to incorrect numbering
+ * when temporary files (paper_clean.md, etc.) exist in the directory.
+ *
  * @param {string} directory - Directory containing .md files
- * @param {string[]} [excludeFiles] - Files to exclude
+ * @param {string[]} [sections] - Array of section filenames to scan (recommended).
+ *   If not provided, reads from rev.yaml or sections.yaml.
+ *   Returns empty registry if no sections can be determined.
  * @returns {{
  *   figures: Map<string, {label: string, num: number, isSupp: boolean, file: string}>,
  *   tables: Map<string, {label: string, num: number, isSupp: boolean, file: string}>,
@@ -217,7 +266,7 @@ export function parseReferenceList(listStr) {
  *   byNumber: {fig: Map<string, string>, tbl: Map<string, string>, eq: Map<string, string>}
  * }}
  */
-export function buildRegistry(directory, excludeFiles = ['paper.md', 'README.md', 'CLAUDE.md']) {
+export function buildRegistry(directory, sections) {
   const figures = new Map();
   const tables = new Map();
   const equations = new Map();
@@ -229,32 +278,16 @@ export function buildRegistry(directory, excludeFiles = ['paper.md', 'README.md'
   let tblSuppNum = 0;
   let eqNum = 0;
 
-  // Get all .md files
-  const files = fs.readdirSync(directory).filter((f) => {
-    if (!f.endsWith('.md')) return false;
-    if (excludeFiles.some((e) => f.toLowerCase() === e.toLowerCase())) return false;
-    return true;
-  });
+  let orderedFiles;
 
-  // Sort by likely document order (use sections.yaml if available)
-  let orderedFiles = files;
-  const sectionsPath = path.join(directory, 'sections.yaml');
-  if (fs.existsSync(sectionsPath)) {
-    try {
-      const config = YAML.parse(fs.readFileSync(sectionsPath, 'utf-8'));
-      if (config.sections) {
-        const sectionOrder = Object.entries(config.sections)
-          .sort((a, b) => (a[1].order ?? 999) - (b[1].order ?? 999))
-          .map(([file]) => file);
-        orderedFiles = sectionOrder.filter((f) => files.includes(f));
-        // Add any remaining files not in sections.yaml
-        for (const f of files) {
-          if (!orderedFiles.includes(f)) orderedFiles.push(f);
-        }
-      }
-    } catch {
-      // Ignore yaml errors, use default order
-    }
+  if (Array.isArray(sections) && sections.length > 0) {
+    // Use explicitly provided section files - most reliable
+    orderedFiles = sections.filter(f => fs.existsSync(path.join(directory, f)));
+  } else {
+    // Try to determine sections from config files (rev.yaml or sections.yaml)
+    orderedFiles = discoverSectionFiles(directory);
+    // If no config found, return empty registry rather than guessing
+    // This prevents bugs from scanning wrong files
   }
 
   // Determine if a file is supplementary

package/lib/merge.js

@@ -1,13 +1,21 @@
 /**
  * Multi-reviewer merge utilities
  * Combine feedback from multiple Word documents with conflict detection
+ *
+ * Supports true three-way merge: base document + multiple reviewer versions
  */
 
 import * as fs from 'fs';
 import * as path from 'path';
-import { diffWords } from 'diff';
+import * as crypto from 'crypto';
+import { diffWords, diffSentences } from 'diff';
 import { extractFromWord, extractWordComments } from './import.js';
 
+// Single base document for three-way merge
+const REV_DIR = '.rev';
+const BASE_FILE = '.rev/base.docx';
+const CONFLICTS_FILE = '.rev/conflicts.json';
+
 /**
  * Represents a change from a reviewer
  * @typedef {Object} ReviewerChange
@@ -17,27 +25,111 @@ import { extractFromWord, extractWordComments } from './import.js';
  * @property {number} end - End position in original text
  * @property {string} oldText - Original text (for delete/replace)
  * @property {string} newText - New text (for insert/replace)
+ * @property {string} [date] - Date of change (from Word track changes)
  */
 
 /**
  * Represents a conflict between reviewers
  * @typedef {Object} Conflict
+ * @property {string} id - Unique conflict ID
  * @property {number} start - Start position in original
  * @property {number} end - End position in original
  * @property {string} original - Original text
  * @property {ReviewerChange[]} changes - Conflicting changes from different reviewers
+ * @property {string} [section] - Section file this conflict belongs to
+ * @property {number} [line] - Line number in section
+ * @property {string|null} resolved - Resolution choice or null if unresolved
+ */
+
+/**
+ * Initialize .rev directory
+ * @param {string} projectDir
+ */
+export function initRevDir(projectDir) {
+  const revDir = path.join(projectDir, REV_DIR);
+  if (!fs.existsSync(revDir)) {
+    fs.mkdirSync(revDir, { recursive: true });
+  }
+}
+
+/**
+ * Store the base document for three-way merge
+ * Overwrites any previous base document
+ * @param {string} projectDir
+ * @param {string} docxPath - Path to the built docx
  */
+export function storeBaseDocument(projectDir, docxPath) {
+  initRevDir(projectDir);
+  const basePath = path.join(projectDir, BASE_FILE);
+  fs.copyFileSync(docxPath, basePath);
+}
+
+/**
+ * Get the base document path if it exists
+ * @param {string} projectDir
+ * @returns {string|null}
+ */
+export function getBaseDocument(projectDir) {
+  const basePath = path.join(projectDir, BASE_FILE);
+  if (fs.existsSync(basePath)) {
+    return basePath;
+  }
+  return null;
+}
+
+/**
+ * Check if base document exists
+ * @param {string} projectDir
+ * @returns {boolean}
+ */
+export function hasBaseDocument(projectDir) {
+  return fs.existsSync(path.join(projectDir, BASE_FILE));
+}
+
+/**
+ * Compute text similarity between two strings
+ * @param {string} text1
+ * @param {string} text2
+ * @returns {number} Similarity score 0-1
+ */
+export function computeSimilarity(text1, text2) {
+  const words1 = new Set(text1.toLowerCase().split(/\s+/).filter(w => w.length > 2));
+  const words2 = text2.toLowerCase().split(/\s+/).filter(w => w.length > 2);
+  if (words1.size === 0 || words2.length === 0) return 0;
+  const common = words2.filter(w => words1.has(w)).length;
+  return common / Math.max(words1.size, words2.length);
+}
+
+/**
+ * Check if base document matches reviewer document (similarity check)
+ * @param {string} basePath
+ * @param {string} reviewerPath
+ * @returns {Promise<{matches: boolean, similarity: number}>}
+ */
+export async function checkBaseMatch(basePath, reviewerPath) {
+  try {
+    const { text: baseText } = await extractFromWord(basePath);
+    const { text: reviewerText } = await extractFromWord(reviewerPath);
+    const similarity = computeSimilarity(baseText, reviewerText);
+    return { matches: similarity > 0.5, similarity };
+  } catch {
+    return { matches: false, similarity: 0 };
+  }
+}
 
 /**
  * Extract changes from a Word document compared to original
- * @param {string} originalText - Original markdown text
- * @param {string} wordText - Text extracted from Word
+ * Uses sentence-level diffing for better conflict detection
+ * @param {string} originalText - Original text (from base document)
+ * @param {string} wordText - Text extracted from reviewer's Word doc
  * @param {string} reviewer - Reviewer identifier
  * @returns {ReviewerChange[]}
  */
 export function extractChanges(originalText, wordText, reviewer) {
   const changes = [];
-  const diffs = diffWords(originalText, wordText);
+
+  // Use sentence-level diff for better granularity
+  const diffs = diffSentences(originalText, wordText);
 
   let originalPos = 0;
   let i = 0;
@@ -90,6 +182,64 @@ export function extractChanges(originalText, wordText, reviewer) {
   return changes;
 }
 
+/**
+ * Extract changes using word-level diff (more fine-grained)
+ * @param {string} originalText
+ * @param {string} wordText
+ * @param {string} reviewer
+ * @returns {ReviewerChange[]}
+ */
+export function extractChangesWordLevel(originalText, wordText, reviewer) {
+  const changes = [];
+  const diffs = diffWords(originalText, wordText);
+
+  let originalPos = 0;
+  let i = 0;
+
+  while (i < diffs.length) {
+    const part = diffs[i];
+
+    if (!part.added && !part.removed) {
+      originalPos += part.value.length;
+      i++;
+    } else if (part.removed && diffs[i + 1]?.added) {
+      changes.push({
+        reviewer,
+        type: 'replace',
+        start: originalPos,
+        end: originalPos + part.value.length,
+        oldText: part.value,
+        newText: diffs[i + 1].value,
+      });
+      originalPos += part.value.length;
+      i += 2;
+    } else if (part.removed) {
+      changes.push({
+        reviewer,
+        type: 'delete',
+        start: originalPos,
+        end: originalPos + part.value.length,
+        oldText: part.value,
+        newText: '',
+      });
+      originalPos += part.value.length;
+      i++;
+    } else if (part.added) {
+      changes.push({
+        reviewer,
+        type: 'insert',
+        start: originalPos,
+        end: originalPos,
+        oldText: '',
+        newText: part.value,
+      });
+      i++;
+    }
+  }
+
+  return changes;
+}
+
 /**
  * Check if two changes overlap
  * @param {ReviewerChange} a
@@ -134,6 +284,7 @@ export function detectConflicts(allChanges) {
   const conflicts = [];
   const nonConflicting = [];
   const usedIndices = new Set();
+  let conflictId = 0;
 
   for (let i = 0; i < flat.length; i++) {
     if (usedIndices.has(i)) continue;
@@ -162,10 +313,12 @@ export function detectConflicts(allChanges) {
       const end = Math.max(...conflictingChanges.map(c => c.end));
 
       conflicts.push({
+        id: `c${++conflictId}`,
         start,
         end,
         original: conflictingChanges[0].oldText || '',
         changes: conflictingChanges,
+        resolved: null,
       });
       usedIndices.add(i);
     } else {
@@ -227,8 +380,6 @@ export function applyChangesAsAnnotations(originalText, changes) {
   let result = originalText;
 
   for (const change of sorted) {
-    const reviewer = change.reviewer;
-
     if (change.type === 'insert') {
       const annotation = `{++${change.newText}++}`;
       result = result.slice(0, change.start) + annotation + result.slice(change.start);
@@ -244,6 +395,42 @@ export function applyChangesAsAnnotations(originalText, changes) {
   return result;
 }
 
+/**
+ * Apply changes as git-style conflict markers
+ * @param {string} originalText
+ * @param {Conflict[]} conflicts
+ * @returns {string}
+ */
+export function applyConflictMarkers(originalText, conflicts) {
+  // Sort by position descending
+  const sorted = [...conflicts].sort((a, b) => b.start - a.start);
+
+  let result = originalText;
+
+  for (const conflict of sorted) {
+    const markers = [];
+    markers.push(`<<<<<<< CONFLICT ${conflict.id}`);
+
+    for (const change of conflict.changes) {
+      markers.push(`======= ${change.reviewer}`);
+      if (change.type === 'delete') {
+        markers.push(`[DELETED: "${change.oldText}"]`);
+      } else if (change.type === 'insert') {
+        markers.push(change.newText);
+      } else {
+        markers.push(change.newText);
+      }
+    }
+
+    markers.push(`>>>>>>> END ${conflict.id}`);
+
+    const markerText = markers.join('\n');
+    result = result.slice(0, conflict.start) + markerText + result.slice(conflict.end);
+  }
+
+  return result;
+}
+
 /**
  * Format a conflict for display
  * @param {Conflict} conflict
@@ -252,35 +439,154 @@ export function applyChangesAsAnnotations(originalText, changes) {
  */
 export function formatConflict(conflict, originalText) {
   const lines = [];
-  const context = 30;
+  const context = 50;
 
   // Show context
   const beforeStart = Math.max(0, conflict.start - context);
   const afterEnd = Math.min(originalText.length, conflict.end + context);
 
-  const before = originalText.slice(beforeStart, conflict.start);
+  const before = originalText.slice(beforeStart, conflict.start).trim();
   const original = originalText.slice(conflict.start, conflict.end);
-  const after = originalText.slice(conflict.end, afterEnd);
+  const after = originalText.slice(conflict.end, afterEnd).trim();
 
-  lines.push(`Context: ...${before}[CONFLICT]${after}...`);
-  lines.push(`Original: "${original || '(insertion point)'}"`);
+  if (before) {
+    lines.push(`  ...${before}`);
+  }
+  lines.push(`  [ORIGINAL]: "${original || '(insertion point)'}"`);
+  if (after) {
+    lines.push(`  ${after}...`);
+  }
   lines.push('');
-  lines.push('Options:');
+  lines.push('  Options:');
 
   conflict.changes.forEach((change, i) => {
     const label = change.type === 'insert'
-      ? `Insert: "${change.newText}"`
+      ? `Insert: "${change.newText.slice(0, 60)}${change.newText.length > 60 ? '...' : ''}"`
       : change.type === 'delete'
-        ? `Delete: "${change.oldText}"`
-        : `Replace "${change.oldText}" → "${change.newText}"`;
-    lines.push(`  ${i + 1}. [${change.reviewer}] ${label}`);
+        ? `Delete: "${change.oldText.slice(0, 60)}${change.oldText.length > 60 ? '...' : ''}"`
+        : `Replace → "${change.newText.slice(0, 60)}${change.newText.length > 60 ? '...' : ''}"`;
+    lines.push(`    ${i + 1}. [${change.reviewer}] ${label}`);
   });
 
   return lines.join('\n');
 }
 
 /**
- * Merge multiple Word documents against an original
+ * Save conflicts to file for later resolution
+ * @param {string} projectDir
+ * @param {Conflict[]} conflicts
+ * @param {string} baseDoc - Base document path
+ */
+export function saveConflicts(projectDir, conflicts, baseDoc) {
+  const conflictsPath = path.join(projectDir, CONFLICTS_FILE);
+  const data = {
+    base: baseDoc,
+    merged: new Date().toISOString(),
+    conflicts,
+  };
+
+  // Ensure directory exists
+  const dir = path.dirname(conflictsPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  fs.writeFileSync(conflictsPath, JSON.stringify(data, null, 2));
+}
+
+/**
+ * Load conflicts from file
+ * @param {string} projectDir
+ * @returns {{base: string, merged: string, conflicts: Conflict[]}|null}
+ */
+export function loadConflicts(projectDir) {
+  const conflictsPath = path.join(projectDir, CONFLICTS_FILE);
+  if (!fs.existsSync(conflictsPath)) {
+    return null;
+  }
+  return JSON.parse(fs.readFileSync(conflictsPath, 'utf-8'));
+}
+
+/**
+ * Clear conflicts file after resolution
+ * @param {string} projectDir
+ */
+export function clearConflicts(projectDir) {
+  const conflictsPath = path.join(projectDir, CONFLICTS_FILE);
+  if (fs.existsSync(conflictsPath)) {
+    fs.unlinkSync(conflictsPath);
+  }
+}
+
+/**
+ * Merge multiple Word documents using three-way merge
+ * @param {string} basePath - Path to base document (original sent to reviewers)
+ * @param {Array<{path: string, name: string}>} reviewerDocs - Reviewer Word docs
+ * @param {Object} options
+ * @returns {Promise<{merged: string, conflicts: Conflict[], stats: Object, baseText: string}>}
+ */
+export async function mergeThreeWay(basePath, reviewerDocs, options = {}) {
+  const { diffLevel = 'sentence' } = options;
+
+  if (!fs.existsSync(basePath)) {
+    throw new Error(`Base document not found: ${basePath}`);
+  }
+
+  // Extract text from base document
+  const { text: baseText } = await extractFromWord(basePath);
+
+  // Extract changes from each reviewer relative to base
+  const allChanges = [];
+  const allComments = [];
+
+  for (const doc of reviewerDocs) {
+    if (!fs.existsSync(doc.path)) {
+      throw new Error(`Reviewer file not found: ${doc.path}`);
+    }
+
+    const { text: wordText } = await extractFromWord(doc.path);
+
+    // Choose diff level
+    const changes = diffLevel === 'word'
+      ? extractChangesWordLevel(baseText, wordText, doc.name)
+      : extractChanges(baseText, wordText, doc.name);
+
+    allChanges.push(changes);
+
+    // Also extract comments
+    try {
+      const comments = await extractWordComments(doc.path);
+      allComments.push(...comments.map(c => ({ ...c, reviewer: doc.name })));
+    } catch {
+      // Comments extraction failed, continue without
+    }
+  }
+
+  // Detect conflicts
+  const { conflicts, nonConflicting } = detectConflicts(allChanges);
+
+  // Apply non-conflicting changes as annotations
+  let merged = applyChangesAsAnnotations(baseText, nonConflicting);
+
+  // Add comments with reviewer attribution
+  for (const comment of allComments) {
+    merged += `\n{>>${comment.reviewer}: ${comment.text}<<}`;
+  }
+
+  const stats = {
+    reviewers: reviewerDocs.length,
+    totalChanges: allChanges.flat().length,
+    nonConflicting: nonConflicting.length,
+    conflicts: conflicts.length,
+    comments: allComments.length,
+  };
+
+  return { merged, conflicts, stats, baseText };
+}
+
+/**
+ * Merge multiple Word documents against an original markdown file
+ * Legacy function - use mergeThreeWay for proper three-way merge
  * @param {string} originalPath - Path to original markdown
  * @param {Array<{path: string, name: string}>} reviewerDocs - Reviewer Word docs
  * @param {Object} options
@@ -342,24 +648,26 @@ export async function mergeReviewerDocs(originalPath, reviewerDocs, options = {}
 
 /**
  * Resolve a conflict by choosing one option
- * @param {string} text - Current merged text
  * @param {Conflict} conflict
  * @param {number} choice - Index of chosen change (0-based)
- * @param {string} originalText - Original text for position reference
- * @returns {string}
+ * @returns {ReviewerChange}
  */
-export function resolveConflict(text, conflict, choice, originalText) {
-  const chosen = conflict.changes[choice];
-
-  // Find the conflict region in the current text
-  // This is simplified - real implementation would track positions
-  const annotation = chosen.type === 'insert'
-    ? `{++${chosen.newText}++}`
-    : chosen.type === 'delete'
-      ? `{--${chosen.oldText}--}`
-      : `{~~${chosen.oldText}~>${chosen.newText}~~}`;
-
-  // For now, append resolved conflicts at marker position
-  // A more sophisticated approach would track exact positions
-  return text + `\n<!-- Resolved: ${annotation} -->`;
+export function resolveConflict(conflict, choice) {
+  if (choice < 0 || choice >= conflict.changes.length) {
+    throw new Error(`Invalid choice: ${choice}. Must be 0-${conflict.changes.length - 1}`);
+  }
+  conflict.resolved = conflict.changes[choice].reviewer;
+  return conflict.changes[choice];
 }
+
+/**
+ * Get list of unresolved conflicts
+ * @param {string} projectDir
+ * @returns {Conflict[]}
+ */
+export function getUnresolvedConflicts(projectDir) {
+  const data = loadConflicts(projectDir);
+  if (!data) return [];
+  return data.conflicts.filter(c => c.resolved === null);
+}
+

package/package.json

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