docrev 0.8.1 → 0.8.5

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

@@ -4,201 +4,9 @@
  */
 
 import * as fs from 'fs';
-import * as path from 'path';
-import * as os from 'os';
-
-// ============================================================================
-// Rate Limiter - Prevents API abuse with exponential backoff
-// ============================================================================
-
-class RateLimiter {
-  constructor(options = {}) {
-    this.minDelay = options.minDelay || 100;      // Min delay between requests (ms)
-    this.maxDelay = options.maxDelay || 30000;    // Max delay after backoff (ms)
-    this.maxRetries = options.maxRetries || 3;    // Max retry attempts
-    this.backoffFactor = options.backoffFactor || 2;
-    this.lastRequestTime = 0;
-    this.currentDelay = this.minDelay;
-    this.consecutiveErrors = 0;
-  }
-
-  async wait() {
-    const now = Date.now();
-    const elapsed = now - this.lastRequestTime;
-    if (elapsed < this.currentDelay) {
-      await new Promise(r => setTimeout(r, this.currentDelay - elapsed));
-    }
-    this.lastRequestTime = Date.now();
-  }
-
-  onSuccess() {
-    // Gradually reduce delay on success
-    this.consecutiveErrors = 0;
-    this.currentDelay = Math.max(this.minDelay, this.currentDelay / this.backoffFactor);
-  }
-
-  onError(statusCode) {
-    this.consecutiveErrors++;
-    // Exponential backoff
-    if (statusCode === 429 || statusCode >= 500) {
-      this.currentDelay = Math.min(this.maxDelay, this.currentDelay * this.backoffFactor);
-    }
-    return this.consecutiveErrors <= this.maxRetries;
-  }
-
-  async fetchWithRetry(url, options = {}) {
-    let lastError;
-
-    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
-      await this.wait();
-
-      try {
-        const response = await fetch(url, options);
-
-        if (response.status === 429) {
-          // Rate limited - back off
-          const retryAfter = response.headers.get('Retry-After');
-          const delay = retryAfter ? parseInt(retryAfter, 10) * 1000 : this.currentDelay * 2;
-          this.currentDelay = Math.min(this.maxDelay, delay);
-          if (!this.onError(429)) break;
-          continue;
-        }
-
-        if (response.status >= 500 && attempt < this.maxRetries) {
-          // Server error - retry with backoff
-          if (!this.onError(response.status)) break;
-          continue;
-        }
-
-        this.onSuccess();
-        return response;
-      } catch (err) {
-        lastError = err;
-        if (!this.onError(0)) break;
-      }
-    }
-
-    throw lastError || new Error('Max retries exceeded');
-  }
-}
-
-// Shared rate limiters for different APIs
-const crossrefLimiter = new RateLimiter({ minDelay: 100, maxDelay: 10000 });
-const dataciteLimiter = new RateLimiter({ minDelay: 100, maxDelay: 10000 });
-const doiOrgLimiter = new RateLimiter({ minDelay: 200, maxDelay: 15000 });
-
-// ============================================================================
-// DOI Cache - Reduces API calls for repeated lookups
-// ============================================================================
-
-const CACHE_FILE = path.join(os.homedir(), '.rev-doi-cache.json');
-const CACHE_TTL = 7 * 24 * 60 * 60 * 1000; // 7 days in ms
-
-let doiCache = null;
-
-/**
- * Load DOI cache from disk
- * @returns {object}
- */
-function loadCache() {
-  if (doiCache !== null) return doiCache;
-
-  try {
-    if (fs.existsSync(CACHE_FILE)) {
-      const data = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf-8'));
-      doiCache = data;
-      return doiCache;
-    }
-  } catch {
-    // Ignore cache errors
-  }
-
-  doiCache = { entries: {}, version: 1 };
-  return doiCache;
-}
-
-/**
- * Save DOI cache to disk
- */
-function saveCache() {
-  if (!doiCache) return;
-
-  try {
-    fs.writeFileSync(CACHE_FILE, JSON.stringify(doiCache, null, 2), 'utf-8');
-  } catch {
-    // Ignore cache write errors
-  }
-}
-
-/**
- * Get cached DOI result
- * @param {string} doi
- * @returns {object|null}
- */
-function getCachedDoi(doi) {
-  const cache = loadCache();
-  const entry = cache.entries[doi];
-
-  if (!entry) return null;
-
-  // Check if cache entry is expired
-  if (Date.now() - entry.timestamp > CACHE_TTL) {
-    delete cache.entries[doi];
-    return null;
-  }
-
-  return entry.result;
-}
-
-/**
- * Cache a DOI result
- * @param {string} doi
- * @param {object} result
- */
-function cacheDoi(doi, result) {
-  const cache = loadCache();
-  cache.entries[doi] = {
-    result,
-    timestamp: Date.now(),
-  };
-
-  // Limit cache size - remove oldest entries if over 1000
-  const entries = Object.entries(cache.entries);
-  if (entries.length > 1000) {
-    entries
-      .sort((a, b) => a[1].timestamp - b[1].timestamp)
-      .slice(0, entries.length - 800)
-      .forEach(([key]) => delete cache.entries[key]);
-  }
-
-  saveCache();
-}
-
-/**
- * Clear the DOI cache
- */
-export function clearDoiCache() {
-  doiCache = { entries: {}, version: 1 };
-  try {
-    if (fs.existsSync(CACHE_FILE)) {
-      fs.unlinkSync(CACHE_FILE);
-    }
-  } catch {
-    // Ignore
-  }
-}
-
-/**
- * Get DOI cache statistics
- * @returns {{ size: number, path: string }}
- */
-export function getDoiCacheStats() {
-  const cache = loadCache();
-  return {
-    size: Object.keys(cache.entries).length,
-    path: CACHE_FILE,
-  };
-}
+import type { BibEntry, DoiCheckResult, BibtexFetchResult, DoiLookupResult, BibCheckResult } from './types.js';
+import { crossrefLimiter, dataciteLimiter, doiOrgLimiter } from './rate-limiter.js';
+import { getCachedDoi, cacheDoi } from './doi-cache.js';
 
 // Entry types that typically don't have DOIs
 const NO_DOI_TYPES = new Set([
@@ -224,25 +32,23 @@ const EXPECT_DOI_TYPES = new Set([
 
 /**
  * Parse .bib file and extract entries with DOI info
- * @param {string} bibPath
- * @returns {Array<{key: string, type: string, doi: string|null, title: string, skip: boolean, line: number}>}
  */
-export function parseBibEntries(bibPath) {
+export function parseBibEntries(bibPath: string): BibEntry[] {
   if (!fs.existsSync(bibPath)) {
     return [];
   }
 
   const content = fs.readFileSync(bibPath, 'utf-8');
-  const entries = [];
+  const entries: BibEntry[] = [];
   const lines = content.split('\n');
 
   // Pattern for bib entries: @type{key,
   const entryPattern = /@(\w+)\s*\{\s*([^,\s]+)\s*,/g;
 
-  let match;
+  let match: RegExpExecArray | null;
   while ((match = entryPattern.exec(content)) !== null) {
-    const type = match[1].toLowerCase();
-    const key = match[2];
+    const type = match[1]!.toLowerCase();
+    const key = match[2]!;
     const startPos = match.index;
 
     // Find the line number
@@ -273,7 +79,7 @@ export function parseBibEntries(bibPath) {
 
     // Extract DOI field
     const doiMatch = entryContent.match(/\bdoi\s*=\s*[{"]([^}"]+)[}"]/i);
-    let doi = doiMatch ? doiMatch[1].trim() : null;
+    let doi = doiMatch ? doiMatch[1]!.trim() : null;
 
     // Clean DOI - remove URL prefix if present
     if (doi) {
@@ -282,19 +88,19 @@ export function parseBibEntries(bibPath) {
 
     // Extract title for display
     const titleMatch = entryContent.match(/\btitle\s*=\s*[{"]([^}"]+)[}"]/i);
-    const title = titleMatch ? titleMatch[1].trim().slice(0, 60) : '';
+    const title = titleMatch ? titleMatch[1]!.trim().slice(0, 60) : '';
 
     // Extract author for lookup
     const authorMatch = entryContent.match(/\bauthor\s*=\s*[{"]([^}"]+)[}"]/i);
-    const authorRaw = authorMatch ? authorMatch[1].trim() : '';
+    const authorRaw = authorMatch ? authorMatch[1]!.trim() : '';
 
     // Extract year
     const yearMatch = entryContent.match(/\byear\s*=\s*[{"]?(\d{4})[}""]?/i);
-    const year = yearMatch ? parseInt(yearMatch[1]) : null;
+    const year = yearMatch ? parseInt(yearMatch[1]!) : null;
 
     // Extract journal
     const journalMatch = entryContent.match(/\bjournal\s*=\s*[{"]([^}"]+)[}"]/i);
-    const journal = journalMatch ? journalMatch[1].trim() : '';
+    const journal = journalMatch ? journalMatch[1]!.trim() : '';
 
     // Check for skip marker: nodoi = {true} or nodoi = true
     const skipMatch = entryContent.match(/\bnodoi\s*=\s*[{"]?(true|yes|1)[}""]?/i);
@@ -311,7 +117,7 @@ export function parseBibEntries(bibPath) {
     entries.push({
       key,
       type,
-      doi,
+      doi: doi || null,
       title,
       authorRaw,
       year,
@@ -328,10 +134,8 @@ export function parseBibEntries(bibPath) {
 
 /**
  * Validate DOI format
- * @param {string} doi
- * @returns {boolean}
  */
-export function isValidDoiFormat(doi) {
+export function isValidDoiFormat(doi: string): boolean {
   if (!doi) return false;
   // DOI format: 10.prefix/suffix
   // Prefix is 4+ digits, suffix can contain most characters
@@ -340,10 +144,8 @@ export function isValidDoiFormat(doi) {
 
 /**
  * Check if DOI resolves via DataCite (for Zenodo, Figshare, etc.)
- * @param {string} doi
- * @returns {Promise<{valid: boolean, metadata?: object, error?: string}>}
  */
-async function checkDoiDataCite(doi) {
+async function checkDoiDataCite(doi: string): Promise<DoiCheckResult> {
   try {
     const response = await dataciteLimiter.fetchWithRetry(
       `https://api.datacite.org/dois/${encodeURIComponent(doi)}`,
@@ -363,7 +165,7 @@ async function checkDoiDataCite(doi) {
       return { valid: false, error: `HTTP ${response.status}` };
     }
 
-    const data = await response.json();
+    const data = await response.json() as any;
     const attrs = data.data?.attributes;
 
     if (!attrs) {
@@ -375,26 +177,26 @@ async function checkDoiDataCite(doi) {
       source: 'datacite',
       metadata: {
         title: attrs.titles?.[0]?.title || '',
-        authors: attrs.creators?.map(c => `${c.givenName || ''} ${c.familyName || ''}`.trim()) || [],
+        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.message };
+    return { valid: false, error: (err as Error).message };
   }
 }
 
+interface CheckDoiOptions {
+  skipCache?: boolean;
+}
+
 /**
  * Check if DOI resolves (exists) - tries Crossref first, then DataCite
  * Results are cached for 7 days to reduce API calls.
- * @param {string} doi
- * @param {object} options
- * @param {boolean} options.skipCache - Skip cache lookup
- * @returns {Promise<{valid: boolean, source?: string, metadata?: object, error?: string, cached?: boolean}>}
  */
-export async function checkDoi(doi, options = {}) {
+export async function checkDoi(doi: string, options: CheckDoiOptions = {}): Promise<DoiCheckResult & { cached?: boolean }> {
   if (!isValidDoiFormat(doi)) {
     return { valid: false, error: 'Invalid DOI format' };
   }
@@ -403,7 +205,7 @@ export async function checkDoi(doi, options = {}) {
   if (!options.skipCache) {
     const cached = getCachedDoi(doi);
     if (cached) {
-      return { ...cached, cached: true };
+      return { ...cached, cached: true } as DoiCheckResult & { cached?: boolean };
     }
   }
 
@@ -450,15 +252,15 @@ export async function checkDoi(doi, options = {}) {
       return { valid: false, error: `HTTP ${response.status}` };
     }
 
-    const data = await response.json();
+    const data = await response.json() as any;
     const work = data.message;
 
-    const result = {
+    const result: DoiCheckResult = {
       valid: true,
       source: 'crossref',
       metadata: {
         title: work.title?.[0] || '',
-        authors: work.author?.map(a => `${a.given || ''} ${a.family || ''}`.trim()) || [],
+        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,
@@ -469,16 +271,14 @@ export async function checkDoi(doi, options = {}) {
     return result;
   } catch (err) {
     // Don't cache network errors
-    return { valid: false, error: err.message };
+    return { valid: false, error: (err as Error).message };
   }
 }
 
 /**
  * Fetch BibTeX from DOI using content negotiation
- * @param {string} doi
- * @returns {Promise<{success: boolean, bibtex?: string, error?: string}>}
  */
-export async function fetchBibtex(doi) {
+export async function fetchBibtex(doi: string): Promise<BibtexFetchResult> {
   // Clean DOI
   doi = doi.replace(/^https?:\/\/(dx\.)?doi\.org\//i, '');
 
@@ -510,21 +310,23 @@ export async function fetchBibtex(doi) {
 
     return { success: true, bibtex: bibtex.trim() };
   } catch (err) {
-    return { success: false, error: err.message };
+    return { success: false, error: (err as Error).message };
   }
 }
 
+interface CheckBibDoisOptions {
+  checkMissing?: boolean;
+  parallel?: number;
+}
+
 /**
  * Check all DOIs in a .bib file
- * @param {string} bibPath
- * @param {object} options
- * @returns {Promise<{entries: Array, valid: number, invalid: number, missing: number, skipped: number}>}
  */
-export async function checkBibDois(bibPath, options = {}) {
+export async function checkBibDois(bibPath: string, options: CheckBibDoisOptions = {}): Promise<BibCheckResult> {
   const { checkMissing = false, parallel = 5 } = options;
 
   const entries = parseBibEntries(bibPath);
-  const results = [];
+  const results: Array<BibEntry & { status: string; message?: string; metadata?: object }> = [];
 
   let valid = 0;
   let invalid = 0;
@@ -588,14 +390,20 @@ export async function checkBibDois(bibPath, options = {}) {
   return { entries: results, valid, invalid, missing, skipped };
 }
 
+interface DataCiteItem {
+  id: string;
+  attributes: {
+    titles?: Array<{ title: string }>;
+    creators?: Array<{ givenName?: string; familyName?: string }>;
+    publicationYear: number;
+    publisher?: string;
+  };
+}
+
 /**
  * Search DataCite API (for Zenodo, Figshare, etc.)
- * @param {string} title
- * @param {string} author
- * @param {number} year
- * @returns {Promise<Array>}
  */
-async function searchDataCite(title, author = '', year = null) {
+async function searchDataCite(title: string, author: string = '', year: number | null = null): Promise<any[]> {
   try {
     // DataCite query syntax
     let query = `titles.title:${title.replace(/[{}]/g, '')}`;
@@ -623,7 +431,7 @@ async function searchDataCite(title, author = '', year = null) {
 
     if (!response.ok) return [];
 
-    const data = await response.json();
+    const data = await response.json() as { data?: DataCiteItem[] };
     const items = data.data || [];
 
     return items.map(item => {
@@ -645,10 +453,8 @@ async function searchDataCite(title, author = '', year = null) {
 
 /**
  * Normalize text for comparison (lowercase, remove special chars)
- * @param {string} text
- * @returns {string}
  */
-function normalizeText(text) {
+function normalizeForMatching(text: string): string {
   return (text || '')
     .toLowerCase()
     .replace(/[{}\\]/g, '')  // Remove LaTeX braces
@@ -659,12 +465,8 @@ function normalizeText(text) {
 
 /**
  * Check if DOI looks like a supplement, figure, or review (not the main paper)
- * @param {string} doi
- * @param {string} title
- * @param {string} journal
- * @returns {boolean}
  */
-function isSupplementOrReview(doi, title = '', journal = '') {
+function isSupplementOrReview(doi: string, title: string = '', journal: string = ''): boolean {
   const doiLower = (doi || '').toLowerCase();
   const titleLower = (title || '').toLowerCase();
   const journalLower = (journal || '').toLowerCase();
@@ -687,15 +489,26 @@ function isSupplementOrReview(doi, title = '', journal = '') {
   return false;
 }
 
+interface CrossrefItem {
+  DOI: string;
+  title?: string[];
+  author?: Array<{ given?: string; family?: string }>;
+  'published-print'?: { 'date-parts': number[][] };
+  'published-online'?: { 'date-parts': number[][] };
+  'container-title'?: string[];
+  score?: number;
+  type?: string;
+}
+
 /**
  * Search for DOI by title and author using Crossref API (+ DataCite fallback)
- * @param {string} title
- * @param {string} author - First author's last name
- * @param {number} year - Publication year (optional, improves accuracy)
- * @param {string} journal - Expected journal name (optional, improves accuracy)
- * @returns {Promise<{found: boolean, doi?: string, confidence?: number, metadata?: object, error?: string}>}
  */
-export async function lookupDoi(title, author = '', year = null, journal = '') {
+export async function lookupDoi(
+  title: string,
+  author: string = '',
+  year: number | null = null,
+  journal: string = ''
+): Promise<DoiLookupResult> {
   if (!title || title.length < 10) {
     return { found: false, error: 'Title too short for reliable search' };
   }
@@ -714,7 +527,7 @@ export async function lookupDoi(title, author = '', year = null, journal = '') {
       query = `${query} ${journal}`;
     }
 
-    let items = [];
+    let items: CrossrefItem[] = [];
 
     // Try structured bibliographic query first (more accurate)
     const structuredParams = new URLSearchParams({
@@ -739,7 +552,7 @@ export async function lookupDoi(title, author = '', year = null, journal = '') {
     );
 
     if (response.ok) {
-      const data = await response.json();
+      const data = await response.json() as { message?: { items?: CrossrefItem[] } };
       items = data.message?.items || [];
     }
 
@@ -761,7 +574,7 @@ export async function lookupDoi(title, author = '', year = null, journal = '') {
       );
 
       if (response2.ok) {
-        const data = await response2.json();
+        const data = await response2.json() as { message?: { items?: CrossrefItem[] } };
         const newItems = data.message?.items || [];
         // Merge results, avoiding duplicates
         const existingDois = new Set(items.map(i => i.DOI));
@@ -791,7 +604,7 @@ export async function lookupDoi(title, author = '', year = null, journal = '') {
       );
 
       if (response.ok) {
-        const data = await response.json();
+        const data = await response.json() as { message?: { items?: CrossrefItem[] } };
         items = data.message?.items || [];
       }
     }
@@ -806,16 +619,16 @@ export async function lookupDoi(title, author = '', year = null, journal = '') {
       return { found: false, error: 'No results found' };
     }
 
-    const normalizedSearchTitle = normalizeText(title);
-    const normalizedJournal = normalizeText(journal);
+    const normalizedSearchTitle = normalizeForMatching(title);
+    const normalizedJournal = normalizeForMatching(journal);
 
     // Score the results
     const scored = items.map(item => {
       let score = 0;
       const itemTitle = item.title?.[0] || '';
       const itemJournal = item['container-title']?.[0] || '';
-      const normalizedItemTitle = normalizeText(itemTitle);
-      const normalizedItemJournal = normalizeText(itemJournal);
+      const normalizedItemTitle = normalizeForMatching(itemTitle);
+      const normalizedItemJournal = normalizeForMatching(itemJournal);
 
       // === PENALTY: Supplement/figure/review DOIs ===
       if (isSupplementOrReview(item.DOI, itemTitle, itemJournal)) {
@@ -908,8 +721,12 @@ export async function lookupDoi(title, author = '', year = null, journal = '') {
     const mainPapers = scored.filter(s => !s.isSupplement);
     const best = mainPapers.length > 0 ? mainPapers[0] : scored[0];
 
+    if (!best) {
+      return { found: false, error: 'No valid results found' };
+    }
+
     // Confidence thresholds
-    let confidence = 'low';
+    let confidence: 'low' | 'medium' | 'high' = 'low';
     if (best.score >= 120) confidence = 'high';
     else if (best.score >= 70) confidence = 'medium';
 
@@ -920,7 +737,7 @@ export async function lookupDoi(title, author = '', year = null, journal = '') {
         // Score DataCite results with same logic
         for (const dcItem of dataciteItems) {
           const dcTitle = dcItem.title?.[0] || '';
-          const normalizedDcTitle = normalizeText(dcTitle);
+          const normalizedDcTitle = normalizeForMatching(dcTitle);
           let dcScore = 0;
 
           // Title match
@@ -945,12 +762,11 @@ export async function lookupDoi(title, author = '', year = null, journal = '') {
               score: dcScore,
               metadata: {
                 title: dcTitle,
-                authors: dcItem.author?.map(a => `${a.given || ''} ${a.family || ''}`.trim()) || [],
+                authors: dcItem.author?.map((a: any) => `${a.given || ''} ${a.family || ''}`.trim()) || [],
                 year: dcYear,
                 journal: dcItem['container-title']?.[0] || '',
               },
               alternatives: scored.slice(0, 2),
-              source: 'datacite',
             };
           }
         }
@@ -965,23 +781,36 @@ export async function lookupDoi(title, author = '', year = null, journal = '') {
       metadata: {
         title: best.title,
         authors: best.authors,
-        year: best.year,
+        year: best.year || 0,
         journal: best.journal,
       },
       alternatives: scored.filter(s => s.doi !== best.doi).slice(0, 3),
     };
   } catch (err) {
-    return { found: false, error: err.message };
+    return { found: false, error: (err as Error).message };
   }
 }
 
+interface LookupMissingDoisOptions {
+  parallel?: number;
+  onProgress?: (current: number, total: number) => void;
+}
+
+interface LookupMissingDoiResult {
+  key: string;
+  title: string;
+  type: string;
+  journal: string;
+  result: DoiLookupResult;
+}
+
 /**
  * Look up DOIs for all entries missing them in a .bib file
- * @param {string} bibPath
- * @param {object} options
- * @returns {Promise<Array<{key: string, result: object}>>}
  */
-export async function lookupMissingDois(bibPath, options = {}) {
+export async function lookupMissingDois(
+  bibPath: string,
+  options: LookupMissingDoisOptions = {}
+): Promise<LookupMissingDoiResult[]> {
   const { parallel = 3, onProgress } = options;
 
   const entries = parseBibEntries(bibPath);
@@ -991,7 +820,7 @@ export async function lookupMissingDois(bibPath, options = {}) {
     !NO_DOI_TYPES.has(e.type)
   );
 
-  const results = [];
+  const results: LookupMissingDoiResult[] = [];
 
   for (let i = 0; i < missing.length; i += parallel) {
     const batch = missing.slice(i, i + parallel);
@@ -1004,8 +833,10 @@ export async function lookupMissingDois(bibPath, options = {}) {
         if (entry.authorRaw) {
           // Try to get first author's last name
           const firstAuthor = entry.authorRaw.split(' and ')[0];
-          const parts = firstAuthor.split(',');
-          author = parts[0]?.trim() || '';
+          if (firstAuthor) {
+            const parts = firstAuthor.split(',');
+            author = parts[0]?.trim() || '';
+          }
         }
 
         const result = await lookupDoi(entry.title, author, entry.year, entry.journal);
@@ -1035,13 +866,16 @@ export async function lookupMissingDois(bibPath, options = {}) {
   return results;
 }
 
+interface AddToBibResult {
+  success: boolean;
+  key?: string;
+  error?: string;
+}
+
 /**
  * Add a BibTeX entry to a .bib file
- * @param {string} bibPath
- * @param {string} bibtex
- * @returns {{success: boolean, key?: string, error?: string}}
  */
-export function addToBib(bibPath, bibtex) {
+export function addToBib(bibPath: string, bibtex: string): AddToBibResult {
   // Extract key from BibTeX
   const keyMatch = bibtex.match(/@\w+\s*\{\s*([^,\s]+)/);
   if (!keyMatch) {