claude-git-hooks 2.1.0 → 2.3.1

package/lib/utils/claude-client.js

@@ -12,12 +12,16 @@
  * - child_process: For executing Claude CLI
  * - fs/promises: For debug file writing
  * - logger: Debug and error logging
+ * - claude-diagnostics: Error detection and formatting
  */
 
 import { spawn, execSync } from 'child_process';
 import fs from 'fs/promises';
+import path from 'path';
 import os from 'os';
 import logger from './logger.js';
+import config from '../config.js';
+import { detectClaudeError, formatClaudeError, ClaudeErrorType } from './claude-diagnostics.js';
 
 /**
  * Custom error for Claude client failures
@@ -53,7 +57,7 @@ const isWSLAvailable = () => {
 
     try {
         // Try to run wsl --version to check if WSL is installed
-        execSync('wsl --version', { stdio: 'ignore', timeout: 3000 });
+        execSync('wsl --version', { stdio: 'ignore', timeout: config.system.wslCheckTimeout });
         return true;
     } catch (error) {
         logger.debug('claude-client - isWSLAvailable', 'WSL not available', error);
@@ -139,18 +143,25 @@ const executeClaude = (prompt, { timeout = 120000 } = {}) => {
                 );
                 resolve(stdout);
             } else {
+                // Detect specific error type
+                const errorInfo = detectClaudeError(stdout, stderr, code);
+
                 logger.error(
                     'claude-client - executeClaude',
-                    `Claude CLI failed with exit code ${code}`,
-                    new ClaudeClientError('Claude CLI execution failed', {
+                    `Claude CLI failed: ${errorInfo.type}`,
+                    new ClaudeClientError(`Claude CLI error: ${errorInfo.type}`, {
                         output: { stdout, stderr },
-                        context: { exitCode: code, duration }
+                        context: { exitCode: code, duration, errorType: errorInfo.type }
                     })
                 );
 
-                reject(new ClaudeClientError('Claude CLI execution failed', {
+                // Show formatted error to user
+                const formattedError = formatClaudeError(errorInfo);
+                console.error('\n' + formattedError + '\n');
+
+                reject(new ClaudeClientError(`Claude CLI error: ${errorInfo.type}`, {
                     output: { stdout, stderr },
-                    context: { exitCode: code, duration }
+                    context: { exitCode: code, duration, errorInfo }
                 }));
             }
         });
@@ -294,15 +305,45 @@ const extractJSON = (response) => {
 };
 
 /**
- * Saves response to debug file
- * Why: Helps troubleshoot issues with Claude responses
+ * Saves prompt and response to debug file
+ * Why: Helps troubleshoot issues with Claude responses and verify prompts
  *
- * @param {string} response - Raw response to save
- * @param {string} filename - Debug filename (default: 'debug-claude-response.json')
+ * @param {string} prompt - Prompt sent to Claude
+ * @param {string} response - Raw response from Claude
+ * @param {string} filename - Debug filename (default: from config)
  */
-const saveDebugResponse = async (response, filename = 'debug-claude-response.json') => {
+const saveDebugResponse = async (prompt, response, filename = config.output.debugFile) => {
     try {
-        await fs.writeFile(filename, response, 'utf8');
+        // Ensure output directory exists
+        const outputDir = path.dirname(filename);
+        await fs.mkdir(outputDir, { recursive: true });
+
+        // Save full debug information
+        const debugData = {
+            timestamp: new Date().toISOString(),
+            promptLength: prompt.length,
+            responseLength: response.length,
+            prompt: prompt,
+            response: response
+        };
+
+        await fs.writeFile(filename, JSON.stringify(debugData, null, 2), 'utf8');
+
+        // Display batch optimization status
+        try {
+            if (prompt.includes('OPTIMIZATION')) {
+                console.log('\n' + '='.repeat(70));
+                console.log('✅ BATCH OPTIMIZATION ENABLED');
+                console.log('='.repeat(70));
+                console.log('Multi-file analysis organized for efficient processing');
+                console.log('Check debug file for full prompt and response details');
+                console.log('='.repeat(70) + '\n');
+            }
+        } catch (parseError) {
+            // Ignore parsing errors, just skip the display
+        }
+
+        logger.info(`📝 Debug output saved to ${filename}`);
         logger.debug(
             'claude-client - saveDebugResponse',
             `Debug response saved to ${filename}`
@@ -323,11 +364,11 @@ const saveDebugResponse = async (response, filename = 'debug-claude-response.jso
  * @param {string} prompt - Analysis prompt
  * @param {Object} options - Analysis options
  * @param {number} options.timeout - Timeout in milliseconds
- * @param {boolean} options.saveDebug - Save response to debug file (default: from DEBUG env)
+ * @param {boolean} options.saveDebug - Save response to debug file (default: from config)
  * @returns {Promise<Object>} Parsed analysis result
  * @throws {ClaudeClientError} If analysis fails
  */
-const analyzeCode = async (prompt, { timeout = 120000, saveDebug = process.env.DEBUG === 'true' } = {}) => {
+const analyzeCode = async (prompt, { timeout = 120000, saveDebug = config.system.debug } = {}) => {
     logger.debug(
         'claude-client - analyzeCode',
         'Starting code analysis',
@@ -340,7 +381,7 @@ const analyzeCode = async (prompt, { timeout = 120000, saveDebug = process.env.D
 
         // Save debug if requested
         if (saveDebug) {
-            await saveDebugResponse(response);
+            await saveDebugResponse(prompt, response);
         }
 
         // Extract and parse JSON
@@ -364,10 +405,60 @@ const analyzeCode = async (prompt, { timeout = 120000, saveDebug = process.env.D
     }
 };
 
+/**
+ * Splits array into chunks
+ * @param {Array} array - Array to split
+ * @param {number} size - Chunk size
+ * @returns {Array<Array>} Array of chunks
+ */
+const chunkArray = (array, size) => {
+    const chunks = [];
+    for (let i = 0; i < array.length; i += size) {
+        chunks.push(array.slice(i, i + size));
+    }
+    return chunks;
+};
+
+/**
+ * Runs multiple analyzeCode calls in parallel
+ * @param {Array<string>} prompts - Array of prompts to analyze
+ * @param {Object} options - Same options as analyzeCode
+ * @returns {Promise<Array<Object>>} Array of results
+ */
+const analyzeCodeParallel = async (prompts, options = {}) => {
+    const startTime = Date.now();
+
+    console.log('\n' + '='.repeat(70));
+    console.log(`🚀 PARALLEL EXECUTION: ${prompts.length} Claude processes`);
+    console.log('='.repeat(70));
+
+    logger.info(`Starting parallel analysis: ${prompts.length} prompts`);
+
+    const promises = prompts.map((prompt, index) => {
+        console.log(`  ⚡ Launching batch ${index + 1}/${prompts.length}...`);
+        logger.debug('claude-client - analyzeCodeParallel', `Starting batch ${index + 1}`);
+        return analyzeCode(prompt, options);
+    });
+
+    console.log(`  ⏳ Waiting for all batches to complete...\n`);
+    const results = await Promise.all(promises);
+
+    const duration = ((Date.now() - startTime) / 1000).toFixed(2);
+
+    console.log('='.repeat(70));
+    console.log(`✅ PARALLEL EXECUTION COMPLETE: ${results.length} results in ${duration}s`);
+    console.log('='.repeat(70) + '\n');
+
+    logger.info(`Parallel analysis complete: ${results.length} results in ${duration}s`);
+    return results;
+};
+
 export {
     ClaudeClientError,
     executeClaude,
     extractJSON,
     saveDebugResponse,
-    analyzeCode
+    analyzeCode,
+    analyzeCodeParallel,
+    chunkArray
 };

package/lib/utils/claude-diagnostics.js

@@ -0,0 +1,266 @@
+/**
+ * File: claude-diagnostics.js
+ * Purpose: Reusable Claude CLI error diagnostics and formatting
+ *
+ * Key features:
+ * - Detects common Claude CLI error patterns
+ * - Provides actionable remediation steps
+ * - Extensible for future error types
+ *
+ * Usage:
+ *   import { detectClaudeError, formatClaudeError } from './claude-diagnostics.js';
+ *
+ *   const errorInfo = detectClaudeError(stdout, stderr, exitCode);
+ *   if (errorInfo) {
+ *     console.error(formatClaudeError(errorInfo));
+ *   }
+ */
+
+/**
+ * Error types that can be detected
+ */
+export const ClaudeErrorType = {
+    RATE_LIMIT: 'RATE_LIMIT',
+    AUTH_FAILED: 'AUTH_FAILED',
+    TIMEOUT: 'TIMEOUT',
+    NETWORK: 'NETWORK',
+    INVALID_RESPONSE: 'INVALID_RESPONSE',
+    GENERIC: 'GENERIC'
+};
+
+/**
+ * Detects Claude CLI error type and extracts relevant information
+ * Why: Centralized error detection for consistent handling
+ *
+ * Future enhancements:
+ * - Network connectivity errors
+ * - Authentication expiration
+ * - Model availability errors
+ * - Token limit exceeded errors
+ *
+ * @param {string} stdout - Claude CLI stdout
+ * @param {string} stderr - Claude CLI stderr
+ * @param {number} exitCode - Process exit code
+ * @returns {Object|null} Error information or null if no specific error detected
+ */
+export const detectClaudeError = (stdout = '', stderr = '', exitCode = 1) => {
+    // 1. Rate limit detection
+    const rateLimitMatch = stdout.match(/Claude AI usage limit reached\|(\d+)/);
+    if (rateLimitMatch) {
+        const resetTimestamp = parseInt(rateLimitMatch[1], 10);
+        const resetDate = new Date(resetTimestamp * 1000);
+        const now = new Date();
+        const minutesUntilReset = Math.ceil((resetDate - now) / 60000);
+
+        return {
+            type: ClaudeErrorType.RATE_LIMIT,
+            exitCode,
+            resetTimestamp,
+            resetDate,
+            minutesUntilReset
+        };
+    }
+
+    // 2. Authentication failure detection
+    if (stdout.includes('not authenticated') || stderr.includes('not authenticated') ||
+        stdout.includes('authentication failed') || stderr.includes('authentication failed')) {
+        return {
+            type: ClaudeErrorType.AUTH_FAILED,
+            exitCode
+        };
+    }
+
+    // 3. Network errors
+    if (stderr.includes('ENOTFOUND') || stderr.includes('ECONNREFUSED') ||
+        stderr.includes('network error') || stderr.includes('connection refused')) {
+        return {
+            type: ClaudeErrorType.NETWORK,
+            exitCode
+        };
+    }
+
+    // 4. Invalid response (JSON parsing errors)
+    if (stdout.includes('SyntaxError') || stdout.includes('Unexpected token')) {
+        return {
+            type: ClaudeErrorType.INVALID_RESPONSE,
+            exitCode
+        };
+    }
+
+    // 5. Generic error
+    return {
+        type: ClaudeErrorType.GENERIC,
+        exitCode,
+        stdout: stdout.substring(0, 200), // First 200 chars
+        stderr: stderr.substring(0, 200)
+    };
+};
+
+/**
+ * Formats Claude error message with diagnostics and remediation steps
+ * Why: Provides consistent, actionable error messages
+ *
+ * @param {Object} errorInfo - Output from detectClaudeError()
+ * @returns {string} Formatted error message
+ */
+export const formatClaudeError = (errorInfo) => {
+    const lines = [];
+
+    switch (errorInfo.type) {
+        case ClaudeErrorType.RATE_LIMIT:
+            return formatRateLimitError(errorInfo);
+
+        case ClaudeErrorType.AUTH_FAILED:
+            return formatAuthError(errorInfo);
+
+        case ClaudeErrorType.NETWORK:
+            return formatNetworkError(errorInfo);
+
+        case ClaudeErrorType.INVALID_RESPONSE:
+            return formatInvalidResponseError(errorInfo);
+
+        case ClaudeErrorType.GENERIC:
+        default:
+            return formatGenericError(errorInfo);
+    }
+};
+
+/**
+ * Format rate limit error
+ */
+const formatRateLimitError = ({ resetDate, minutesUntilReset }) => {
+    const lines = [];
+
+    lines.push('❌ Claude API usage limit reached');
+    lines.push('');
+    lines.push('Rate limit details:');
+    lines.push(`  Reset time: ${resetDate.toLocaleString()}`);
+
+    if (minutesUntilReset > 60) {
+        const hours = Math.ceil(minutesUntilReset / 60);
+        lines.push(`  Time until reset: ~${hours} hour${hours > 1 ? 's' : ''}`);
+    } else if (minutesUntilReset > 0) {
+        lines.push(`  Time until reset: ~${minutesUntilReset} minute${minutesUntilReset !== 1 ? 's' : ''}`);
+    } else {
+        lines.push('  Limit should be reset now');
+    }
+
+    lines.push('');
+    lines.push('Options:');
+    lines.push('  1. Wait for rate limit to reset');
+    lines.push('  2. Skip analysis for now:');
+    lines.push('     git commit --no-verify -m "your message"');
+    lines.push('  3. Reduce API usage by switching to haiku model:');
+    lines.push('     Edit .claude/config.json:');
+    lines.push('     { "subagents": { "model": "haiku" } }');
+
+    return lines.join('\n');
+};
+
+/**
+ * Format authentication error
+ */
+const formatAuthError = ({ exitCode }) => {
+    const lines = [];
+
+    lines.push('❌ Claude CLI authentication failed');
+    lines.push('');
+    lines.push('Possible causes:');
+    lines.push('  1. Not logged in to Claude CLI');
+    lines.push('  2. Authentication token expired');
+    lines.push('  3. Invalid API credentials');
+    lines.push('');
+    lines.push('Solution:');
+    lines.push('  claude auth login');
+    lines.push('');
+    lines.push('Then try your commit again.');
+
+    return lines.join('\n');
+};
+
+/**
+ * Format network error
+ */
+const formatNetworkError = ({ exitCode }) => {
+    const lines = [];
+
+    lines.push('❌ Network error connecting to Claude API');
+    lines.push('');
+    lines.push('Possible causes:');
+    lines.push('  1. No internet connection');
+    lines.push('  2. Firewall blocking Claude API');
+    lines.push('  3. Claude API temporarily unavailable');
+    lines.push('');
+    lines.push('Solutions:');
+    lines.push('  1. Check your internet connection');
+    lines.push('  2. Verify firewall settings');
+    lines.push('  3. Try again in a few moments');
+    lines.push('  4. Skip analysis: git commit --no-verify -m "message"');
+
+    return lines.join('\n');
+};
+
+/**
+ * Format invalid response error
+ */
+const formatInvalidResponseError = ({ exitCode }) => {
+    const lines = [];
+
+    lines.push('❌ Claude returned invalid response');
+    lines.push('');
+    lines.push('This usually means:');
+    lines.push('  - Claude did not return valid JSON');
+    lines.push('  - Response format does not match expected schema');
+    lines.push('');
+    lines.push('Solutions:');
+    lines.push('  1. Check debug output: .claude/out/debug-claude-response.json');
+    lines.push('  2. Try again (may be temporary issue)');
+    lines.push('  3. Skip analysis: git commit --no-verify -m "message"');
+
+    return lines.join('\n');
+};
+
+/**
+ * Format generic error
+ */
+const formatGenericError = ({ exitCode, stdout, stderr }) => {
+    const lines = [];
+
+    lines.push('❌ Claude CLI execution failed');
+    lines.push('');
+    lines.push(`Exit code: ${exitCode}`);
+
+    if (stdout && stdout.trim()) {
+        lines.push('');
+        lines.push('Output:');
+        lines.push(`  ${stdout.trim()}`);
+    }
+
+    if (stderr && stderr.trim()) {
+        lines.push('');
+        lines.push('Error:');
+        lines.push(`  ${stderr.trim()}`);
+    }
+
+    lines.push('');
+    lines.push('Solutions:');
+    lines.push('  1. Verify Claude CLI is installed: claude --version');
+    lines.push('  2. Check authentication: claude auth login');
+    lines.push('  3. Enable debug mode in .claude/config.json:');
+    lines.push('     { "system": { "debug": true } }');
+    lines.push('  4. Skip analysis: git commit --no-verify -m "message"');
+
+    return lines.join('\n');
+};
+
+/**
+ * Checks if Claude CLI error is recoverable
+ * Why: Some errors (rate limit) should wait, others (auth) should fail immediately
+ *
+ * @param {Object} errorInfo - Output from detectClaudeError()
+ * @returns {boolean} True if error might resolve with retry
+ */
+export const isRecoverableError = (errorInfo) => {
+    return errorInfo.type === ClaudeErrorType.RATE_LIMIT ||
+           errorInfo.type === ClaudeErrorType.NETWORK;
+};

package/lib/utils/file-operations.js

@@ -347,69 +347,6 @@ const filterFiles = async (files, { maxSize = 100000, extensions = [] } = {}) =>
  *   }
  * ]
  */
-const readMultipleFiles = async (files, { maxSize = 100000, applySkipFilter = true } = {}) => {
-    logger.debug(
-        'file-operations - readMultipleFiles',
-        'Reading multiple files',
-        { fileCount: files.length, maxSize, applySkipFilter }
-    );
-
-    const results = await Promise.allSettled(
-        files.map(async (filePath) => {
-            try {
-                let content = await readFile(filePath, { maxSize });
-
-                // Apply SKIP-ANALYSIS filtering if requested
-                if (applySkipFilter) {
-                    content = filterSkipAnalysis(content);
-                }
-
-                const size = await getFileSize(filePath);
-
-                return {
-                    path: filePath,
-                    content,
-                    size,
-                    error: null
-                };
-
-            } catch (error) {
-                logger.error(
-                    'file-operations - readMultipleFiles',
-                    `Failed to read file: ${filePath}`,
-                    error
-                );
-
-                return {
-                    path: filePath,
-                    content: null,
-                    size: 0,
-                    error
-                };
-            }
-        })
-    );
-
-    // Extract all results (both successful and failed)
-    const fileContents = results.map(r =>
-        r.status === 'fulfilled' ? r.value : r.reason
-    );
-
-    const successCount = fileContents.filter(f => f.error === null).length;
-
-    logger.debug(
-        'file-operations - readMultipleFiles',
-        'Reading complete',
-        {
-            totalFiles: files.length,
-            successfulReads: successCount,
-            failedReads: files.length - successCount
-        }
-    );
-
-    return fileContents;
-};
-
 export {
     FileOperationError,
     getFileSize,
@@ -417,6 +354,5 @@ export {
     readFile,
     filterSkipAnalysis,
     hasAllowedExtension,
-    filterFiles,
-    readMultipleFiles
+    filterFiles
 };

package/lib/utils/file-utils.js

@@ -0,0 +1,65 @@
+/**
+ * File: file-utils.js
+ * Purpose: Utility functions for file system operations
+ */
+
+import fs from 'fs/promises';
+import fsSync from 'fs';
+import path from 'path';
+import { getRepoRoot } from './git-operations.js';
+import logger from './logger.js';
+
+/**
+ * Ensures a directory exists (creates if not present)
+ *
+ * @param {string} dirPath - Directory path to ensure
+ * @returns {Promise<void>}
+ */
+export const ensureDir = async (dirPath) => {
+    const absolutePath = path.isAbsolute(dirPath)
+        ? dirPath
+        : path.join(getRepoRoot(), dirPath);
+
+    try {
+        await fs.mkdir(absolutePath, { recursive: true });
+        logger.debug('file-utils - ensureDir', 'Directory ensured', { path: absolutePath });
+    } catch (error) {
+        logger.error('file-utils - ensureDir', 'Failed to create directory', error);
+        throw error;
+    }
+};
+
+/**
+ * Ensures the output directory exists before writing files
+ * Creates .claude/out/ if it doesn't exist
+ *
+ * @param {Object} config - Configuration object with output.outputDir
+ * @returns {Promise<void>}
+ */
+export const ensureOutputDir = async (config) => {
+    const outputDir = config?.output?.outputDir || '.claude/out';
+    await ensureDir(outputDir);
+};
+
+/**
+ * Writes a file ensuring its directory exists
+ *
+ * @param {string} filePath - File path to write
+ * @param {string} content - File content
+ * @param {Object} config - Configuration object
+ * @returns {Promise<void>}
+ */
+export const writeOutputFile = async (filePath, content, config) => {
+    await ensureOutputDir(config);
+
+    const absolutePath = path.isAbsolute(filePath)
+        ? filePath
+        : path.join(getRepoRoot(), filePath);
+
+    await fs.writeFile(absolutePath, content, 'utf8');
+
+    logger.debug('file-utils - writeOutputFile', 'File written', {
+        path: absolutePath,
+        size: content.length
+    });
+};