docrev 0.8.1 → 0.8.5

package/lib/commands/{utilities.js → utilities.ts}

@@ -6,6 +6,7 @@
  * Miscellaneous utility commands for project management.
  */
 
+import type { Command } from 'commander';
 import {
   chalk,
   fs,
@@ -19,14 +20,211 @@ import {
   stripAnnotations,
   parseAnnotations,
   getUserName,
+  countWords,
 } from './context.js';
 
+// Use the actual BuildConfig from build.ts which allows string|Author[]
+type BuildConfig = ReturnType<typeof loadBuildConfig>;
+
+// Type definitions for package.json
+interface PackageJson {
+  version?: string;
+  name?: string;
+  [key: string]: unknown;
+}
+
+// Options interfaces
+interface WordCountOptions {
+  limit?: number;
+  journal?: string;
+}
+
+interface StatsOptions {
+  // No options currently
+}
+
+interface SearchOptions {
+  ignoreCase?: boolean;
+  context?: number;
+}
+
+interface BackupOptions {
+  name?: string;
+  output?: string;
+}
+
+interface ArchiveOptions {
+  dir?: string;
+  by?: string;
+  rename?: boolean;
+  dryRun?: boolean;
+}
+
+interface ExportOptions {
+  output?: string;
+  includeOutput?: boolean;
+}
+
+interface PreviewOptions {
+  // No options currently
+}
+
+interface WatchOptions {
+  open?: boolean;
+}
+
+interface LintOptions {
+  fix?: boolean;
+}
+
+interface GrammarOptions {
+  learn?: string;
+  forget?: string;
+  list?: boolean;
+  rules?: boolean;
+  scientific?: boolean;
+  severity?: string;
+}
+
+interface AnnotateOptions {
+  message?: string;
+  search?: string;
+  author?: string;
+}
+
+interface ApplyOptions {
+  author?: string;
+}
+
+interface CommentOptions {
+  author?: string;
+}
+
+interface CleanOptions {
+  dryRun?: boolean;
+  all?: boolean;
+}
+
+interface CheckOptions {
+  fix?: boolean;
+  severity?: string;
+}
+
+interface OpenOptions {
+  // No options currently
+}
+
+interface SpellingOptions {
+  learn?: string;
+  learnProject?: string;
+  forget?: string;
+  forgetProject?: string;
+  list?: boolean;
+  listProject?: boolean;
+  listAll?: boolean;
+  british?: boolean;
+  addNames?: boolean;
+}
+
+interface UpgradeOptions {
+  check?: boolean;
+}
+
+interface BatchOptions {
+  parallel?: boolean;
+  dryRun?: boolean;
+  all?: boolean;
+}
+
+// Comment interface
+interface Comment {
+  text: string;
+  resolved: boolean;
+  author?: string;
+}
+
+// Annotation interface
+interface Annotation {
+  type: string;
+  text: string;
+}
+
+// Grammar issue interface (from grammar.ts)
+interface GrammarIssue {
+  rule: string;
+  severity: 'error' | 'warning' | 'info';
+  message: string;
+  line: number;
+  column: number;
+  match: string;
+  context: string;
+  file?: string;
+}
+
+// Grammar summary interface (from grammar.ts)
+interface GrammarSummary {
+  total: number;
+  errors: number;
+  warnings: number;
+  info: number;
+  byRule?: Record<string, number>;
+}
+
+// Lint issue interface
+interface LintIssue {
+  type: 'error' | 'warning';
+  message: string;
+  fix?: string | null;
+  file?: string;
+}
+
+// Build result interface - matches build.ts export
+interface BuildResult {
+  format: string;
+  success: boolean;
+  outputPath?: string;
+  error?: string;
+}
+
+// Full build result interface - matches build.ts FullBuildResult
+interface FullBuildResult {
+  results: BuildResult[];
+  paperPath: string;
+  warnings: string[];
+  forwardRefsResolved: number;
+  refsAutoInjected?: boolean;
+}
+
+// Spelling issue interface
+interface SpellingIssue {
+  word: string;
+  line: number;
+  suggestions: string[];
+}
+
+// Spelling result interface
+interface SpellingResult {
+  misspelled: SpellingIssue[];
+  possibleNames: SpellingIssue[];
+}
+
+// Batch result interface
+interface BatchResult {
+  file: string;
+  status: string;
+  annotations?: number;
+  comments?: number;
+  pending?: number;
+  total?: number;
+  resolved?: number;
+  stripped?: boolean;
+  error?: string;
+}
+
 /**
  * Register utility commands with the program
- * @param {import('commander').Command} program
- * @param {object} [pkg] - Package.json object for version info
  */
-export function register(program, pkg) {
+export function register(program: Command, pkg?: PackageJson): void {
   // ==========================================================================
   // HELP command - Comprehensive help
   // ==========================================================================
@@ -35,7 +233,7 @@ export function register(program, pkg) {
     .command('help')
     .description('Show detailed help and workflow guide')
     .argument('[topic]', 'Help topic: workflow, syntax, commands')
-    .action((topic) => {
+    .action((topic?: string) => {
       if (!topic || topic === 'all') {
         showFullHelp(pkg);
       } else if (topic === 'workflow') {
@@ -58,7 +256,7 @@ export function register(program, pkg) {
     .command('completions')
     .description('Output shell completions')
     .argument('<shell>', 'Shell type: bash, zsh, powershell')
-    .action((shell) => {
+    .action((shell: string) => {
       const completionsDir = path.join(import.meta.dirname, '..', '..', 'completions');
 
       if (shell === 'bash') {
@@ -102,10 +300,10 @@ export function register(program, pkg) {
     .description('Show word counts per section')
     .option('-l, --limit <number>', 'Warn if total exceeds limit', parseInt)
     .option('-j, --journal <name>', 'Use journal word limit')
-    .action(async (options) => {
-      let config = {};
+    .action(async (options: WordCountOptions) => {
+      let config: Partial<BuildConfig> = {};
       try {
-        config = loadBuildConfig() || {};
+        config = loadBuildConfig('.') || {};
       } catch {
         // Not in a rev project, that's ok
       }
@@ -123,26 +321,8 @@ export function register(program, pkg) {
         sections.push(...mdFiles);
       }
 
-      const countWords = (text) => {
-        return text
-          .replace(/^---[\s\S]*?---/m, '')
-          .replace(/!\[.*?\]\(.*?\)/g, '')
-          .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
-          .replace(/#+\s*/g, '')
-          .replace(/\*\*|__|[*_`]/g, '')
-          .replace(/```[\s\S]*?```/g, '')
-          .replace(/\{[^}]+\}/g, '')
-          .replace(/@\w+:\w+/g, '')
-          .replace(/@\w+/g, '')
-          .replace(/\|[^|]+\|/g, ' ')
-          .replace(/\n+/g, ' ')
-          .trim()
-          .split(/\s+/)
-          .filter(w => w.length > 0).length;
-      };
-
       let total = 0;
-      const rows = [];
+      const rows: string[][] = [];
 
       for (const section of sections) {
         if (!fs.existsSync(section)) continue;
@@ -183,10 +363,10 @@ export function register(program, pkg) {
   program
     .command('stats')
     .description('Show project statistics dashboard')
-    .action(async () => {
-      let config = {};
+    .action(async (_options: StatsOptions) => {
+      let config: Partial<BuildConfig> = {};
       try {
-        config = loadBuildConfig() || {};
+        config = loadBuildConfig('.') || {};
       } catch {
         // Not in a rev project, that's ok
       }
@@ -198,26 +378,12 @@ export function register(program, pkg) {
         );
       }
 
-      const countWords = (text) => {
-        return text
-          .replace(/^---[\s\S]*?---/m, '')
-          .replace(/!\[.*?\]\(.*?\)/g, '')
-          .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
-          .replace(/[#*_`]/g, '')
-          .replace(/\{[^}]+\}/g, '')
-          .replace(/@\w+/g, '')
-          .replace(/\n+/g, ' ')
-          .trim()
-          .split(/\s+/)
-          .filter(w => w.length > 0).length;
-      };
-
       let totalWords = 0;
       let totalFigures = 0;
       let totalTables = 0;
       let totalComments = 0;
       let pendingComments = 0;
-      const citations = new Set();
+      const citations = new Set<string>();
 
       for (const section of sections) {
         if (!fs.existsSync(section)) continue;
@@ -238,7 +404,7 @@ export function register(program, pkg) {
       console.log(fmt.header('Project Statistics'));
       console.log();
 
-      const stats = [
+      const stats: [string, string | number][] = [
         ['Sections', sections.length],
         ['Words', totalWords.toLocaleString()],
         ['Figures', Math.round(totalFigures)],
@@ -272,10 +438,10 @@ export function register(program, pkg) {
     .argument('<query>', 'Search query (supports regex)')
     .option('-i, --ignore-case', 'Case-insensitive search')
     .option('-c, --context <lines>', 'Show context lines', parseInt, 1)
-    .action((query, options) => {
-      let config = {};
+    .action((query: string, options: SearchOptions) => {
+      let config: Partial<BuildConfig> = {};
       try {
-        config = loadBuildConfig() || {};
+        config = loadBuildConfig('.') || {};
       } catch {
         // Not in a rev project, that's ok
       }
@@ -288,7 +454,7 @@ export function register(program, pkg) {
       }
 
       const flags = options.ignoreCase ? 'gi' : 'g';
-      let pattern;
+      let pattern: RegExp;
       try {
         pattern = new RegExp(query, flags);
       } catch {
@@ -302,7 +468,7 @@ export function register(program, pkg) {
         const text = fs.readFileSync(section, 'utf-8');
         const lines = text.split('\n');
 
-        const matches = [];
+        const matches: { line: number; text: string }[] = [];
         for (let i = 0; i < lines.length; i++) {
           if (pattern.test(lines[i])) {
             matches.push({ line: i + 1, text: lines[i] });
@@ -336,13 +502,13 @@ export function register(program, pkg) {
     .description('Create timestamped project backup')
     .option('-n, --name <name>', 'Custom backup name')
     .option('-o, --output <dir>', 'Output directory', '.')
-    .action(async (options) => {
+    .action(async (options: BackupOptions) => {
       const { default: AdmZip } = await import('adm-zip');
       const zip = new AdmZip();
 
       const date = new Date().toISOString().slice(0, 10);
       const name = options.name || `backup-${date}`;
-      const outputPath = path.join(options.output, `${name}.zip`);
+      const outputPath = path.join(options.output || '.', `${name}.zip`);
 
       // Files to exclude
       const excludePatterns = [
@@ -350,14 +516,14 @@ export function register(program, pkg) {
         'paper.md' // Generated file
       ];
 
-      const shouldInclude = (file) => {
+      const shouldInclude = (file: string): boolean => {
         for (const pattern of excludePatterns) {
           if (file.includes(pattern.replace('*', ''))) return false;
         }
         return true;
       };
 
-      const addDir = (dir, zipPath = '') => {
+      const addDir = (dir: string, zipPath = ''): void => {
         const entries = fs.readdirSync(dir, { withFileTypes: true });
         for (const entry of entries) {
           const fullPath = path.join(dir, entry.name);
@@ -401,7 +567,7 @@ export function register(program, pkg) {
     .option('--by <name>', 'Reviewer name (auto-detected if single commenter)')
     .option('--no-rename', 'Keep original filenames')
     .option('--dry-run', 'Preview without moving files')
-    .action(async (files, options) => {
+    .action(async (files: string[] | undefined, options: ArchiveOptions) => {
       const { extractWordComments } = await import('../import.js');
       const { default: YAML } = await import('yaml');
 
@@ -411,7 +577,7 @@ export function register(program, pkg) {
         : findFiles('.docx');
 
       // Exclude our own build outputs
-      let projectSlug = null;
+      let projectSlug: string | null = null;
       const configPath = path.join(process.cwd(), 'rev.yaml');
       if (fs.existsSync(configPath)) {
         try {
@@ -429,7 +595,7 @@ export function register(program, pkg) {
       }
 
       // Filter out build outputs
-      if (projectSlug && files.length === 0) {
+      if (projectSlug && (!files || files.length === 0)) {
         const buildPatterns = [
           `${projectSlug}.docx`,
           `${projectSlug}_comments.docx`,
@@ -438,7 +604,7 @@ export function register(program, pkg) {
           'paper_comments.docx',
           'paper-changes.docx',
         ];
-        const excluded = [];
+        const excluded: string[] = [];
         docxFiles = docxFiles.filter(f => {
           const base = path.basename(f).toLowerCase();
           const isBuilt = buildPatterns.includes(base);
@@ -459,7 +625,7 @@ export function register(program, pkg) {
       const projectTitle = projectSlug;
 
       // Create archive folder
-      const archiveDir = path.resolve(options.dir);
+      const archiveDir = path.resolve(options.dir || 'archive');
       if (!options.dryRun && !fs.existsSync(archiveDir)) {
         fs.mkdirSync(archiveDir, { recursive: true });
       }
@@ -467,14 +633,14 @@ export function register(program, pkg) {
       console.log(fmt.header('Archive'));
       console.log();
 
-      const moved = [];
+      const moved: string[] = [];
       for (const file of docxFiles) {
         const stat = fs.statSync(file);
         const mtime = stat.mtime;
         const timestamp = mtime.toISOString().slice(0, 19).replace(/[-:]/g, '').replace('T', '_');
 
         // Determine reviewer name
-        let reviewer = options.by || null;
+        let reviewer: string | null = options.by || null;
         if (!reviewer && options.rename !== false) {
           try {
             const comments = await extractWordComments(file);
@@ -488,7 +654,7 @@ export function register(program, pkg) {
         }
 
         // Generate new name
-        let newName;
+        let newName: string;
         if (options.rename === false) {
           newName = path.basename(file);
         } else {
@@ -508,7 +674,7 @@ export function register(program, pkg) {
         const destPath = path.join(archiveDir, newName);
 
         if (options.dryRun) {
-          console.log(`  ${chalk.dim(file)} → ${chalk.cyan(path.join(options.dir, newName))}`);
+          console.log(`  ${chalk.dim(file)} → ${chalk.cyan(path.join(options.dir || 'archive', newName))}`);
         } else {
           // Handle name collision
           let finalPath = destPath;
@@ -529,7 +695,7 @@ export function register(program, pkg) {
       if (options.dryRun) {
         console.log(fmt.status('info', `Would archive ${moved.length} file(s). Run without --dry-run to proceed.`));
       } else {
-        console.log(fmt.status('success', `Archived ${moved.length} file(s) to ${options.dir}/`));
+        console.log(fmt.status('success', `Archived ${moved.length} file(s) to ${options.dir || 'archive'}/`));
       }
     });
 
@@ -542,13 +708,13 @@ export function register(program, pkg) {
     .description('Export project as distributable zip')
     .option('-o, --output <file>', 'Output filename')
     .option('--include-output', 'Include built PDF/DOCX files')
-    .action(async (options) => {
+    .action(async (options: ExportOptions) => {
       const { default: AdmZip } = await import('adm-zip');
       const { build } = await import('../build.js');
 
-      let config = {};
+      let config: Partial<BuildConfig> = {};
       try {
-        config = loadBuildConfig() || {};
+        config = loadBuildConfig('.') || {};
       } catch {
         // Not in a rev project, that's ok
       }
@@ -556,7 +722,7 @@ export function register(program, pkg) {
       // Build first if including output
       if (options.includeOutput) {
         console.log(chalk.dim('Building documents...'));
-        await build(['pdf', 'docx']);
+        await build('.', ['pdf', 'docx']);
       }
 
       const zip = new AdmZip();
@@ -565,7 +731,7 @@ export function register(program, pkg) {
 
       const exclude = ['node_modules', '.git', '.DS_Store', '*.zip'];
 
-      const shouldInclude = (name) => {
+      const shouldInclude = (name: string): boolean => {
         if (!options.includeOutput && (name.endsWith('.pdf') || name.endsWith('.docx'))) {
           return false;
         }
@@ -575,7 +741,7 @@ export function register(program, pkg) {
         return true;
       };
 
-      const addDir = (dir, zipPath = '') => {
+      const addDir = (dir: string, zipPath = ''): void => {
         const entries = fs.readdirSync(dir, { withFileTypes: true });
         for (const entry of entries) {
           const fullPath = path.join(dir, entry.name);
@@ -614,29 +780,30 @@ export function register(program, pkg) {
     .command('preview')
     .description('Build and open document in default app')
     .argument('[format]', 'Format to preview: pdf, docx', 'pdf')
-    .action(async (format) => {
+    .action(async (format: string, _options: PreviewOptions) => {
       const { exec } = await import('child_process');
       const { build } = await import('../build.js');
 
-      let config = {};
+      let config: Partial<BuildConfig> = {};
       try {
-        config = loadBuildConfig() || {};
+        config = loadBuildConfig('.') || {};
       } catch (err) {
         console.error(chalk.red('Not in a rev project directory (no rev.yaml found)'));
         process.exit(1);
       }
 
       console.log(chalk.dim(`Building ${format}...`));
-      const results = await build([format]);
+      const result = await build('.', [format]);
 
-      const result = results.find(r => r.format === format);
-      if (!result?.success) {
-        console.error(chalk.red(`Build failed: ${result?.error || 'Unknown error'}`));
+      const buildResult = result.results.find(r => r.format === format);
+      if (!buildResult?.success) {
+        const errorMsg = buildResult?.error || 'Unknown error';
+        console.error(chalk.red(`Build failed: ${errorMsg}`));
         process.exit(1);
       }
 
-      const outputFile = result.output;
-      if (!fs.existsSync(outputFile)) {
+      const outputFile = buildResult.outputPath;
+      if (!outputFile || !fs.existsSync(outputFile)) {
         console.error(chalk.red(`Output file not found: ${outputFile}`));
         process.exit(1);
       }
@@ -663,13 +830,13 @@ export function register(program, pkg) {
     .description('Watch files and auto-rebuild on changes')
     .argument('[format]', 'Format to build: pdf, docx, all', 'pdf')
     .option('--no-open', 'Do not open after first build')
-    .action(async (format, options) => {
+    .action(async (format: string, options: WatchOptions) => {
       const { exec } = await import('child_process');
       const { build } = await import('../build.js');
 
-      let config = {};
+      let config: Partial<BuildConfig> = {};
       try {
-        config = loadBuildConfig() || {};
+        config = loadBuildConfig('.') || {};
       } catch (err) {
         console.error(chalk.red('Not in a rev project directory (no rev.yaml found)'));
         process.exit(1);
@@ -695,7 +862,7 @@ export function register(program, pkg) {
       let building = false;
       let pendingBuild = false;
 
-      const doBuild = async () => {
+      const doBuild = async (): Promise<void> => {
         if (building) {
           pendingBuild = true;
           return;
@@ -706,17 +873,17 @@ export function register(program, pkg) {
 
         try {
           const formats = format === 'all' ? ['pdf', 'docx'] : [format];
-          const results = await build(formats);
+          const result = await build('.', formats);
 
-          for (const r of results) {
+          for (const r of result.results) {
             if (r.success) {
-              console.log(chalk.green(`  ✓ ${r.format}: ${r.output}`));
+              console.log(chalk.green(`  ✓ ${r.format}: ${r.outputPath}`));
             } else {
               console.log(chalk.red(`  ✗ ${r.format}: ${r.error}`));
             }
           }
         } catch (err) {
-          console.error(chalk.red(`  Build error: ${err.message}`));
+          console.error(chalk.red(`  Build error: ${(err as Error).message}`));
         }
 
         building = false;
@@ -760,10 +927,10 @@ export function register(program, pkg) {
     .command('lint')
     .description('Check for common issues in the project')
     .option('--fix', 'Auto-fix issues where possible')
-    .action(async (options) => {
-      let config = {};
+    .action(async (_options: LintOptions) => {
+      let config: Partial<BuildConfig> = {};
       try {
-        config = loadBuildConfig() || {};
+        config = loadBuildConfig('.') || {};
       } catch {
         // Not in a rev project, that's ok
       }
@@ -775,8 +942,8 @@ export function register(program, pkg) {
         );
       }
 
-      const issues = [];
-      const warnings = [];
+      const issues: LintIssue[] = [];
+      const warnings: LintIssue[] = [];
 
       // Collect all content
       let allText = '';
@@ -787,12 +954,12 @@ export function register(program, pkg) {
       }
 
       // Check 1: Broken cross-references
-      const figAnchors = new Set();
-      const tblAnchors = new Set();
-      const eqAnchors = new Set();
+      const figAnchors = new Set<string>();
+      const tblAnchors = new Set<string>();
+      const eqAnchors = new Set<string>();
 
       const anchorPattern = /\{#(fig|tbl|eq):([^}]+)\}/g;
-      let match;
+      let match: RegExpExecArray | null;
       while ((match = anchorPattern.exec(allText)) !== null) {
         if (match[1] === 'fig') figAnchors.add(match[2]);
         else if (match[1] === 'tbl') tblAnchors.add(match[2]);
@@ -828,7 +995,7 @@ export function register(program, pkg) {
       const bibPath = config.bibliography || 'references.bib';
       if (fs.existsSync(bibPath)) {
         const bibContent = fs.readFileSync(bibPath, 'utf-8');
-        const bibKeys = new Set();
+        const bibKeys = new Set<string>();
         const bibPattern = /@\w+\s*\{\s*([^,]+)/g;
         while ((match = bibPattern.exec(bibContent)) !== null) {
           bibKeys.add(match[1].trim());
@@ -908,7 +1075,7 @@ export function register(program, pkg) {
     .option('--rules', 'List available grammar rules')
     .option('--no-scientific', 'Disable scientific writing rules')
     .option('-s, --severity <level>', 'Minimum severity: error, warning, info', 'info')
-    .action(async (files, options) => {
+    .action(async (files: string[] | undefined, options: GrammarOptions) => {
       const {
         checkGrammar,
         getGrammarSummary,
@@ -974,9 +1141,9 @@ export function register(program, pkg) {
       // Get files to check
       let mdFiles = files;
       if (!mdFiles || mdFiles.length === 0) {
-        let config = {};
+        let config: Partial<BuildConfig> = {};
         try {
-          config = loadBuildConfig() || {};
+          config = loadBuildConfig('.') || {};
         } catch {
           // Not in a rev project
         }
@@ -997,10 +1164,10 @@ export function register(program, pkg) {
       console.log(fmt.header('Grammar Check'));
       console.log();
 
-      const severityLevels = { error: 3, warning: 2, info: 1 };
-      const minSeverity = severityLevels[options.severity] || 1;
+      const severityLevels: Record<string, number> = { error: 3, warning: 2, info: 1 };
+      const minSeverity = severityLevels[options.severity || 'info'] || 1;
 
-      let allIssues = [];
+      let allIssues: GrammarIssue[] = [];
 
       for (const file of mdFiles) {
         if (!fs.existsSync(file)) continue;
@@ -1009,7 +1176,7 @@ export function register(program, pkg) {
         const issues = checkGrammar(text, { scientific: options.scientific });
 
         // Filter by severity
-        const filtered = issues.filter(i => severityLevels[i.severity] >= minSeverity);
+        const filtered = issues.filter((i: GrammarIssue) => severityLevels[i.severity] >= minSeverity);
 
         if (filtered.length > 0) {
           console.log(chalk.cyan.bold(file));
@@ -1049,7 +1216,7 @@ export function register(program, pkg) {
     .option('-m, --message <text>', 'Comment text')
     .option('-s, --search <text>', 'Text to attach comment to')
     .option('-a, --author <name>', 'Comment author')
-    .action(async (docxPath, options) => {
+    .action(async (docxPath: string, options: AnnotateOptions) => {
       if (!fs.existsSync(docxPath)) {
         console.error(chalk.red(`File not found: ${docxPath}`));
         process.exit(1);
@@ -1074,14 +1241,14 @@ export function register(program, pkg) {
 
       // Read or create comments.xml
       let commentsEntry = zip.getEntry('word/comments.xml');
-      let commentsXml;
+      let commentsXml: string;
       let nextCommentId = 1;
 
       if (commentsEntry) {
         commentsXml = zip.readAsText(commentsEntry);
         const idMatches = commentsXml.match(/w:id="(\d+)"/g) || [];
         for (const m of idMatches) {
-          const id = parseInt(m.match(/\d+/)[0]);
+          const id = parseInt(m.match(/\d+/)![0]);
           if (id >= nextCommentId) nextCommentId = id + 1;
         }
       } else {
@@ -1107,7 +1274,7 @@ export function register(program, pkg) {
         const textPattern = new RegExp(`(<w:t[^>]*>)([^<]*${searchText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[^<]*)(<\/w:t>)`, 'i');
 
         if (textPattern.test(docXml)) {
-          docXml = docXml.replace(textPattern, (match, start, text, end) => {
+          docXml = docXml.replace(textPattern, (_match, start, text, end) => {
             return `<w:commentRangeStart w:id="${commentId}"/>${start}${text}${end}<w:commentRangeEnd w:id="${commentId}"/><w:r><w:commentReference w:id="${commentId}"/></w:r>`;
           });
         } else {
@@ -1162,7 +1329,7 @@ export function register(program, pkg) {
     .argument('<md>', 'Markdown file with annotations')
     .argument('<docx>', 'Output Word document')
     .option('-a, --author <name>', 'Author name for track changes')
-    .action(async (mdPath, docxPath, options) => {
+    .action(async (mdPath: string, docxPath: string, options: ApplyOptions) => {
       if (!fs.existsSync(mdPath)) {
         console.error(chalk.red(`File not found: ${mdPath}`));
         process.exit(1);
@@ -1191,7 +1358,7 @@ export function register(program, pkg) {
           process.exit(1);
         }
       } catch (err) {
-        console.error(chalk.red(`Error: ${err.message}`));
+        console.error(chalk.red(`Error: ${(err as Error).message}`));
         process.exit(1);
       }
     });
@@ -1205,19 +1372,20 @@ export function register(program, pkg) {
     .description('Add comments to Word document interactively')
     .argument('<docx>', 'Word document')
     .option('-a, --author <name>', 'Comment author')
-    .action(async (docxPath, options) => {
+    .action(async (docxPath: string, options: CommentOptions) => {
       if (!fs.existsSync(docxPath)) {
         console.error(chalk.red(`File not found: ${docxPath}`));
         process.exit(1);
       }
 
       const { default: AdmZip } = await import('adm-zip');
-      const rl = (await import('readline')).createInterface({
+      const readline = await import('readline');
+      const rl = readline.createInterface({
         input: process.stdin,
         output: process.stdout,
       });
 
-      const ask = (prompt) => new Promise((resolve) => rl.question(prompt, resolve));
+      const ask = (prompt: string): Promise<string> => new Promise((resolve) => rl.question(prompt, resolve));
 
       const author = options.author || getUserName() || 'Reviewer';
 
@@ -1252,14 +1420,14 @@ export function register(program, pkg) {
 
         // Read or create comments.xml
         let commentsEntry = zip.getEntry('word/comments.xml');
-        let commentsXml;
+        let commentsXml: string;
         let nextCommentId = 1;
 
         if (commentsEntry) {
           commentsXml = zip.readAsText(commentsEntry);
           const idMatches = commentsXml.match(/w:id="(\d+)"/g) || [];
           for (const m of idMatches) {
-            const id = parseInt(m.match(/\d+/)[0]);
+            const id = parseInt(m.match(/\d+/)![0]);
             if (id >= nextCommentId) nextCommentId = id + 1;
           }
         } else {
@@ -1284,7 +1452,7 @@ export function register(program, pkg) {
           const textPattern = new RegExp(`(<w:t[^>]*>)([^<]*${escapedSearch}[^<]*)(<\/w:t>)`, 'i');
 
           if (textPattern.test(docXml)) {
-            docXml = docXml.replace(textPattern, (match, start, text, end) => {
+            docXml = docXml.replace(textPattern, (_match, start, text, end) => {
               return `<w:commentRangeStart w:id="${commentId}"/>${start}${text}${end}<w:commentRangeEnd w:id="${commentId}"/><w:r><w:commentReference w:id="${commentId}"/></w:r>`;
             });
             console.log(chalk.green(`  ✓ Comment added at "${searchText}"`));
@@ -1351,10 +1519,10 @@ export function register(program, pkg) {
     .description('Remove generated files (paper.md, PDFs, DOCXs)')
     .option('-n, --dry-run', 'Show what would be deleted without deleting')
     .option('--all', 'Also remove backup and export zips')
-    .action((options) => {
-      let config = {};
+    .action((options: CleanOptions) => {
+      let config: Partial<BuildConfig> = {};
       try {
-        config = loadBuildConfig() || {};
+        config = loadBuildConfig('.') || {};
       } catch {
         // Not in a rev project, that's ok
       }
@@ -1375,7 +1543,7 @@ export function register(program, pkg) {
         patterns.push('*.zip', 'backup-*.zip', '*-export.zip');
       }
 
-      const toDelete = [];
+      const toDelete: string[] = [];
 
       for (const pattern of patterns) {
         if (pattern.includes('*')) {
@@ -1421,7 +1589,7 @@ export function register(program, pkg) {
     .description('Run all checks before submission (lint + grammar + citations)')
     .option('--fix', 'Auto-fix issues where possible')
     .option('-s, --severity <level>', 'Minimum grammar severity', 'warning')
-    .action(async (options) => {
+    .action(async (options: CheckOptions) => {
       const { validateCitations } = await import('../citations.js');
       const { checkGrammar, getGrammarSummary } = await import('../grammar.js');
 
@@ -1433,9 +1601,9 @@ export function register(program, pkg) {
 
       // 1. Run lint
       console.log(chalk.cyan.bold('1. Linting...'));
-      let config = {};
+      let config: Partial<BuildConfig> = {};
       try {
-        config = loadBuildConfig() || {};
+        config = loadBuildConfig('.') || {};
       } catch {
         // Not in a rev project
       }
@@ -1447,8 +1615,8 @@ export function register(program, pkg) {
         );
       }
 
-      const lintIssues = [];
-      const lintWarnings = [];
+      const lintIssues: { file: string; message: string }[] = [];
+      const lintWarnings: { file: string; message: string }[] = [];
 
       for (const file of sections) {
         if (!fs.existsSync(file)) continue;
@@ -1457,7 +1625,7 @@ export function register(program, pkg) {
         // Check for broken cross-references
         const refs = content.match(/@(fig|tbl|eq|sec):\w+/g) || [];
         const anchors = content.match(/\{#(fig|tbl|eq|sec):[^}]+\}/g) || [];
-        const anchorLabels = anchors.map(a => a.match(/#([^}]+)/)[1]);
+        const anchorLabels = anchors.map(a => a.match(/#([^}]+)/)![1]);
 
         for (const ref of refs) {
           const label = ref.slice(1);
@@ -1493,15 +1661,15 @@ export function register(program, pkg) {
       // 2. Run grammar check
       console.log(chalk.cyan.bold('2. Grammar check...'));
 
-      const severityLevels = { error: 3, warning: 2, info: 1 };
-      const minSeverity = severityLevels[options.severity] || 2;
-      let grammarIssues = [];
+      const severityLevels: Record<string, number> = { error: 3, warning: 2, info: 1 };
+      const minSeverity = severityLevels[options.severity || 'warning'] || 2;
+      let grammarIssues: GrammarIssue[] = [];
 
       for (const file of sections) {
         if (!fs.existsSync(file)) continue;
         const text = fs.readFileSync(file, 'utf-8');
         const issues = checkGrammar(text, { scientific: true });
-        const filtered = issues.filter(i => severityLevels[i.severity] >= minSeverity);
+        const filtered = issues.filter((i: GrammarIssue) => severityLevels[i.severity] >= minSeverity);
         grammarIssues.push(...filtered.map(i => ({ ...i, file })));
       }
 
@@ -1522,13 +1690,9 @@ export function register(program, pkg) {
       console.log(chalk.cyan.bold('3. Citation check...'));
       const bibFile = config.bibliography || 'references.bib';
       if (fs.existsSync(bibFile)) {
-        const allContent = sections
-          .filter(f => fs.existsSync(f))
-          .map(f => fs.readFileSync(f, 'utf-8'))
-          .join('\n');
-        const bibContent = fs.readFileSync(bibFile, 'utf-8');
+        const existingSections = sections.filter(f => fs.existsSync(f));
 
-        const result = validateCitations(allContent, bibContent);
+        const result = validateCitations(existingSections, bibFile);
 
         if (result.missing.length > 0) {
           console.log(chalk.red(`   ✗ ${result.missing.length} missing citation(s): ${result.missing.slice(0, 3).join(', ')}${result.missing.length > 3 ? '...' : ''}`));
@@ -1567,7 +1731,7 @@ export function register(program, pkg) {
     .command('open')
     .description('Open project folder or file in default app')
     .argument('[file]', 'File to open (default: project folder)')
-    .action(async (file) => {
+    .action(async (file?: string, _options?: OpenOptions) => {
       const { exec } = await import('child_process');
       const target = file || '.';
 
@@ -1577,7 +1741,7 @@ export function register(program, pkg) {
       }
 
       const platform = process.platform;
-      let command;
+      let command: string;
 
       if (platform === 'darwin') {
         command = `open "${target}"`;
@@ -1605,6 +1769,10 @@ export function register(program, pkg) {
     .description('Install docrev skill for Claude Code')
     .action(() => {
       const homedir = process.env.HOME || process.env.USERPROFILE;
+      if (!homedir) {
+        console.error(chalk.red('Could not determine home directory'));
+        process.exit(1);
+      }
       const skillDir = path.join(homedir, '.claude', 'skills', 'docrev');
       const sourceDir = path.join(import.meta.dirname, '..', '..', 'skill');
 
@@ -1638,6 +1806,10 @@ export function register(program, pkg) {
     .description('Remove docrev skill from Claude Code')
     .action(() => {
       const homedir = process.env.HOME || process.env.USERPROFILE;
+      if (!homedir) {
+        console.error(chalk.red('Could not determine home directory'));
+        process.exit(1);
+      }
       const skillDir = path.join(homedir, '.claude', 'skills', 'docrev');
 
       if (fs.existsSync(skillDir)) {
@@ -1665,7 +1837,7 @@ export function register(program, pkg) {
     .option('--list-all', 'List all custom words (global + project)')
     .option('--british', 'Use British English dictionary')
     .option('--add-names', 'Add detected names to global dictionary')
-    .action(async (files, options) => {
+    .action(async (files: string[] | undefined, options: SpellingOptions) => {
       const spelling = await import('../spelling.js');
 
       // Handle dictionary management
@@ -1766,12 +1938,20 @@ export function register(program, pkg) {
       }
 
       // Check spelling in files
-      let filesToCheck = files;
+      let filesToCheck = files || [];
 
       if (filesToCheck.length === 0) {
         if (fs.existsSync('rev.yaml')) {
-          const { getSectionFiles } = await import('../sections.js');
-          filesToCheck = getSectionFiles('.');
+          try {
+            const config = loadBuildConfig('.');
+            filesToCheck = config?.sections || [];
+          } catch {
+            // Ignore errors
+          }
+          if (filesToCheck.length === 0) {
+            filesToCheck = fs.readdirSync('.')
+              .filter(f => f.endsWith('.md') && !f.startsWith('.'));
+          }
         } else {
           filesToCheck = fs.readdirSync('.')
             .filter(f => f.endsWith('.md') && !f.startsWith('.'));
@@ -1786,7 +1966,7 @@ export function register(program, pkg) {
       const lang = options.british ? 'en-gb' : 'en';
       console.log(fmt.header(`Spelling Check (${options.british ? 'British' : 'US'} English)`));
       let totalMisspelled = 0;
-      const allNames = new Set();
+      const allNames = new Set<string>();
 
       for (const file of filesToCheck) {
         if (!fs.existsSync(file)) {
@@ -1794,7 +1974,7 @@ export function register(program, pkg) {
           continue;
         }
 
-        const result = await spelling.checkFile(file, { projectDir: '.', lang });
+        const result = await spelling.checkFile(file, { projectDir: '.', lang }) as SpellingResult;
         const { misspelled, possibleNames } = result;
 
         // Collect names
@@ -1853,7 +2033,7 @@ export function register(program, pkg) {
     .command('upgrade')
     .description('Check for updates and upgrade docrev')
     .option('--check', 'Only check for updates, do not install')
-    .action(async (options) => {
+    .action(async (options: UpgradeOptions) => {
       const { execSync, spawn } = await import('child_process');
 
       console.log(chalk.cyan('Checking for updates...'));
@@ -1863,7 +2043,7 @@ export function register(program, pkg) {
         const currentVersion = pkg?.version || 'unknown';
 
         // Get latest version from npm
-        let latestVersion;
+        let latestVersion: string;
         try {
           latestVersion = execSync('npm view docrev version', { encoding: 'utf-8' }).trim();
         } catch {
@@ -1911,7 +2091,7 @@ export function register(program, pkg) {
           process.exit(1);
         });
       } catch (err) {
-        console.error(chalk.red(`Error: ${err.message}`));
+        console.error(chalk.red(`Error: ${(err as Error).message}`));
         process.exit(1);
       }
     });
@@ -1928,7 +2108,7 @@ export function register(program, pkg) {
     .option('--parallel', 'Run operations in parallel')
     .option('--dry-run', 'Preview files without running')
     .option('-a, --all', 'Include all .md files (not just sections)')
-    .action(async (command, pattern, options) => {
+    .action(async (command: string, pattern: string | undefined, options: BatchOptions) => {
       const validCommands = ['status', 'strip', 'resolve', 'comments'];
 
       if (!validCommands.includes(command)) {
@@ -1938,7 +2118,7 @@ export function register(program, pkg) {
       }
 
       // Find files
-      let files = [];
+      let files: string[] = [];
       if (pattern) {
         if (pattern.includes('*')) {
           files = fs.readdirSync('.').filter(f =>
@@ -1971,7 +2151,7 @@ export function register(program, pkg) {
       }
 
       // Process files
-      const results = [];
+      const results: BatchResult[] = [];
       const progressBar = fmt.progressBar(files.length, 'Processing');
       progressBar.update(0);
 
@@ -1986,7 +2166,7 @@ export function register(program, pkg) {
 
         try {
           const text = fs.readFileSync(file, 'utf-8');
-          let result = { file, status: 'ok' };
+          let result: BatchResult = { file, status: 'ok' };
 
           switch (command) {
             case 'status': {
@@ -2037,7 +2217,7 @@ export function register(program, pkg) {
 
           results.push(result);
         } catch (err) {
-          results.push({ file, status: 'error', error: err.message });
+          results.push({ file, status: 'error', error: (err as Error).message });
         }
       }
 
@@ -2064,7 +2244,7 @@ export function register(program, pkg) {
             details = chalk.dim(`${r.total || 0} total, ${r.pending || 0} pending`);
             break;
           case 'resolve':
-            details = r.resolved > 0
+            details = r.resolved && r.resolved > 0
               ? chalk.green(`${r.resolved} resolved`)
               : chalk.dim('no pending');
             break;
@@ -2091,7 +2271,7 @@ export function register(program, pkg) {
 
 // Helper functions for help text
 
-function showFullHelp(pkg) {
+function showFullHelp(pkg?: PackageJson): void {
   console.log(`
 ${chalk.bold.cyan('rev')} ${chalk.dim(`v${pkg?.version || 'unknown'}`)} - Revision workflow for Word ↔ Markdown round-trips
 
@@ -2124,7 +2304,7 @@ ${chalk.bold('MORE HELP')}
 `);
 }
 
-function showWorkflowHelp() {
+function showWorkflowHelp(): void {
   console.log(`
 ${chalk.bold.cyan('rev')} ${chalk.dim('- Workflow Guide')}
 
@@ -2178,7 +2358,7 @@ ${chalk.bold('STEP 7: ARCHIVE & REPEAT')}
 `);
 }
 
-function showSyntaxHelp() {
+function showSyntaxHelp(): void {
   console.log(`
 ${chalk.bold.cyan('rev')} ${chalk.dim('- Annotation Syntax (CriticMarkup)')}
 
@@ -2222,7 +2402,7 @@ ${chalk.bold('COMMENTS')}
 `);
 }
 
-function showCommandsHelp() {
+function showCommandsHelp(): void {
   console.log(`
 ${chalk.bold.cyan('rev')} ${chalk.dim('- Command Reference')}