docrev 0.8.1 → 0.8.5

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

@@ -4,21 +4,24 @@
  * Fetches author information from ORCID public API
  */
 
+export interface OrcidProfile {
+  orcid: string;
+  name: string;
+  affiliation: string;
+  email: string;
+}
+
 /**
  * Validate ORCID format (0000-0000-0000-0000)
- * @param {string} orcid
- * @returns {boolean}
  */
-export function isValidOrcid(orcid) {
+export function isValidOrcid(orcid: string): boolean {
   return /^(\d{4}-){3}\d{3}[\dX]$/i.test(orcid);
 }
 
 /**
  * Clean ORCID input (removes URLs, whitespace)
- * @param {string} input
- * @returns {string}
  */
-export function cleanOrcid(input) {
+export function cleanOrcid(input: string): string {
   if (!input) return '';
 
   // Remove URL prefix if present
@@ -32,10 +35,8 @@ export function cleanOrcid(input) {
 
 /**
  * Fetch author info from ORCID public API
- * @param {string} orcid
- * @returns {Promise<{name: string, affiliation: string, email: string, works: number}>}
  */
-export async function fetchOrcidProfile(orcid) {
+export async function fetchOrcidProfile(orcid: string): Promise<OrcidProfile> {
   const cleanId = cleanOrcid(orcid);
 
   if (!isValidOrcid(cleanId)) {
@@ -57,7 +58,7 @@ export async function fetchOrcidProfile(orcid) {
     throw new Error(`ORCID API error: ${response.status}`);
   }
 
-  const data = await response.json();
+  const data = await response.json() as any;
 
   // Extract name
   const nameData = data.name;
@@ -79,7 +80,7 @@ export async function fetchOrcidProfile(orcid) {
   // Extract email (if public)
   let email = '';
   const emails = data.emails?.email || [];
-  const primaryEmail = emails.find(e => e.primary) || emails[0];
+  const primaryEmail = emails.find((e: any) => e.primary) || emails[0];
   if (primaryEmail?.email) {
     email = primaryEmail.email;
   }
@@ -94,10 +95,8 @@ export async function fetchOrcidProfile(orcid) {
 
 /**
  * Fetch work count from ORCID
- * @param {string} orcid
- * @returns {Promise<number>}
  */
-export async function fetchOrcidWorkCount(orcid) {
+export async function fetchOrcidWorkCount(orcid: string): Promise<number> {
   const cleanId = cleanOrcid(orcid);
 
   if (!isValidOrcid(cleanId)) {
@@ -116,17 +115,15 @@ export async function fetchOrcidWorkCount(orcid) {
     return 0;
   }
 
-  const data = await response.json();
+  const data = await response.json() as any;
   return data.group?.length || 0;
 }
 
 /**
  * Format author for YAML
- * @param {object} profile
- * @returns {string}
  */
-export function formatAuthorYaml(profile) {
-  const lines = [];
+export function formatAuthorYaml(profile: OrcidProfile): string {
+  const lines: string[] = [];
   lines.push(`  - name: ${profile.name}`);
   if (profile.affiliation) {
     lines.push(`    affiliation: ${profile.affiliation}`);
@@ -140,10 +137,8 @@ export function formatAuthorYaml(profile) {
 
 /**
  * Generate ORCID badge markdown
- * @param {string} orcid
- * @returns {string}
  */
-export function getOrcidBadge(orcid) {
+export function getOrcidBadge(orcid: string): string {
   const cleanId = cleanOrcid(orcid);
   return `[![ORCID](https://img.shields.io/badge/ORCID-${cleanId}-a6ce39)](https://orcid.org/${cleanId})`;
 }

package/lib/{pdf-comments.js → pdf-comments.ts}

@@ -47,15 +47,35 @@ export const SIMPLE_MARGIN_PREAMBLE = `
 }
 `;
 
+/**
+ * Options for converting comments to margin notes
+ */
+export interface CommentConversionOptions {
+  useTodonotes?: boolean;
+  stripResolved?: boolean;
+}
+
+/**
+ * Result of comment conversion
+ */
+export interface CommentConversionResult {
+  markdown: string;
+  commentCount: number;
+  preamble: string;
+}
+
 /**
  * Convert CriticMarkup comments to LaTeX margin notes
  * {>>Author: comment text<<} -> \margincomment{Author: comment text}
  *
- * @param {string} markdown - Markdown with CriticMarkup comments
- * @param {object} options - { useTodonotes: boolean, stripResolved: boolean }
- * @returns {{markdown: string, commentCount: number, preamble: string}}
+ * @param markdown - Markdown with CriticMarkup comments
+ * @param options - { useTodonotes: boolean, stripResolved: boolean }
+ * @returns Converted markdown with comment count and preamble
  */
-export function convertCommentsToMarginNotes(markdown, options = {}) {
+export function convertCommentsToMarginNotes(
+  markdown: string,
+  options: CommentConversionOptions = {}
+): CommentConversionResult {
   const { useTodonotes = true, stripResolved = true } = options;
 
   let commentCount = 0;
@@ -77,7 +97,7 @@ export function convertCommentsToMarginNotes(markdown, options = {}) {
 
     if (useTodonotes) {
       // Check if content has author prefix (Author: text)
-      const authorMatch = escaped.match(/^([^:]+):\s*(.+)$/s);
+      const authorMatch = escaped.match(/^([^:]+):\s*([\s\S]+)$/);
       if (authorMatch) {
         const [, author, text] = authorMatch;
         return `\\reviewercomment{${author}}{${text}}`;
@@ -99,10 +119,10 @@ export function convertCommentsToMarginNotes(markdown, options = {}) {
 
 /**
  * Escape LaTeX special characters
- * @param {string} text
- * @returns {string}
+ * @param text - Text to escape
+ * @returns Escaped text
  */
-function escapeLatex(text) {
+function escapeLatex(text: string): string {
   return text
     .replace(/\\/g, '\\textbackslash{}')
     .replace(/([#$%&_{}])/g, '\\$1')
@@ -111,16 +131,24 @@ function escapeLatex(text) {
     .replace(/\n/g, ' ');  // Replace newlines with spaces
 }
 
+/**
+ * Result of track changes conversion
+ */
+export interface TrackChangesResult {
+  markdown: string;
+  preamble: string;
+}
+
 /**
  * Convert track changes to visible LaTeX formatting
  * {++inserted++} -> \textcolor{green}{inserted}
  * {--deleted--} -> \textcolor{red}{\sout{deleted}}
  * {~~old~>new~~} -> \textcolor{red}{\sout{old}}\textcolor{green}{new}
  *
- * @param {string} markdown
- * @returns {{markdown: string, preamble: string}}
+ * @param markdown - Markdown with track changes
+ * @returns Converted markdown and preamble
  */
-export function convertTrackChangesToLatex(markdown) {
+export function convertTrackChangesToLatex(markdown: string): TrackChangesResult {
   let result = markdown;
 
   // Insertions: {++text++} -> green text
@@ -149,12 +177,21 @@ export function convertTrackChangesToLatex(markdown) {
   return { markdown: result, preamble };
 }
 
+/**
+ * Options for combined preamble
+ */
+export interface PreambleOptions {
+  comments?: boolean;
+  trackChanges?: boolean;
+  useTodonotes?: boolean;
+}
+
 /**
  * Get combined preamble for comments and track changes
- * @param {object} options - { comments: boolean, trackChanges: boolean, useTodonotes: boolean }
- * @returns {string}
+ * @param options - { comments: boolean, trackChanges: boolean, useTodonotes: boolean }
+ * @returns Combined LaTeX preamble
  */
-export function getCombinedPreamble(options = {}) {
+export function getCombinedPreamble(options: PreambleOptions = {}): string {
   const { comments = true, trackChanges = false, useTodonotes = true } = options;
 
   let preamble = '';
@@ -180,15 +217,36 @@ export function getCombinedPreamble(options = {}) {
   return preamble;
 }
 
+/**
+ * Options for preparing markdown for annotated PDF
+ */
+export interface AnnotatedPdfOptions {
+  showTrackChanges?: boolean;
+  useTodonotes?: boolean;
+  stripResolved?: boolean;
+}
+
+/**
+ * Result of preparing markdown for annotated PDF
+ */
+export interface AnnotatedPdfResult {
+  markdown: string;
+  preamble: string;
+  commentCount: number;
+}
+
 /**
  * Prepare markdown for PDF with visible comments
  * Converts comments to margin notes and optionally shows track changes
  *
- * @param {string} markdown
- * @param {object} options - { showTrackChanges: boolean, useTodonotes: boolean }
- * @returns {{markdown: string, preamble: string, commentCount: number}}
+ * @param markdown - Markdown content
+ * @param options - { showTrackChanges: boolean, useTodonotes: boolean }
+ * @returns Converted markdown with preamble and comment count
  */
-export function prepareMarkdownForAnnotatedPdf(markdown, options = {}) {
+export function prepareMarkdownForAnnotatedPdf(
+  markdown: string,
+  options: AnnotatedPdfOptions = {}
+): AnnotatedPdfResult {
   const { showTrackChanges = false, useTodonotes = true, stripResolved = true } = options;
 
   let result = markdown;

package/lib/{pdf-import.js → pdf-import.ts}

@@ -22,13 +22,82 @@ const COMMENT_TYPES = [
   'Popup',     // Popup comments (attached to other annotations)
 ];
 
+/**
+ * Raw PDF annotation extracted from pdf-lib
+ */
+export interface PdfAnnotation {
+  type: string;
+  page: number;
+  contents: string;
+  author: string;
+  date: string;
+  rect: number[];
+  quadPoints: number[];
+}
+
+/**
+ * PDF comment converted to CriticMarkup format
+ */
+export interface PdfComment {
+  author: string;
+  text: string;
+  page: number;
+  type: string;
+  date?: string;
+}
+
+/**
+ * PDF annotation with extracted highlighted text
+ */
+export interface PdfAnnotationWithText extends PdfAnnotation {
+  highlightedText: string;
+}
+
+/**
+ * Options for PDF extraction
+ */
+export interface ExtractOptions {
+  timeout?: number;
+}
+
+/**
+ * Options for markdown insertion
+ */
+export interface InsertOptions {
+  sectionPerPage?: boolean;
+}
+
+/**
+ * Statistics about PDF comments
+ */
+export interface PdfCommentStats {
+  total: number;
+  byType: Record<string, number>;
+  byAuthor: Record<string, number>;
+  byPage: Record<number, number>;
+}
+
+/**
+ * Text item from pdfjs-dist
+ */
+interface PdfTextItem {
+  str: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
 /**
  * Extract raw annotations from a PDF file
- * @param {string} pdfPath - Path to PDF file
- * @param {object} options - { timeout: number (ms) }
- * @returns {Promise<Array<{type: string, page: number, contents: string, author: string, date: string, rect: number[], quadPoints: number[]}>>}
+ * @param pdfPath - Path to PDF file
+ * @param options - { timeout: number (ms) }
+ * @returns Array of PDF annotations
  */
-export async function extractPdfAnnotations(pdfPath, options = {}) {
+export async function extractPdfAnnotations(
+  pdfPath: string,
+  options: ExtractOptions = {}
+): Promise<PdfAnnotation[]> {
   const { timeout = 30000 } = options;
 
   // Validate file exists
@@ -36,32 +105,34 @@ export async function extractPdfAnnotations(pdfPath, options = {}) {
     throw new Error(`File not found: ${pdfPath}`);
   }
 
-  let pdfBytes;
+  let pdfBytes: Buffer;
   try {
     pdfBytes = fs.readFileSync(pdfPath);
   } catch (err) {
-    throw new Error(`Cannot read PDF file: ${err.message}`);
+    const error = err as Error;
+    throw new Error(`Cannot read PDF file: ${error.message}`);
   }
 
   // Create a promise that rejects after timeout
-  const timeoutPromise = new Promise((_, reject) => {
+  const timeoutPromise = new Promise<never>((_, reject) => {
     setTimeout(() => reject(new Error(`PDF extraction timed out after ${timeout / 1000}s`)), timeout);
   });
 
-  let pdfDoc;
+  let pdfDoc: PDFDocument;
   try {
     pdfDoc = await Promise.race([
       PDFDocument.load(pdfBytes, { ignoreEncryption: true }),
       timeoutPromise,
     ]);
   } catch (err) {
-    if (err.message.includes('timed out')) {
-      throw err;
+    const error = err as Error;
+    if (error.message.includes('timed out')) {
+      throw error;
     }
-    throw new Error(`Invalid or corrupted PDF file: ${err.message}`);
+    throw new Error(`Invalid or corrupted PDF file: ${error.message}`);
   }
 
-  const annotations = [];
+  const annotations: PdfAnnotation[] = [];
   const pages = pdfDoc.getPages();
 
   for (let pageNum = 0; pageNum < pages.length; pageNum++) {
@@ -74,7 +145,7 @@ export async function extractPdfAnnotations(pdfPath, options = {}) {
 
     for (const annotRef of annotRefs) {
       try {
-        const annot = annotRef.dict || annotRef;
+        const annot = (annotRef as any).dict || annotRef;
         if (!annot) continue;
 
         // Get annotation type
@@ -98,11 +169,11 @@ export async function extractPdfAnnotations(pdfPath, options = {}) {
 
         // Extract rectangle (position on page)
         const rectObj = annot.get(pdfDoc.context.obj('Rect'));
-        const rect = rectObj?.asArray?.()?.map(n => n?.asNumber?.() || 0) || [0, 0, 0, 0];
+        const rect = rectObj?.asArray?.()?.map((n: any) => n?.asNumber?.() || 0) || [0, 0, 0, 0];
 
         // Extract QuadPoints for highlights (the actual text bounds)
         const quadObj = annot.get(pdfDoc.context.obj('QuadPoints'));
-        const quadPoints = quadObj?.asArray?.()?.map(n => n?.asNumber?.() || 0) || [];
+        const quadPoints = quadObj?.asArray?.()?.map((n: any) => n?.asNumber?.() || 0) || [];
 
         // Skip empty annotations
         if (!contents.trim() && subtype !== 'StrikeOut') continue;
@@ -135,10 +206,10 @@ export async function extractPdfAnnotations(pdfPath, options = {}) {
 
 /**
  * Parse PDF date string (D:YYYYMMDDHHmmSS format)
- * @param {string} dateStr
- * @returns {string} ISO date string
+ * @param dateStr - PDF date string
+ * @returns ISO date string
  */
-function parsePdfDate(dateStr) {
+function parsePdfDate(dateStr: string): string {
   if (!dateStr) return '';
 
   // Remove D: prefix and timezone info
@@ -156,10 +227,10 @@ function parsePdfDate(dateStr) {
 
 /**
  * Clean PDF string (remove parentheses, decode escape sequences)
- * @param {string} str
- * @returns {string}
+ * @param str - Raw PDF string
+ * @returns Cleaned string
  */
-function cleanPdfString(str) {
+function cleanPdfString(str: string): string {
   if (!str) return '';
 
   return str
@@ -176,10 +247,10 @@ function cleanPdfString(str) {
 
 /**
  * Convert PDF annotations to CriticMarkup comments
- * @param {Array} annotations - From extractPdfAnnotations
- * @returns {Array<{author: string, text: string, page: number, type: string}>}
+ * @param annotations - From extractPdfAnnotations
+ * @returns Array of PDF comments
  */
-export function annotationsToComments(annotations) {
+export function annotationsToComments(annotations: PdfAnnotation[]): PdfComment[] {
   return annotations
     .filter(a => a.contents.trim())
     .map(a => ({
@@ -193,10 +264,10 @@ export function annotationsToComments(annotations) {
 
 /**
  * Extract comments from PDF and format for display
- * @param {string} pdfPath
- * @returns {Promise<Array<{author: string, text: string, page: number, type: string, date: string}>>}
+ * @param pdfPath - Path to PDF file
+ * @returns Array of PDF comments
  */
-export async function extractPdfComments(pdfPath) {
+export async function extractPdfComments(pdfPath: string): Promise<PdfComment[]> {
   const annotations = await extractPdfAnnotations(pdfPath);
   return annotationsToComments(annotations);
 }
@@ -206,32 +277,36 @@ export async function extractPdfComments(pdfPath) {
  * Since PDFs don't have direct text anchors like Word, we use page numbers
  * and append comments to the end of corresponding sections
  *
- * @param {string} markdown - The markdown content
- * @param {Array} comments - Comments from extractPdfComments
- * @param {object} options - { sectionPerPage: boolean }
- * @returns {string} Markdown with comments inserted
+ * @param markdown - The markdown content
+ * @param comments - Comments from extractPdfComments
+ * @param options - { sectionPerPage: boolean }
+ * @returns Markdown with comments inserted
  */
-export function insertPdfCommentsIntoMarkdown(markdown, comments, options = {}) {
+export function insertPdfCommentsIntoMarkdown(
+  markdown: string,
+  comments: PdfComment[],
+  options: InsertOptions = {}
+): string {
   if (comments.length === 0) return markdown;
 
   // Group comments by page
-  const commentsByPage = new Map();
+  const commentsByPage = new Map<number, PdfComment[]>();
   for (const c of comments) {
     if (!commentsByPage.has(c.page)) {
       commentsByPage.set(c.page, []);
     }
-    commentsByPage.get(c.page).push(c);
+    commentsByPage.get(c.page)!.push(c);
   }
 
   // Strategy: Append all comments at the end with page references
   // This is the safest approach since we can't reliably map PDF positions to markdown
   const lines = markdown.split('\n');
-  const commentBlock = [];
+  const commentBlock: string[] = [];
 
   commentBlock.push('');
   commentBlock.push('<!-- PDF Comments -->');
 
-  for (const [page, pageComments] of commentsByPage) {
+  for (const [page, pageComments] of Array.from(commentsByPage.entries())) {
     for (const c of pageComments) {
       const authorPrefix = c.author ? `${c.author}: ` : '';
       const pageRef = `[p.${page}]`;
@@ -244,15 +319,15 @@ export function insertPdfCommentsIntoMarkdown(markdown, comments, options = {})
 
 /**
  * Format PDF comments for CLI display
- * @param {Array} comments
- * @returns {string}
+ * @param comments - Array of PDF comments
+ * @returns Formatted string
  */
-export function formatPdfComments(comments) {
+export function formatPdfComments(comments: PdfComment[]): string {
   if (comments.length === 0) {
     return 'No comments found in PDF.';
   }
 
-  const lines = [];
+  const lines: string[] = [];
   let currentPage = 0;
 
   for (const c of comments) {
@@ -272,10 +347,10 @@ export function formatPdfComments(comments) {
 
 /**
  * Get icon for annotation type
- * @param {string} type
- * @returns {string}
+ * @param type - Annotation type
+ * @returns Icon string
  */
-function getTypeIcon(type) {
+function getTypeIcon(type: string): string {
   switch (type) {
     case 'Text': return '📝';      // Sticky note
     case 'FreeText': return '💬';  // Text box
@@ -289,11 +364,11 @@ function getTypeIcon(type) {
 
 /**
  * Get statistics about PDF comments
- * @param {Array} comments
- * @returns {{total: number, byType: object, byAuthor: object, byPage: object}}
+ * @param comments - Array of PDF comments
+ * @returns Statistics object
  */
-export function getPdfCommentStats(comments) {
-  const stats = {
+export function getPdfCommentStats(comments: PdfComment[]): PdfCommentStats {
+  const stats: PdfCommentStats = {
     total: comments.length,
     byType: {},
     byAuthor: {},
@@ -311,12 +386,12 @@ export function getPdfCommentStats(comments) {
 
 /**
  * Extract text content from a PDF page
- * @param {object} page - pdfjs page object
- * @returns {Promise<Array<{str: string, x: number, y: number, width: number, height: number}>>}
+ * @param page - pdfjs page object
+ * @returns Array of text items with positions
  */
-async function getPageTextItems(page) {
+async function getPageTextItems(page: any): Promise<PdfTextItem[]> {
   const textContent = await page.getTextContent();
-  return textContent.items.map(item => ({
+  return textContent.items.map((item: any) => ({
     str: item.str,
     x: item.transform[4],
     y: item.transform[5],
@@ -328,12 +403,12 @@ async function getPageTextItems(page) {
 /**
  * Check if a point is inside a quadrilateral defined by QuadPoints
  * QuadPoints format: [x1,y1, x2,y2, x3,y3, x4,y4] for each quad
- * @param {number} x
- * @param {number} y
- * @param {number[]} quad - 8 numbers defining corners
- * @returns {boolean}
+ * @param x - X coordinate
+ * @param y - Y coordinate
+ * @param quad - 8 numbers defining corners
+ * @returns True if point is inside quad
  */
-function isPointInQuad(x, y, quad) {
+function isPointInQuad(x: number, y: number, quad: number[]): boolean {
   if (quad.length < 8) return false;
 
   // Get bounding box from quad points
@@ -349,11 +424,14 @@ function isPointInQuad(x, y, quad) {
 
 /**
  * Extract highlighted text from a PDF using QuadPoints
- * @param {string} pdfPath - Path to PDF file
- * @param {Array} annotations - Annotations with quadPoints from extractPdfAnnotations
- * @returns {Promise<Array<{...annotation, highlightedText: string}>>}
+ * @param pdfPath - Path to PDF file
+ * @param annotations - Annotations with quadPoints from extractPdfAnnotations
+ * @returns Annotations with highlighted text extracted
  */
-export async function extractHighlightedText(pdfPath, annotations) {
+export async function extractHighlightedText(
+  pdfPath: string,
+  annotations: PdfAnnotation[]
+): Promise<PdfAnnotationWithText[]> {
   const pdfBytes = fs.readFileSync(pdfPath);
   const data = new Uint8Array(pdfBytes);
 
@@ -362,7 +440,7 @@ export async function extractHighlightedText(pdfPath, annotations) {
   const loadingTask = getDocument({ data, useSystemFonts: true });
   const pdfDoc = await loadingTask.promise;
 
-  const results = [];
+  const results: PdfAnnotationWithText[] = [];
 
   for (const annot of annotations) {
     // Only process text markup annotations (Highlight, Underline, StrikeOut, Squiggly)
@@ -381,13 +459,13 @@ export async function extractHighlightedText(pdfPath, annotations) {
       const textItems = await getPageTextItems(page);
 
       // Split quadPoints into individual quads (8 numbers each)
-      const quads = [];
+      const quads: number[][] = [];
       for (let i = 0; i < annot.quadPoints.length; i += 8) {
         quads.push(annot.quadPoints.slice(i, i + 8));
       }
 
       // Find text items that fall within any of the quads
-      const matchedText = [];
+      const matchedText: string[] = [];
       for (const item of textItems) {
         // Check if text item center is in any quad
         const centerX = item.x + (item.width || 0) / 2;
@@ -416,23 +494,23 @@ export async function extractHighlightedText(pdfPath, annotations) {
 
 /**
  * Extract annotations with highlighted text in one call
- * @param {string} pdfPath
- * @returns {Promise<Array>}
+ * @param pdfPath - Path to PDF file
+ * @returns Annotations with highlighted text
  */
-export async function extractPdfAnnotationsWithText(pdfPath) {
+export async function extractPdfAnnotationsWithText(pdfPath: string): Promise<PdfAnnotationWithText[]> {
   const annotations = await extractPdfAnnotations(pdfPath);
   return extractHighlightedText(pdfPath, annotations);
 }
 
 /**
  * Format annotation with highlighted text for display
- * @param {object} annot - Annotation with highlightedText
- * @returns {string}
+ * @param annot - Annotation with highlightedText
+ * @returns Formatted string
  */
-export function formatAnnotationWithText(annot) {
+export function formatAnnotationWithText(annot: PdfAnnotationWithText): string {
   const typeIcon = getTypeIcon(annot.type);
   const author = annot.author || 'Unknown';
-  const parts = [`${typeIcon} [${author}]`];
+  const parts: string[] = [`${typeIcon} [${author}]`];
 
   if (annot.highlightedText) {
     parts.push(`"${annot.highlightedText}"`);