docrev 0.8.1 → 0.8.5

package/lib/{merge.js → merge.ts}

@@ -10,42 +10,79 @@ import * as path from 'path';
 import * as crypto from 'crypto';
 import { diffWords, diffSentences } from 'diff';
 import { extractFromWord, extractWordComments } from './import.js';
+import type { ReviewerChange, Conflict, MergeResult } from './types.js';
 
-// Single base document for three-way merge
+// =============================================================================
+// Constants
+// =============================================================================
+
+/** Directory for revision tracking data */
 const REV_DIR = '.rev';
+
+/** Path to base document for three-way merge */
 const BASE_FILE = '.rev/base.docx';
+
+/** Path to conflict resolution state */
 const CONFLICTS_FILE = '.rev/conflicts.json';
 
-/**
- * Represents a change from a reviewer
- * @typedef {Object} ReviewerChange
- * @property {string} reviewer - Reviewer name/identifier
- * @property {string} type - 'insert' | 'delete' | 'replace'
- * @property {number} start - Start position in original text
- * @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)
- */
+/** Minimum word length for similarity calculations */
+const MIN_WORD_LENGTH = 2;
 
-/**
- * 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
- */
+/** Similarity threshold below which changes are considered conflicts */
+const CONFLICT_SIMILARITY_THRESHOLD = 0.8;
+
+/** Characters of context for change attribution */
+const CHANGE_CONTEXT_SIZE = 50;
+
+// =============================================================================
+// Interfaces
+// =============================================================================
+
+interface ReviewerDoc {
+  path: string;
+  name: string;
+}
+
+interface ReviewerComment {
+  text: string;
+  reviewer: string;
+}
+
+interface MergeOptions {
+  diffLevel?: 'sentence' | 'word';
+  autoResolve?: boolean;
+}
+
+interface CheckMatchResult {
+  matches: boolean;
+  similarity: number;
+}
+
+interface ConflictDetectionResult {
+  conflicts: Conflict[];
+  nonConflicting: ReviewerChange[];
+}
+
+interface ConflictsData {
+  base: string;
+  merged: string;
+  conflicts: Conflict[];
+}
+
+// =============================================================================
+// Public API
+// =============================================================================
 
 /**
- * Initialize .rev directory
- * @param {string} projectDir
+ * Initialize .rev directory for revision tracking
+ * @param projectDir - Project directory path
+ * @throws {TypeError} If projectDir is not a string
  */
-export function initRevDir(projectDir) {
+export function initRevDir(projectDir: string): void {
+  if (typeof projectDir !== 'string') {
+    throw new TypeError(`projectDir must be a string, got ${typeof projectDir}`);
+  }
+
   const revDir = path.join(projectDir, REV_DIR);
   if (!fs.existsSync(revDir)) {
     fs.mkdirSync(revDir, { recursive: true });
@@ -55,10 +92,22 @@ export function initRevDir(projectDir) {
 /**
  * Store the base document for three-way merge
  * Overwrites any previous base document
- * @param {string} projectDir
- * @param {string} docxPath - Path to the built docx
+ * @param projectDir - Project directory path
+ * @param docxPath - Path to the built docx to store as base
+ * @throws {TypeError} If arguments are not strings
+ * @throws {Error} If docxPath does not exist
  */
-export function storeBaseDocument(projectDir, docxPath) {
+export function storeBaseDocument(projectDir: string, docxPath: string): void {
+  if (typeof projectDir !== 'string') {
+    throw new TypeError(`projectDir must be a string, got ${typeof projectDir}`);
+  }
+  if (typeof docxPath !== 'string') {
+    throw new TypeError(`docxPath must be a string, got ${typeof docxPath}`);
+  }
+  if (!fs.existsSync(docxPath)) {
+    throw new Error(`Source document not found: ${docxPath}`);
+  }
+
   initRevDir(projectDir);
   const basePath = path.join(projectDir, BASE_FILE);
   fs.copyFileSync(docxPath, basePath);
@@ -66,10 +115,15 @@ export function storeBaseDocument(projectDir, docxPath) {
 
 /**
  * Get the base document path if it exists
- * @param {string} projectDir
- * @returns {string|null}
+ * @param projectDir - Project directory path
+ * @returns Path to base document or null if not found
+ * @throws {TypeError} If projectDir is not a string
  */
-export function getBaseDocument(projectDir) {
+export function getBaseDocument(projectDir: string): string | null {
+  if (typeof projectDir !== 'string') {
+    throw new TypeError(`projectDir must be a string, got ${typeof projectDir}`);
+  }
+
   const basePath = path.join(projectDir, BASE_FILE);
   if (fs.existsSync(basePath)) {
     return basePath;
@@ -79,22 +133,31 @@ export function getBaseDocument(projectDir) {
 
 /**
  * Check if base document exists
- * @param {string} projectDir
- * @returns {boolean}
+ * @param projectDir - Project directory path
+ * @returns True if base document exists
+ * @throws {TypeError} If projectDir is not a string
  */
-export function hasBaseDocument(projectDir) {
+export function hasBaseDocument(projectDir: string): boolean {
+  if (typeof projectDir !== 'string') {
+    throw new TypeError(`projectDir must be a string, got ${typeof 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
+ * Compute text similarity between two strings using Jaccard-like coefficient
+ * @param text1 - First text to compare
+ * @param text2 - Second text to compare
+ * @returns Similarity score 0-1 (0 = no similarity, 1 = identical)
  */
-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);
+export function computeSimilarity(text1: string, text2: string): number {
+  if (typeof text1 !== 'string' || typeof text2 !== 'string') {
+    return 0;
+  }
+
+  const words1 = new Set(text1.toLowerCase().split(/\s+/).filter(w => w.length > MIN_WORD_LENGTH));
+  const words2 = text2.toLowerCase().split(/\s+/).filter(w => w.length > MIN_WORD_LENGTH);
   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);
@@ -102,11 +165,8 @@ export function computeSimilarity(text1, text2) {
 
 /**
  * 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) {
+export async function checkBaseMatch(basePath: string, reviewerPath: string): Promise<CheckMatchResult> {
   try {
     const { text: baseText } = await extractFromWord(basePath);
     const { text: reviewerText } = await extractFromWord(reviewerPath);
@@ -120,13 +180,12 @@ export async function checkBaseMatch(basePath, reviewerPath) {
 /**
  * Extract changes from a Word document compared to original
  * 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[]}
+ * @param originalText - Original text (from base document)
+ * @param wordText - Text extracted from reviewer's Word doc
+ * @param reviewer - Reviewer identifier
  */
-export function extractChanges(originalText, wordText, reviewer) {
-  const changes = [];
+export function extractChanges(originalText: string, wordText: string, reviewer: string): ReviewerChange[] {
+  const changes: ReviewerChange[] = [];
 
   // Use sentence-level diff for better granularity
   const diffs = diffSentences(originalText, wordText);
@@ -136,6 +195,7 @@ export function extractChanges(originalText, wordText, reviewer) {
 
   while (i < diffs.length) {
     const part = diffs[i];
+    if (!part) break;
 
     if (!part.added && !part.removed) {
       // Unchanged
@@ -143,13 +203,15 @@ export function extractChanges(originalText, wordText, reviewer) {
       i++;
     } else if (part.removed && diffs[i + 1]?.added) {
       // Replacement: removed followed by added
+      const nextPart = diffs[i + 1];
+      if (!nextPart) break;
       changes.push({
         reviewer,
         type: 'replace',
         start: originalPos,
         end: originalPos + part.value.length,
         oldText: part.value,
-        newText: diffs[i + 1].value,
+        newText: nextPart.value,
       });
       originalPos += part.value.length;
       i += 2;
@@ -184,13 +246,9 @@ export function extractChanges(originalText, wordText, reviewer) {
 
 /**
  * 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 = [];
+export function extractChangesWordLevel(originalText: string, wordText: string, reviewer: string): ReviewerChange[] {
+  const changes: ReviewerChange[] = [];
   const diffs = diffWords(originalText, wordText);
 
   let originalPos = 0;
@@ -198,18 +256,21 @@ export function extractChangesWordLevel(originalText, wordText, reviewer) {
 
   while (i < diffs.length) {
     const part = diffs[i];
+    if (!part) break;
 
     if (!part.added && !part.removed) {
       originalPos += part.value.length;
       i++;
     } else if (part.removed && diffs[i + 1]?.added) {
+      const nextPart = diffs[i + 1];
+      if (!nextPart) break;
       changes.push({
         reviewer,
         type: 'replace',
         start: originalPos,
         end: originalPos + part.value.length,
         oldText: part.value,
-        newText: diffs[i + 1].value,
+        newText: nextPart.value,
       });
       originalPos += part.value.length;
       i += 2;
@@ -242,11 +303,8 @@ export function extractChangesWordLevel(originalText, wordText, reviewer) {
 
 /**
  * Check if two changes overlap
- * @param {ReviewerChange} a
- * @param {ReviewerChange} b
- * @returns {boolean}
  */
-function changesOverlap(a, b) {
+function changesOverlap(a: ReviewerChange, b: ReviewerChange): boolean {
   // Insertions at same point conflict
   if (a.type === 'insert' && b.type === 'insert' && a.start === b.start) {
     return a.newText !== b.newText; // Same insertion is not a conflict
@@ -274,22 +332,22 @@ function changesOverlap(a, b) {
 
 /**
  * Detect conflicts between changes from multiple reviewers
- * @param {ReviewerChange[][]} allChanges - Array of change arrays, one per reviewer
- * @returns {{conflicts: Conflict[], nonConflicting: ReviewerChange[]}}
+ * @param allChanges - Array of change arrays, one per reviewer
  */
-export function detectConflicts(allChanges) {
+export function detectConflicts(allChanges: ReviewerChange[][]): ConflictDetectionResult {
   // Flatten and sort all changes by position
   const flat = allChanges.flat().sort((a, b) => a.start - b.start || a.end - b.end);
 
-  const conflicts = [];
-  const nonConflicting = [];
-  const usedIndices = new Set();
+  const conflicts: Conflict[] = [];
+  const nonConflicting: ReviewerChange[] = [];
+  const usedIndices = new Set<number>();
   let conflictId = 0;
 
   for (let i = 0; i < flat.length; i++) {
     if (usedIndices.has(i)) continue;
 
     const change = flat[i];
+    if (!change) continue;
     const conflictingChanges = [change];
 
     // Find all changes that conflict with this one
@@ -297,6 +355,7 @@ export function detectConflicts(allChanges) {
       if (usedIndices.has(j)) continue;
 
       const other = flat[j];
+      if (!other) continue;
 
       // Stop if we're past the range
       if (other.start > change.end && change.type !== 'insert') break;
@@ -309,15 +368,16 @@ export function detectConflicts(allChanges) {
 
     if (conflictingChanges.length > 1) {
       // Multiple reviewers changed the same region
-      const start = Math.min(...conflictingChanges.map(c => c.start));
-      const end = Math.max(...conflictingChanges.map(c => c.end));
+      const start = Math.min(...conflictingChanges.map(c => c?.start ?? 0).filter(s => s !== undefined));
+      const end = Math.max(...conflictingChanges.map(c => c?.end ?? 0).filter(e => e !== undefined));
+      const firstChange = conflictingChanges[0];
 
       conflicts.push({
         id: `c${++conflictId}`,
         start,
         end,
-        original: conflictingChanges[0].oldText || '',
-        changes: conflictingChanges,
+        original: firstChange?.oldText || '',
+        changes: conflictingChanges.filter((c): c is ReviewerChange => c !== undefined),
         resolved: null,
       });
       usedIndices.add(i);
@@ -329,8 +389,8 @@ export function detectConflicts(allChanges) {
   }
 
   // Deduplicate identical non-conflicting changes
-  const seen = new Map();
-  const dedupedNonConflicting = [];
+  const seen = new Map<string, boolean>();
+  const dedupedNonConflicting: ReviewerChange[] = [];
 
   for (const change of nonConflicting) {
     const key = `${change.start}:${change.end}:${change.type}:${change.newText}`;
@@ -345,11 +405,10 @@ export function detectConflicts(allChanges) {
 
 /**
  * Apply non-conflicting changes to text
- * @param {string} originalText
- * @param {ReviewerChange[]} changes - Must be sorted by position
- * @returns {string}
+ * @param originalText
+ * @param changes - Must be sorted by position
  */
-export function applyChanges(originalText, changes) {
+export function applyChanges(originalText: string, changes: ReviewerChange[]): string {
   // Sort by position descending to apply from end to start
   const sorted = [...changes].sort((a, b) => b.start - a.start);
 
@@ -370,11 +429,8 @@ export function applyChanges(originalText, changes) {
 
 /**
  * Apply changes as CriticMarkup annotations
- * @param {string} originalText
- * @param {ReviewerChange[]} changes
- * @returns {string}
  */
-export function applyChangesAsAnnotations(originalText, changes) {
+export function applyChangesAsAnnotations(originalText: string, changes: ReviewerChange[]): string {
   const sorted = [...changes].sort((a, b) => b.start - a.start);
 
   let result = originalText;
@@ -397,18 +453,15 @@ export function applyChangesAsAnnotations(originalText, changes) {
 
 /**
  * Apply changes as git-style conflict markers
- * @param {string} originalText
- * @param {Conflict[]} conflicts
- * @returns {string}
  */
-export function applyConflictMarkers(originalText, conflicts) {
+export function applyConflictMarkers(originalText: string, conflicts: Conflict[]): string {
   // Sort by position descending
   const sorted = [...conflicts].sort((a, b) => b.start - a.start);
 
   let result = originalText;
 
   for (const conflict of sorted) {
-    const markers = [];
+    const markers: string[] = [];
     markers.push(`<<<<<<< CONFLICT ${conflict.id}`);
 
     for (const change of conflict.changes) {
@@ -433,12 +486,9 @@ export function applyConflictMarkers(originalText, conflicts) {
 
 /**
  * Format a conflict for display
- * @param {Conflict} conflict
- * @param {string} originalText
- * @returns {string}
  */
-export function formatConflict(conflict, originalText) {
-  const lines = [];
+export function formatConflict(conflict: Conflict, originalText: string): string {
+  const lines: string[] = [];
   const context = 50;
 
   // Show context
@@ -473,13 +523,10 @@ export function formatConflict(conflict, originalText) {
 
 /**
  * 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) {
+export function saveConflicts(projectDir: string, conflicts: Conflict[], baseDoc: string): void {
   const conflictsPath = path.join(projectDir, CONFLICTS_FILE);
-  const data = {
+  const data: ConflictsData = {
     base: baseDoc,
     merged: new Date().toISOString(),
     conflicts,
@@ -496,22 +543,19 @@ export function saveConflicts(projectDir, conflicts, baseDoc) {
 
 /**
  * Load conflicts from file
- * @param {string} projectDir
- * @returns {{base: string, merged: string, conflicts: Conflict[]}|null}
  */
-export function loadConflicts(projectDir) {
+export function loadConflicts(projectDir: string): ConflictsData | null {
   const conflictsPath = path.join(projectDir, CONFLICTS_FILE);
   if (!fs.existsSync(conflictsPath)) {
     return null;
   }
-  return JSON.parse(fs.readFileSync(conflictsPath, 'utf-8'));
+  return JSON.parse(fs.readFileSync(conflictsPath, 'utf-8')) as ConflictsData;
 }
 
 /**
  * Clear conflicts file after resolution
- * @param {string} projectDir
  */
-export function clearConflicts(projectDir) {
+export function clearConflicts(projectDir: string): void {
   const conflictsPath = path.join(projectDir, CONFLICTS_FILE);
   if (fs.existsSync(conflictsPath)) {
     fs.unlinkSync(conflictsPath);
@@ -520,12 +564,12 @@ export function clearConflicts(projectDir) {
 
 /**
  * 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 = {}) {
+export async function mergeThreeWay(
+  basePath: string,
+  reviewerDocs: ReviewerDoc[],
+  options: MergeOptions = {}
+): Promise<MergeResult & { baseText: string }> {
   const { diffLevel = 'sentence' } = options;
 
   if (!fs.existsSync(basePath)) {
@@ -536,8 +580,8 @@ export async function mergeThreeWay(basePath, reviewerDocs, options = {}) {
   const { text: baseText } = await extractFromWord(basePath);
 
   // Extract changes from each reviewer relative to base
-  const allChanges = [];
-  const allComments = [];
+  const allChanges: ReviewerChange[][] = [];
+  const allComments: ReviewerComment[] = [];
 
   for (const doc of reviewerDocs) {
     if (!fs.existsSync(doc.path)) {
@@ -557,8 +601,11 @@ export async function mergeThreeWay(basePath, reviewerDocs, options = {}) {
     try {
       const comments = await extractWordComments(doc.path);
       allComments.push(...comments.map(c => ({ ...c, reviewer: doc.name })));
-    } catch {
-      // Comments extraction failed, continue without
+    } catch (e) {
+      if (process.env.DEBUG) {
+        const error = e as Error;
+        console.warn(`merge: Failed to extract comments:`, error.message);
+      }
     }
   }
 
@@ -581,18 +628,18 @@ export async function mergeThreeWay(basePath, reviewerDocs, options = {}) {
     comments: allComments.length,
   };
 
-  return { merged, conflicts, stats, baseText };
+  return { merged, conflicts, stats, baseText, originalText: 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
- * @returns {Promise<{merged: string, conflicts: Conflict[], stats: Object}>}
  */
-export async function mergeReviewerDocs(originalPath, reviewerDocs, options = {}) {
+export async function mergeReviewerDocs(
+  originalPath: string,
+  reviewerDocs: ReviewerDoc[],
+  options: MergeOptions = {}
+): Promise<MergeResult> {
   const { autoResolve = false } = options;
 
   if (!fs.existsSync(originalPath)) {
@@ -602,8 +649,8 @@ export async function mergeReviewerDocs(originalPath, reviewerDocs, options = {}
   const originalText = fs.readFileSync(originalPath, 'utf-8');
 
   // Extract changes from each reviewer
-  const allChanges = [];
-  const allComments = [];
+  const allChanges: ReviewerChange[][] = [];
+  const allComments: ReviewerComment[] = [];
 
   for (const doc of reviewerDocs) {
     if (!fs.existsSync(doc.path)) {
@@ -618,8 +665,11 @@ export async function mergeReviewerDocs(originalPath, reviewerDocs, options = {}
     try {
       const comments = await extractWordComments(doc.path);
       allComments.push(...comments.map(c => ({ ...c, reviewer: doc.name })));
-    } catch {
-      // Comments extraction failed, continue without
+    } catch (e) {
+      if (process.env.DEBUG) {
+        const error = e as Error;
+        console.warn(`merge: Failed to extract comments:`, error.message);
+      }
     }
   }
 
@@ -648,26 +698,26 @@ export async function mergeReviewerDocs(originalPath, reviewerDocs, options = {}
 
 /**
  * Resolve a conflict by choosing one option
- * @param {Conflict} conflict
- * @param {number} choice - Index of chosen change (0-based)
- * @returns {ReviewerChange}
+ * @param conflict
+ * @param choice - Index of chosen change (0-based)
  */
-export function resolveConflict(conflict, choice) {
+export function resolveConflict(conflict: Conflict, choice: number): ReviewerChange {
   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];
+  const selectedChange = conflict.changes[choice];
+  if (!selectedChange) {
+    throw new Error(`Invalid choice: ${choice}. Change not found`);
+  }
+  conflict.resolved = selectedChange.reviewer;
+  return selectedChange;
 }
 
 /**
  * Get list of unresolved conflicts
- * @param {string} projectDir
- * @returns {Conflict[]}
  */
-export function getUnresolvedConflicts(projectDir) {
+export function getUnresolvedConflicts(projectDir: string): Conflict[] {
   const data = loadConflicts(projectDir);
   if (!data) return [];
   return data.conflicts.filter(c => c.resolved === null);
 }
-