docrev 0.10.2 → 0.11.1

package/lib/dependencies.ts

@@ -2,39 +2,68 @@
  * Dependency checking utilities for pandoc, LaTeX, and related tools
  */
 
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 
 /**
- * Check if a command is available by running it silently
+ * Run `<file> --version` without a shell and return its stdout, or null when
+ * the binary is absent (ENOENT) or exits non-zero (present but broken). Using
+ * execFileSync avoids shell quoting and treats both failure modes uniformly.
  */
-function commandExists(cmd: string): boolean {
+function runVersion(file: string, args: string[] = ['--version']): string | null {
   try {
-    execSync(cmd, { stdio: 'ignore' });
-    return true;
+    return execFileSync(file, args, { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' });
   } catch {
-    return false;
+    return null;
   }
 }
 
+function commandExists(file: string, args: string[] = ['--version']): boolean {
+  return runVersion(file, args) !== null;
+}
+
 /**
  * Check if pandoc-crossref is available
  */
 export function hasPandocCrossref(): boolean {
-  return commandExists('pandoc-crossref --version');
+  return commandExists('pandoc-crossref');
 }
 
 /**
  * Check if pandoc is available
  */
 export function hasPandoc(): boolean {
-  return commandExists('pandoc --version');
+  return commandExists('pandoc');
+}
+
+/**
+ * Parsed pandoc version (e.g. "3.9"), or null when pandoc is unavailable.
+ */
+export function getPandocVersion(): string | null {
+  const out = runVersion('pandoc');
+  if (!out) return null;
+  const m = out.match(/pandoc(?:\.exe)?\s+(\d+\.\d+(?:\.\d+)?)/i);
+  return m ? m[1]! : null;
+}
+
+/**
+ * Whether pandoc bundles citeproc and accepts `--citeproc`. That flag and the
+ * built-in citeproc arrived in pandoc 2.11; earlier versions need the separate
+ * pandoc-citeproc filter.
+ */
+export function pandocSupportsCiteproc(): boolean {
+  const v = getPandocVersion();
+  if (!v) return false;
+  const parts = v.split('.').map((n) => parseInt(n, 10));
+  const major = parts[0] ?? 0;
+  const minor = parts[1] ?? 0;
+  return major > 2 || (major === 2 && minor >= 11);
 }
 
 /**
  * Check if LaTeX is available (for PDF generation)
  */
 export function hasLatex(): boolean {
-  return commandExists('pdflatex --version') || commandExists('xelatex --version');
+  return commandExists('pdflatex') || commandExists('xelatex');
 }
 
 /**
@@ -86,6 +115,11 @@ export function checkDependencies(): DependencyStatus {
 
   if (!status.pandoc) {
     status.messages.push(`Pandoc not found. Install with: ${getInstallInstructions('pandoc')}`);
+  } else if (!pandocSupportsCiteproc()) {
+    const version = getPandocVersion();
+    status.messages.push(
+      `Pandoc ${version ?? '(unknown version)'} is older than 2.11; citation processing (--citeproc) needs 2.11+. Upgrade with: ${getInstallInstructions('pandoc')}`,
+    );
   }
   if (!status.latex) {
     status.messages.push(`LaTeX not found (required for PDF). Install with: ${getInstallInstructions('latex')}`);

package/lib/doi.ts

@@ -22,6 +22,16 @@ const NO_DOI_TYPES = new Set([
   'booklet',
 ]);
 
+// Thresholds for the heuristic DOI-match score (title + author + year +
+// journal). `high` auto-accepts, `medium` asks the user, below `medium` is a
+// weak guess. `runnerUpMargin` is how far the best must beat the second-best
+// to count as high — guards against picking the wrong one of two near-ties.
+const DOI_CONFIDENCE = {
+  high: 120,
+  medium: 70,
+  runnerUpMargin: 30,
+};
+
 // Entry types that should have DOIs
 const EXPECT_DOI_TYPES = new Set([
   'article',        // Journal articles should have DOIs
@@ -142,52 +152,6 @@ export function isValidDoiFormat(doi: string): boolean {
   return /^10\.\d{4,}\/[^\s]+$/.test(doi);
 }
 
-/**
- * Check if DOI resolves via DataCite (for Zenodo, Figshare, etc.)
- */
-async function checkDoiDataCite(doi: string): Promise<DoiCheckResult> {
-  try {
-    const response = await dataciteLimiter.fetchWithRetry(
-      `https://api.datacite.org/dois/${encodeURIComponent(doi)}`,
-      {
-        headers: {
-          'Accept': 'application/vnd.api+json',
-          'User-Agent': 'docrev/0.6.0 (https://github.com/gcol33/docrev)',
-        },
-      }
-    );
-
-    if (response.status === 404) {
-      return { valid: false, error: 'DOI not found in DataCite' };
-    }
-
-    if (!response.ok) {
-      return { valid: false, error: `HTTP ${response.status}` };
-    }
-
-    const data = await response.json() as any;
-    const attrs = data.data?.attributes;
-
-    if (!attrs) {
-      return { valid: false, error: 'Invalid DataCite response' };
-    }
-
-    return {
-      valid: true,
-      source: 'datacite',
-      metadata: {
-        title: attrs.titles?.[0]?.title || '',
-        authors: attrs.creators?.map((c: any) => `${c.givenName || ''} ${c.familyName || ''}`.trim()) || [],
-        year: attrs.publicationYear,
-        journal: attrs.publisher || '',
-        type: attrs.types?.resourceTypeGeneral || '',
-      },
-    };
-  } catch (err) {
-    return { valid: false, error: (err as Error).message };
-  }
-}
-
 interface CheckDoiOptions {
   skipCache?: boolean;
 }
@@ -209,72 +173,80 @@ export async function checkDoi(doi: string, options: CheckDoiOptions = {}): Prom
     }
   }
 
-  // Zenodo DOIs start with 10.5281 - check DataCite first
-  const isZenodo = doi.startsWith('10.5281/');
-  const isFigshare = doi.startsWith('10.6084/');
-  const isDataCiteLikely = isZenodo || isFigshare;
-
-  if (isDataCiteLikely) {
-    const dataciteResult = await checkDoiDataCite(doi);
-    if (dataciteResult.valid) {
-      cacheDoi(doi, dataciteResult);
-      return dataciteResult;
-    }
-  }
-
+  // One resolution path: doi.org content negotiation returns CSL-JSON and
+  // federates every registration agency (Crossref, DataCite, mEDRA, ...), so
+  // there is no registrar to guess and no Crossref-then-DataCite fallback.
   try {
-    // Use Crossref API to check DOI
-    const response = await crossrefLimiter.fetchWithRetry(
-      `https://api.crossref.org/works/${encodeURIComponent(doi)}`,
+    const response = await doiOrgLimiter.fetchWithRetry(
+      `https://doi.org/${encodeURIComponent(doi)}`,
       {
         headers: {
-          'User-Agent': 'docrev/0.6.0 (https://github.com/gcol33/docrev; mailto:docrev@example.com)',
+          'Accept': 'application/vnd.citationstyles.csl+json',
+          'User-Agent': 'docrev (https://github.com/gcol33/docrev)',
         },
-      }
+        redirect: 'follow',
+      },
     );
 
-    if (response.status === 404) {
-      // Try DataCite as fallback (if not already tried)
-      if (!isDataCiteLikely) {
-        const dataciteResult = await checkDoiDataCite(doi);
-        if (dataciteResult.valid) {
-          cacheDoi(doi, dataciteResult);
-          return dataciteResult;
-        }
-      }
-      const result = { valid: false, error: 'DOI not found' };
+    if (response.status === 404 || response.status === 410) {
+      // Definitive: the registry resolved and the DOI is not registered.
+      const result: DoiCheckResult = { valid: false, error: 'DOI not found' };
       cacheDoi(doi, result);
       return result;
     }
 
     if (!response.ok) {
-      // Don't cache transient errors
-      return { valid: false, error: `HTTP ${response.status}` };
+      // 5xx or unexpected: the registry is reachable but not answering — the
+      // DOI's status is unknown, so do not declare it invalid or cache it.
+      return { valid: false, unreachable: true, error: `HTTP ${response.status}` };
     }
 
-    const data = await response.json() as any;
-    const work = data.message;
-
+    const work = await response.json() as any;
     const result: DoiCheckResult = {
       valid: true,
-      source: 'crossref',
-      metadata: {
-        title: work.title?.[0] || '',
-        authors: work.author?.map((a: any) => `${a.given || ''} ${a.family || ''}`.trim()) || [],
-        year: work.published?.['date-parts']?.[0]?.[0] || work.created?.['date-parts']?.[0]?.[0],
-        journal: work['container-title']?.[0] || '',
-        type: work.type,
-      },
+      source: 'doi.org',
+      metadata: metadataFromCsl(work),
     };
 
     cacheDoi(doi, result);
     return result;
   } catch (err) {
-    // Don't cache network errors
-    return { valid: false, error: (err as Error).message };
+    // Network failure / timeout: cannot reach the resolver. Unknown, not invalid.
+    return { valid: false, unreachable: true, error: (err as Error).message };
   }
 }
 
+/**
+ * Extract docrev's metadata fields from a CSL-JSON record — the shape doi.org
+ * content negotiation returns for any registrar.
+ */
+function metadataFromCsl(work: any): DoiCheckResult['metadata'] {
+  const dateParts =
+    work?.issued?.['date-parts']?.[0] ||
+    work?.published?.['date-parts']?.[0] ||
+    work?.created?.['date-parts']?.[0];
+  const year = Array.isArray(dateParts) ? dateParts[0] : undefined;
+
+  const authors = Array.isArray(work?.author)
+    ? work.author
+        .map((a: any) => `${a.given || a.givenName || ''} ${a.family || a.familyName || ''}`.trim())
+        .filter((s: string) => s.length > 0)
+    : [];
+
+  const title = Array.isArray(work?.title) ? work.title[0] : work?.title;
+  const journal = Array.isArray(work?.['container-title'])
+    ? work['container-title'][0]
+    : work?.['container-title'] || work?.publisher;
+
+  return {
+    title: title || '',
+    authors,
+    year: year || 0,
+    journal: journal || '',
+    type: work?.type,
+  };
+}
+
 /**
  * Fetch BibTeX from DOI using content negotiation
  */
@@ -330,6 +302,7 @@ export async function checkBibDois(bibPath: string, options: CheckBibDoisOptions
 
   let valid = 0;
   let invalid = 0;
+  let unreachable = 0;
   let missing = 0;
   let skipped = 0;
 
@@ -372,6 +345,11 @@ export async function checkBibDois(bibPath: string, options: CheckBibDoisOptions
         if (check.valid) {
           valid++;
           return { ...entry, status: 'valid', metadata: check.metadata };
+        } else if (check.unreachable) {
+          // Registry unreachable — the DOI may be perfectly valid; don't
+          // condemn it. Offline runs report unreachable, not a wall of invalid.
+          unreachable++;
+          return { ...entry, status: 'unreachable', message: check.error };
         } else {
           invalid++;
           return { ...entry, status: 'invalid', message: check.error };
@@ -387,7 +365,7 @@ export async function checkBibDois(bibPath: string, options: CheckBibDoisOptions
     }
   }
 
-  return { entries: results, valid, invalid, missing, skipped };
+  return { entries: results, valid, invalid, unreachable, missing, skipped };
 }
 
 interface DataCiteItem {
@@ -725,10 +703,14 @@ export async function lookupDoi(
       return { found: false, error: 'No valid results found' };
     }
 
-    // Confidence thresholds
+    // Confidence: a "high" pick must clear the high threshold AND beat the
+    // runner-up by a margin, so two near-identical candidates are reported as
+    // "medium" (needs review) instead of one being auto-written as if certain.
+    const runnerUp = (mainPapers.length > 0 ? mainPapers : scored).find(s => s.doi !== best.doi);
+    const margin = runnerUp ? best.score - runnerUp.score : Infinity;
     let confidence: 'low' | 'medium' | 'high' = 'low';
-    if (best.score >= 120) confidence = 'high';
-    else if (best.score >= 70) confidence = 'medium';
+    if (best.score >= DOI_CONFIDENCE.high && margin >= DOI_CONFIDENCE.runnerUpMargin) confidence = 'high';
+    else if (best.score >= DOI_CONFIDENCE.medium) confidence = 'medium';
 
     // === NEW: Try DataCite if Crossref confidence is low ===
     if (confidence === 'low' && !likelyZenodo) {
@@ -758,7 +740,7 @@ export async function lookupDoi(
             return {
               found: true,
               doi: dcItem.DOI,
-              confidence: dcScore >= 120 ? 'high' : dcScore >= 70 ? 'medium' : 'low',
+              confidence: dcScore >= DOI_CONFIDENCE.high ? 'high' : dcScore >= DOI_CONFIDENCE.medium ? 'medium' : 'low',
               score: dcScore,
               metadata: {
                 title: dcTitle,

package/lib/errors.ts

@@ -44,7 +44,11 @@ export function getFileNotFoundSuggestions(filePath: string): string[] {
   // Check if directory exists
   if (!fs.existsSync(dir)) {
     suggestions.push(`Directory does not exist: ${dir}`);
-    suggestions.push(`Create it with: mkdir -p "${dir}"`);
+    suggestions.push(
+      process.platform === 'win32'
+        ? `Create it with: New-Item -ItemType Directory -Force "${dir}"`
+        : `Create it with: mkdir -p "${dir}"`,
+    );
     return suggestions;
   }
 

package/lib/import.ts

@@ -53,6 +53,7 @@ function pickBestOccurrence(
   after: string,
   anchorLen: number,
   usedPositions: Set<number>,
+  nearPos?: number,
 ): number {
   if (occurrences.length === 0) return -1;
   if (occurrences.length === 1) {
@@ -63,6 +64,13 @@ function pickBestOccurrence(
   if (bestIdx < 0) return -1;
   let bestScore = -1;
 
+  // Tie-break by context score first; when scores tie, prefer the occurrence
+  // nearest `nearPos` (a section-position estimate) if given, else the
+  // leftmost. The estimate only orders equally-scored candidates — it is never
+  // the returned position.
+  const closer = (pos: number, incumbent: number) =>
+    nearPos === undefined ? pos < incumbent : Math.abs(pos - nearPos) < Math.abs(incumbent - nearPos);
+
   for (const pos of occurrences) {
     if (usedPositions.has(pos)) continue;
     let score = 0;
@@ -87,7 +95,7 @@ function pickBestOccurrence(
       if (contextAfter.includes(afterLower.slice(0, 30))) score += 5;
     }
 
-    if (score > bestScore || (score === bestScore && pos < bestIdx)) {
+    if (score > bestScore || (score === bestScore && closer(pos, bestIdx))) {
       bestScore = score;
       bestIdx = pos;
     }
@@ -160,12 +168,24 @@ export interface InsertCommentsOptions {
   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.
+   * can distinguish placement outcomes in their summary. `placed` counts
+   * insertions made at a matched anchor or context, `lowConfidence` counts
+   * insertions made at an approximate (proportional / context-only) position
+   * that should be reviewed with `rev verify-anchors`, `deduped` counts
+   * comments already present at their anchor (skipped on re-sync), and
+   * `unmatched` counts comments that could not be placed at all.
    */
-  outStats?: { placed: number; deduped: number; unmatched: number };
+  outStats?: { placed: number; deduped: number; unmatched: number; lowConfidence?: number };
+}
+
+/**
+ * Whether a resolved placement landed on matched anchor/context text (high) or
+ * on an approximate position the user should review (low). Low-confidence
+ * strategies place the comment without matching the anchor word itself.
+ */
+function placementConfidence(strategy: string | undefined): 'high' | 'low' {
+  if (!strategy) return 'high';
+  return /proportional|position-only|context/.test(strategy) ? 'low' : 'high';
 }
 
 export interface CommentWithPos {
@@ -319,6 +339,7 @@ export function insertCommentsIntoMarkdown(
   let result = markdown;
   let unmatchedCount = 0;
   let placedCount = 0;
+  let lowConfidenceCount = 0;
   const duplicateWarnings: string[] = [];
   const usedPositions = new Set<number>(); // For tie-breaking: track used positions
 
@@ -370,24 +391,19 @@ export function insertCommentsIntoMarkdown(
     const isEmpty = typeof anchorData === 'object' && anchorData.isEmpty;
     const docPosition = typeof anchorData === 'object' ? anchorData.docPosition : undefined;
 
-    // Position-based insertion (most reliable)
+    // Section-scoped insertion. The comment is known to belong to this
+    // section (the caller already filtered by docPosition); place it by
+    // matching its anchor text within the section, never by mapping a length
+    // ratio across the docx and markdown coordinate systems. The section
+    // estimate only seeds duplicate tie-breaking and the final fallback.
     if (sectionBoundary && docPosition !== undefined) {
       const sectionLength = sectionBoundary.end - sectionBoundary.start;
       if (sectionLength > 0) {
-        let relativePos;
-        if (docPosition < sectionBoundary.start) {
-          relativePos = 0;
-        } else {
-          relativePos = docPosition - sectionBoundary.start;
-        }
-
+        const relativePos = docPosition < sectionBoundary.start ? 0 : docPosition - sectionBoundary.start;
         const proportion = Math.min(relativePos / sectionLength, 1.0);
-        const markdownPos = Math.floor(proportion * result.length);
+        const estimatedPos = 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.
+        // Empty anchor: before/after context is the only text signal.
         if ((!anchor || isEmpty) && (before || after)) {
           const ctx = findAnchorInText('', result, before, after);
           if (ctx.occurrences.length > 0) {
@@ -396,62 +412,32 @@ export function insertCommentsIntoMarkdown(
           }
         }
 
-        let insertPos = markdownPos;
-
-        // Look for nearby word boundary
-        const searchWindow = result.slice(Math.max(0, markdownPos - 25), Math.min(result.length, markdownPos + 25));
-        const spaceIdx = searchWindow.indexOf(' ', 25);
-        if (spaceIdx !== -1 && spaceIdx < 50) {
-          insertPos = Math.max(0, markdownPos - 25) + spaceIdx;
-        }
-
-        // 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).
+        // Non-empty anchor: locate it anywhere in the section text. Duplicates
+        // are disambiguated by before/after context and, only as a tie-break,
+        // by proximity to the section estimate.
         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 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' };
+          const { occurrences, matchedAnchor, strategy } = findAnchorInText(anchor, result, before, after);
+          if (occurrences.length > 0) {
+            const anchorLen = matchedAnchor ? matchedAnchor.length : 0;
+            const chosen = pickBestOccurrence(occurrences, result, before, after, anchorLen, usedPositions, estimatedPos);
+            const finalIdx = chosen >= 0 ? chosen : occurrences[0];
+            if (occurrences.length > 1 && matchedAnchor) {
+              duplicateWarnings.push(`"${matchedAnchor.slice(0, 40)}${matchedAnchor.length > 40 ? '...' : ''}" appears ${occurrences.length} times in section`);
             }
-          }
-
-          // Try first few words
-          const words = anchor.split(/\s+/).slice(0, 4).join(' ').toLowerCase();
-          if (words.length >= 10) {
-            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' };
-              }
+            usedPositions.add(finalIdx);
+            if (matchedAnchor) {
+              return { ...c, pos: finalIdx, anchorText: matchedAnchor, anchorEnd: finalIdx + anchorLen, strategy: `section:${strategy}` };
             }
+            return { ...c, pos: finalIdx, anchorText: null, strategy: `section:${strategy}` };
           }
         }
 
-        // 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' };
+        // Anchor text and context are both gone from the section. The docx
+        // marker's offset is the only remaining signal: map it proportionally
+        // and snap to a word boundary. This is an approximate placement, not a
+        // match — flagged low-confidence so the summary surfaces it.
+        const insertPos = pushPastSectionHeading(result, snapToWordBoundary(result, estimatedPos));
+        return { ...c, pos: insertPos, anchorText: null, strategy: 'proportional-fallback' };
       }
     }
 
@@ -599,11 +585,17 @@ export function insertCommentsIntoMarkdown(
     } else {
       result = result.slice(0, c.pos) + combined + result.slice(c.pos);
     }
-    placedCount += 1 + replies.length;
+    // Replies inherit the root's confidence — they ride the same position.
+    if (placementConfidence(c.strategy) === 'low') {
+      lowConfidenceCount += 1 + replies.length;
+    } else {
+      placedCount += 1 + replies.length;
+    }
   }
 
   if (outStats) {
     outStats.placed = placedCount;
+    outStats.lowConfidence = lowConfidenceCount;
     outStats.deduped = dedupedCount;
     outStats.unmatched = unmatchedCount;
   }
@@ -613,6 +605,9 @@ export function insertCommentsIntoMarkdown(
     if (unmatchedCount > 0) {
       console.warn(`Warning: ${unmatchedCount} comment(s) could not be matched to anchor text`);
     }
+    if (lowConfidenceCount > 0) {
+      console.warn(`Note: ${lowConfidenceCount} comment(s) placed approximately — run \`rev verify-anchors\` to review`);
+    }
     if (dedupedCount > 0) {
       console.warn(`Note: ${dedupedCount} comment(s) already present at anchor — skipped to avoid duplication`);
     }