docrev 0.8.1 → 0.8.5

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

@@ -7,12 +7,12 @@ import { execSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { diffWords } from 'diff';
+import type { FileChange, CommitInfo, ChangedFile, BlameEntry, AuthorStats, ContributorStats } from './types.js';
 
 /**
  * Check if current directory is a git repository
- * @returns {boolean}
  */
-export function isGitRepo() {
+export function isGitRepo(): boolean {
   try {
     execSync('git rev-parse --is-inside-work-tree', { stdio: 'pipe' });
     return true;
@@ -23,9 +23,8 @@ export function isGitRepo() {
 
 /**
  * Get the current git branch
- * @returns {string|null}
  */
-export function getCurrentBranch() {
+export function getCurrentBranch(): string | null {
   try {
     return execSync('git rev-parse --abbrev-ref HEAD', { stdio: 'pipe' })
       .toString()
@@ -37,15 +36,14 @@ export function getCurrentBranch() {
 
 /**
  * Get the default branch (main or master)
- * @returns {string}
  */
-export function getDefaultBranch() {
+export function getDefaultBranch(): string {
   try {
     // Try to get the remote default branch
     const remote = execSync('git remote show origin', { stdio: 'pipe' })
       .toString();
     const match = remote.match(/HEAD branch:\s*(\S+)/);
-    if (match) return match[1];
+    if (match?.[1]) return match[1];
   } catch {
     // Fall through
   }
@@ -66,11 +64,10 @@ export function getDefaultBranch() {
 
 /**
  * Get file content from a specific git ref
- * @param {string} filePath
- * @param {string} ref - Git reference (branch, tag, commit)
- * @returns {string|null}
+ * @param filePath - Path to file
+ * @param ref - Git reference (branch, tag, commit)
  */
-export function getFileAtRef(filePath, ref) {
+export function getFileAtRef(filePath: string, ref: string): string | null {
   try {
     return execSync(`git show ${ref}:${filePath}`, { stdio: 'pipe' }).toString();
   } catch {
@@ -80,11 +77,10 @@ export function getFileAtRef(filePath, ref) {
 
 /**
  * Get list of changed files between refs
- * @param {string} fromRef
- * @param {string} toRef - Default: HEAD
- * @returns {Array<{file: string, status: string}>}
+ * @param fromRef - Starting reference
+ * @param toRef - Ending reference (default: HEAD)
  */
-export function getChangedFiles(fromRef, toRef = 'HEAD') {
+export function getChangedFiles(fromRef: string, toRef: string = 'HEAD'): ChangedFile[] {
   try {
     const output = execSync(`git diff --name-status ${fromRef}..${toRef}`, { stdio: 'pipe' })
       .toString()
@@ -93,10 +89,12 @@ export function getChangedFiles(fromRef, toRef = 'HEAD') {
     if (!output) return [];
 
     return output.split('\n').map(line => {
-      const [status, file] = line.split('\t');
+      const parts = line.split('\t');
+      const status = parts[0];
+      const file = parts[1] ?? '';
       return {
         file,
-        status: status === 'A' ? 'added' : status === 'D' ? 'deleted' : 'modified',
+        status: (status === 'A' ? 'added' : status === 'D' ? 'deleted' : 'modified') as 'added' | 'deleted' | 'modified',
       };
     });
   } catch {
@@ -106,11 +104,10 @@ export function getChangedFiles(fromRef, toRef = 'HEAD') {
 
 /**
  * Get commit history for a file
- * @param {string} filePath
- * @param {number} limit
- * @returns {Array<{hash: string, date: string, message: string}>}
+ * @param filePath - Path to file
+ * @param limit - Maximum number of commits to return
  */
-export function getFileHistory(filePath, limit = 10) {
+export function getFileHistory(filePath: string, limit: number = 10): CommitInfo[] {
   try {
     const output = execSync(
       `git log --format="%h|%ci|%s" -n ${limit} -- "${filePath}"`,
@@ -120,8 +117,13 @@ export function getFileHistory(filePath, limit = 10) {
     if (!output) return [];
 
     return output.split('\n').map(line => {
-      const [hash, date, message] = line.split('|');
-      return { hash, date, message };
+      const parts = line.split('|');
+      return {
+        hash: parts[0] ?? '',
+        date: parts[1] ?? '',
+        message: parts[2] ?? '',
+        author: ''
+      };
     });
   } catch {
     return [];
@@ -130,12 +132,11 @@ export function getFileHistory(filePath, limit = 10) {
 
 /**
  * Compare file content between two refs
- * @param {string} filePath
- * @param {string} fromRef
- * @param {string} toRef
- * @returns {{added: number, removed: number, changes: Array}}
+ * @param filePath - Path to file
+ * @param fromRef - Starting reference
+ * @param toRef - Ending reference (default: HEAD)
  */
-export function compareFileVersions(filePath, fromRef, toRef = 'HEAD') {
+export function compareFileVersions(filePath: string, fromRef: string, toRef: string = 'HEAD'): FileChange {
   const oldContent = getFileAtRef(filePath, fromRef) || '';
   const newContent = toRef === 'HEAD'
     ? fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf-8') : ''
@@ -145,15 +146,15 @@ export function compareFileVersions(filePath, fromRef, toRef = 'HEAD') {
 
   let added = 0;
   let removed = 0;
-  const changes = [];
+  const changes: Array<{ added?: boolean; removed?: boolean; value: string }> = [];
 
   for (const part of diffs) {
     if (part.added) {
       added += part.value.split(/\s+/).filter(w => w).length;
-      changes.push({ type: 'add', text: part.value });
+      changes.push({ added: true, value: part.value });
     } else if (part.removed) {
       removed += part.value.split(/\s+/).filter(w => w).length;
-      changes.push({ type: 'remove', text: part.value });
+      changes.push({ removed: true, value: part.value });
     }
   }
 
@@ -162,15 +163,18 @@ export function compareFileVersions(filePath, fromRef, toRef = 'HEAD') {
 
 /**
  * Get word count difference between refs
- * @param {string[]} files
- * @param {string} fromRef
- * @param {string} toRef
- * @returns {{total: {added: number, removed: number}, byFile: Object}}
+ * @param files - Array of file paths
+ * @param fromRef - Starting reference
+ * @param toRef - Ending reference (default: HEAD)
  */
-export function getWordCountDiff(files, fromRef, toRef = 'HEAD') {
+export function getWordCountDiff(
+  files: string[],
+  fromRef: string,
+  toRef: string = 'HEAD'
+): { total: { added: number; removed: number }; byFile: Record<string, { added: number; removed: number }> } {
   let totalAdded = 0;
   let totalRemoved = 0;
-  const byFile = {};
+  const byFile: Record<string, { added: number; removed: number }> = {};
 
   for (const file of files) {
     const { added, removed } = compareFileVersions(file, fromRef, toRef);
@@ -187,10 +191,9 @@ export function getWordCountDiff(files, fromRef, toRef = 'HEAD') {
 
 /**
  * Get recent commits
- * @param {number} limit
- * @returns {Array<{hash: string, date: string, message: string, author: string}>}
+ * @param limit - Maximum number of commits to return
  */
-export function getRecentCommits(limit = 10) {
+export function getRecentCommits(limit: number = 10): CommitInfo[] {
   try {
     const output = execSync(
       `git log --format="%h|%ci|%an|%s" -n ${limit}`,
@@ -200,8 +203,13 @@ export function getRecentCommits(limit = 10) {
     if (!output) return [];
 
     return output.split('\n').map(line => {
-      const [hash, date, author, message] = line.split('|');
-      return { hash, date, author, message };
+      const parts = line.split('|');
+      return {
+        hash: parts[0] ?? '',
+        date: parts[1] ?? '',
+        author: parts[2] ?? '',
+        message: parts[3] ?? ''
+      };
     });
   } catch {
     return [];
@@ -210,9 +218,8 @@ export function getRecentCommits(limit = 10) {
 
 /**
  * Check if there are uncommitted changes
- * @returns {boolean}
  */
-export function hasUncommittedChanges() {
+export function hasUncommittedChanges(): boolean {
   try {
     const output = execSync('git status --porcelain', { stdio: 'pipe' }).toString();
     return output.trim().length > 0;
@@ -223,9 +230,8 @@ export function hasUncommittedChanges() {
 
 /**
  * Get tags
- * @returns {string[]}
  */
-export function getTags() {
+export function getTags(): string[] {
   try {
     return execSync('git tag --sort=-creatordate', { stdio: 'pipe' })
       .toString()
@@ -240,10 +246,9 @@ export function getTags() {
 /**
  * Get blame information for a file
  * Returns author and commit info for each line
- * @param {string} filePath
- * @returns {Array<{line: number, author: string, date: string, hash: string, content: string}>}
+ * @param filePath - Path to file
  */
-export function getFileBlame(filePath) {
+export function getFileBlame(filePath: string): BlameEntry[] {
   try {
     const output = execSync(
       `git blame --line-porcelain "${filePath}"`,
@@ -251,16 +256,16 @@ export function getFileBlame(filePath) {
     ).toString();
 
     const lines = output.split('\n');
-    const result = [];
-    let current = {};
+    const result: BlameEntry[] = [];
+    let current: Partial<BlameEntry> = {};
     let lineNumber = 0;
 
     for (const line of lines) {
       if (/^[0-9a-f]{40}/.test(line)) {
         // New blame entry: hash original-line final-line [count]
         const parts = line.split(' ');
-        current.hash = parts[0].slice(0, 7);
-        lineNumber = parseInt(parts[2], 10);
+        current.hash = parts[0]?.slice(0, 7) ?? '';
+        lineNumber = parseInt(parts[2] ?? '0', 10);
       } else if (line.startsWith('author ')) {
         current.author = line.slice(7);
       } else if (line.startsWith('author-time ')) {
@@ -270,7 +275,7 @@ export function getFileBlame(filePath) {
         // Actual content line (prefixed with tab)
         current.content = line.slice(1);
         current.line = lineNumber;
-        result.push({ ...current });
+        result.push(current as BlameEntry);
         current = {};
       }
     }
@@ -283,20 +288,19 @@ export function getFileBlame(filePath) {
 
 /**
  * Get author statistics for a file
- * @param {string} filePath
- * @returns {Object<string, {lines: number, percentage: number}>}
+ * @param filePath - Path to file
  */
-export function getAuthorStats(filePath) {
+export function getAuthorStats(filePath: string): Record<string, AuthorStats> {
   const blame = getFileBlame(filePath);
   if (blame.length === 0) return {};
 
-  const counts = {};
+  const counts: Record<string, number> = {};
   for (const entry of blame) {
     counts[entry.author] = (counts[entry.author] || 0) + 1;
   }
 
   const total = blame.length;
-  const stats = {};
+  const stats: Record<string, AuthorStats> = {};
   for (const [author, lines] of Object.entries(counts)) {
     stats[author] = {
       lines,
@@ -309,11 +313,10 @@ export function getAuthorStats(filePath) {
 
 /**
  * Get contributors across multiple files
- * @param {string[]} files
- * @returns {Object<string, {lines: number, files: number}>}
+ * @param files - Array of file paths
  */
-export function getContributors(files) {
-  const contributors = {};
+export function getContributors(files: string[]): Record<string, ContributorStats> {
+  const contributors: Record<string, ContributorStats> = {};
 
   for (const file of files) {
     const stats = getAuthorStats(file);

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

@@ -13,10 +13,41 @@ import * as path from 'path';
 // Default dictionary location
 const DEFAULT_DICT_NAME = '.rev-dictionary';
 
+interface GrammarRule {
+  id: string;
+  pattern: RegExp;
+  message: string;
+  severity: 'error' | 'warning' | 'info';
+  check?: (match: string) => boolean;
+}
+
+interface GrammarIssue {
+  rule: string;
+  message: string;
+  severity: 'error' | 'warning' | 'info';
+  line: number;
+  column: number;
+  match: string;
+  context: string;
+}
+
+interface GrammarSummary {
+  total: number;
+  errors: number;
+  warnings: number;
+  info: number;
+  byRule: Record<string, number>;
+}
+
+interface CheckGrammarOptions {
+  scientific?: boolean;
+  directory?: string;
+}
+
 /**
  * Common grammar/style rules
  */
-const GRAMMAR_RULES = [
+const GRAMMAR_RULES: GrammarRule[] = [
   {
     id: 'passive-voice',
     pattern: /\b(is|are|was|were|be|been|being)\s+(being\s+)?\w+ed\b/gi,
@@ -50,7 +81,7 @@ const GRAMMAR_RULES = [
   {
     id: 'sentence-length',
     pattern: /[^.!?]*[.!?]/g,
-    check: (match) => {
+    check: (match: string): boolean => {
       const words = match.trim().split(/\s+/).length;
       return words > 40;
     },
@@ -80,7 +111,7 @@ const GRAMMAR_RULES = [
 /**
  * Scientific writing specific rules
  */
-const SCIENTIFIC_RULES = [
+const SCIENTIFIC_RULES: GrammarRule[] = [
   {
     id: 'first-person',
     pattern: /\b(I|we|my|our)\b/gi,
@@ -109,12 +140,10 @@ const SCIENTIFIC_RULES = [
 
 /**
  * Load custom dictionary from file
- * @param {string} directory - Directory to search for dictionary
- * @returns {Set<string>} Set of custom words
  */
-export function loadDictionary(directory = '.') {
+export function loadDictionary(directory: string = '.'): Set<string> {
   const dictPath = path.join(directory, DEFAULT_DICT_NAME);
-  const words = new Set();
+  const words = new Set<string>();
 
   if (fs.existsSync(dictPath)) {
     const content = fs.readFileSync(dictPath, 'utf-8');
@@ -133,10 +162,8 @@ export function loadDictionary(directory = '.') {
 
 /**
  * Save custom dictionary to file
- * @param {Set<string>} words - Set of words
- * @param {string} directory - Directory to save dictionary
  */
-export function saveDictionary(words, directory = '.') {
+export function saveDictionary(words: Set<string>, directory: string = '.'): void {
   const dictPath = path.join(directory, DEFAULT_DICT_NAME);
 
   const header = `# Custom dictionary for docrev
@@ -150,11 +177,8 @@ export function saveDictionary(words, directory = '.') {
 
 /**
  * Add word to custom dictionary
- * @param {string} word - Word to add
- * @param {string} directory - Directory containing dictionary
- * @returns {boolean} True if word was added (not already present)
  */
-export function addToDictionary(word, directory = '.') {
+export function addToDictionary(word: string, directory: string = '.'): boolean {
   const words = loadDictionary(directory);
   const normalizedWord = word.trim().toLowerCase();
 
@@ -169,11 +193,8 @@ export function addToDictionary(word, directory = '.') {
 
 /**
  * Remove word from custom dictionary
- * @param {string} word - Word to remove
- * @param {string} directory - Directory containing dictionary
- * @returns {boolean} True if word was removed
  */
-export function removeFromDictionary(word, directory = '.') {
+export function removeFromDictionary(word: string, directory: string = '.'): boolean {
   const words = loadDictionary(directory);
   const normalizedWord = word.trim().toLowerCase();
 
@@ -188,16 +209,11 @@ export function removeFromDictionary(word, directory = '.') {
 
 /**
  * Check text for grammar/style issues
- * @param {string} text - Text to check
- * @param {object} options - Options
- * @param {boolean} options.scientific - Include scientific writing rules
- * @param {string} options.directory - Directory for custom dictionary
- * @returns {Array<{rule: string, message: string, severity: string, line: number, match: string}>}
  */
-export function checkGrammar(text, options = {}) {
+export function checkGrammar(text: string, options: CheckGrammarOptions = {}): GrammarIssue[] {
   const { scientific = true, directory = '.' } = options;
   const customDict = loadDictionary(directory);
-  const issues = [];
+  const issues: GrammarIssue[] = [];
 
   // Get all rules
   const rules = scientific ? [...GRAMMAR_RULES, ...SCIENTIFIC_RULES] : GRAMMAR_RULES;
@@ -207,6 +223,7 @@ export function checkGrammar(text, options = {}) {
 
   for (let lineNum = 0; lineNum < lines.length; lineNum++) {
     const line = lines[lineNum];
+    if (!line) continue;
 
     // Skip code blocks and YAML frontmatter
     if (line.trim().startsWith('```') || line.trim().startsWith('---')) {
@@ -252,11 +269,9 @@ export function checkGrammar(text, options = {}) {
 
 /**
  * Get grammar check summary
- * @param {Array} issues - List of issues from checkGrammar
- * @returns {object} Summary stats
  */
-export function getGrammarSummary(issues) {
-  const summary = {
+export function getGrammarSummary(issues: GrammarIssue[]): GrammarSummary {
+  const summary: GrammarSummary = {
     total: issues.length,
     errors: 0,
     warnings: 0,
@@ -277,10 +292,8 @@ export function getGrammarSummary(issues) {
 
 /**
  * List available grammar rules
- * @param {boolean} scientific - Include scientific rules
- * @returns {Array<{id: string, message: string, severity: string}>}
  */
-export function listRules(scientific = true) {
+export function listRules(scientific: boolean = true): Array<{ id: string; message: string; severity: string }> {
   const rules = scientific ? [...GRAMMAR_RULES, ...SCIENTIFIC_RULES] : GRAMMAR_RULES;
   return rules.map(r => ({
     id: r.id,

package/lib/image-registry.ts

@@ -0,0 +1,180 @@
+/**
+ * Image registry utilities for tracking figures and tables in markdown documents
+ *
+ * The registry maps figure/table labels and display numbers to source paths,
+ * enabling Word import to match rendered figures back to original sources.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Image registry entry
+ */
+interface ImageEntry {
+  caption: string;
+  path: string;
+  label: string | null;
+  type: 'fig' | 'tbl';
+  number?: string;
+}
+
+/**
+ * Image registry
+ */
+interface ImageRegistry {
+  figures: ImageEntry[];
+  byLabel: Map<string, ImageEntry>;
+  byNumber: Map<string, ImageEntry>;
+  byCaption: Map<string, ImageEntry>;
+}
+
+/**
+ * Crossref registry info
+ */
+interface CrossrefInfo {
+  num: number;
+  isSupp: boolean;
+}
+
+/**
+ * Crossref registry
+ */
+interface CrossrefRegistry {
+  figures: Map<string, CrossrefInfo>;
+  tables: Map<string, CrossrefInfo>;
+}
+
+/**
+ * Saved registry data
+ */
+interface RegistryData {
+  version: number;
+  created: string;
+  figures: ImageEntry[];
+}
+
+/**
+ * Pattern to extract markdown images with optional pandoc-crossref anchors
+ * Captures: ![caption](path){#fig:label} or ![caption](path)
+ * Groups: [1] = caption, [2] = path, [3] = label type (fig/tbl), [4] = label
+ */
+export const IMAGE_PATTERN = /!\[([^\]]*)\]\(([^)]+)\)(?:\{#(fig|tbl):([^}]+)\})?/g;
+
+/**
+ * Build image registry from markdown content
+ * Maps figure labels and display numbers to source paths
+ */
+export function buildImageRegistry(
+  content: string,
+  crossrefRegistry: CrossrefRegistry | null = null
+): ImageRegistry {
+  const figures: ImageEntry[] = [];
+  const byLabel = new Map<string, ImageEntry>();
+  const byNumber = new Map<string, ImageEntry>();
+  const byCaption = new Map<string, ImageEntry>();
+
+  IMAGE_PATTERN.lastIndex = 0;
+  let match: RegExpExecArray | null;
+
+  while ((match = IMAGE_PATTERN.exec(content)) !== null) {
+    const caption = match[1];
+    const imagePath = match[2];
+    const labelType = match[3] as 'fig' | 'tbl' | undefined; // 'fig' or 'tbl' or undefined
+    const label = match[4]; // label without prefix
+
+    const entry: ImageEntry = {
+      caption,
+      path: imagePath,
+      label: label || null,
+      type: labelType || 'fig',
+    };
+
+    // Add display number if we have a crossref registry
+    if (label && crossrefRegistry) {
+      const info = crossrefRegistry.figures.get(label) || crossrefRegistry.tables.get(label);
+      if (info) {
+        entry.number = info.isSupp ? `S${info.num}` : `${info.num}`;
+        byNumber.set(`${entry.type}:${entry.number}`, entry);
+      }
+    }
+
+    figures.push(entry);
+
+    if (label) {
+      byLabel.set(`${labelType || 'fig'}:${label}`, entry);
+    }
+
+    // Index by first 50 chars of caption for fuzzy matching
+    if (caption) {
+      const captionKey = caption.slice(0, 50).toLowerCase().trim();
+      byCaption.set(captionKey, entry);
+    }
+  }
+
+  return { figures, byLabel, byNumber, byCaption };
+}
+
+/**
+ * Write image registry to .rev directory
+ */
+export function writeImageRegistry(directory: string, registry: ImageRegistry): string {
+  const revDir = path.join(directory, '.rev');
+  if (!fs.existsSync(revDir)) {
+    fs.mkdirSync(revDir, { recursive: true });
+  }
+
+  // Convert Maps to objects for JSON serialization
+  const data: RegistryData = {
+    version: 1,
+    created: new Date().toISOString(),
+    figures: registry.figures,
+  };
+
+  const registryPath = path.join(revDir, 'image-registry.json');
+  fs.writeFileSync(registryPath, JSON.stringify(data, null, 2), 'utf-8');
+
+  return registryPath;
+}
+
+/**
+ * Read image registry from .rev directory
+ */
+export function readImageRegistry(directory: string): (ImageRegistry & RegistryData) | null {
+  const registryPath = path.join(directory, '.rev', 'image-registry.json');
+
+  if (!fs.existsSync(registryPath)) {
+    return null;
+  }
+
+  try {
+    const data = JSON.parse(fs.readFileSync(registryPath, 'utf-8')) as RegistryData;
+
+    // Rebuild lookup maps from figures array
+    const byLabel = new Map<string, ImageEntry>();
+    const byNumber = new Map<string, ImageEntry>();
+    const byCaption = new Map<string, ImageEntry>();
+
+    for (const entry of data.figures || []) {
+      if (entry.label) {
+        byLabel.set(`${entry.type || 'fig'}:${entry.label}`, entry);
+      }
+      if (entry.number) {
+        byNumber.set(`${entry.type || 'fig'}:${entry.number}`, entry);
+      }
+      if (entry.caption) {
+        const captionKey = entry.caption.slice(0, 50).toLowerCase().trim();
+        byCaption.set(captionKey, entry);
+      }
+    }
+
+    return {
+      ...data,
+      byLabel,
+      byNumber,
+      byCaption,
+    };
+  } catch (err) {
+    return null;
+  }
+}