claude-git-hooks 1.5.4 → 2.0.0

package/lib/utils/file-operations.js

@@ -0,0 +1,409 @@
+/**
+ * File: file-operations.js
+ * Purpose: File system operations and content filtering
+ *
+ * Key responsibilities:
+ * - Read files with size validation
+ * - Filter SKIP-ANALYSIS patterns from code
+ * - Validate file extensions
+ * - Check file sizes
+ *
+ * Dependencies:
+ * - fs/promises: Async file operations
+ * - path: Cross-platform path handling
+ * - logger: Debug and error logging
+ */
+
+import fs from 'fs/promises';
+import fsSync from 'fs';
+import path from 'path';
+import logger from './logger.js';
+
+/**
+ * Custom error for file operation failures
+ */
+class FileOperationError extends Error {
+    constructor(message, { filePath, cause, context } = {}) {
+        super(message);
+        this.name = 'FileOperationError';
+        this.filePath = filePath;
+        this.cause = cause;
+        this.context = context;
+    }
+}
+
+/**
+ * Gets file size in bytes
+ * Why: Need to filter large files before reading to avoid memory issues
+ *
+ * @param {string} filePath - Path to file
+ * @returns {Promise<number>} File size in bytes
+ */
+const getFileSize = async (filePath) => {
+    logger.debug('file-operations - getFileSize', 'Getting file size', { filePath });
+
+    try {
+        const stats = await fs.stat(filePath);
+        return stats.size;
+    } catch (error) {
+        throw new FileOperationError('Failed to get file size', {
+            filePath,
+            cause: error
+        });
+    }
+};
+
+/**
+ * Checks if file exists
+ *
+ * @param {string} filePath - Path to file
+ * @returns {Promise<boolean>} True if file exists
+ */
+const fileExists = async (filePath) => {
+    try {
+        await fs.access(filePath);
+        return true;
+    } catch {
+        return false;
+    }
+};
+
+/**
+ * Reads file content with size check
+ * Why: Prevents loading huge files into memory that could cause OOM errors
+ *
+ * @param {string} filePath - Path to file
+ * @param {Object} options - Read options
+ * @param {number} options.maxSize - Maximum file size in bytes (default: 100000 = 100KB)
+ * @param {string} options.encoding - File encoding (default: 'utf8')
+ * @returns {Promise<string>} File content
+ * @throws {FileOperationError} If file too large or read fails
+ */
+const readFile = async (filePath, { maxSize = 100000, encoding = 'utf8' } = {}) => {
+    logger.debug(
+        'file-operations - readFile',
+        'Reading file',
+        { filePath, maxSize, encoding }
+    );
+
+    try {
+        const size = await getFileSize(filePath);
+
+        // Why: Check size before reading to avoid loading huge files
+        if (size > maxSize) {
+            throw new FileOperationError('File exceeds maximum size', {
+                filePath,
+                context: { size, maxSize }
+            });
+        }
+
+        const content = await fs.readFile(filePath, encoding);
+
+        logger.debug(
+            'file-operations - readFile',
+            'File read successfully',
+            { filePath, contentLength: content.length }
+        );
+
+        return content;
+
+    } catch (error) {
+        if (error instanceof FileOperationError) {
+            throw error;
+        }
+
+        logger.error('file-operations - readFile', 'Failed to read file', error);
+        throw new FileOperationError('Failed to read file', {
+            filePath,
+            cause: error
+        });
+    }
+};
+
+/**
+ * Filters SKIP-ANALYSIS patterns from code content
+ * Why: Allows developers to exclude specific code from analysis
+ *
+ * Supports two patterns:
+ * 1. Single line: // SKIP-ANALYSIS (excludes next line)
+ * 2. Block: // SKIP_ANALYSIS_BLOCK ... // SKIP_ANALYSIS_BLOCK (excludes block)
+ *
+ * @param {string} content - File content to filter
+ * @returns {string} Filtered content
+ */
+const filterSkipAnalysis = (content) => {
+    logger.debug(
+        'file-operations - filterSkipAnalysis',
+        'Filtering SKIP-ANALYSIS patterns',
+        { originalLength: content.length }
+    );
+
+    const lines = content.split('\n');
+    let skipNext = false;
+    let inSkipBlock = false;
+
+    // Why: Use map instead of filter to preserve line numbers for error reporting
+    // Empty lines maintain original line number mapping
+    const filteredLines = lines.map((line) => {
+        // Detect single-line SKIP-ANALYSIS
+        if (line.includes('// SKIP-ANALYSIS')) {
+            skipNext = true;
+            return ''; // Preserve line number
+        }
+
+        // Detect SKIP_ANALYSIS_BLOCK (toggle block state)
+        if (line.includes('// SKIP_ANALYSIS_BLOCK')) {
+            inSkipBlock = !inSkipBlock;
+            return ''; // Preserve line number
+        }
+
+        // Skip lines inside block
+        if (inSkipBlock) {
+            return '';
+        }
+
+        // Skip next line after single SKIP-ANALYSIS
+        if (skipNext) {
+            skipNext = false;
+            return '';
+        }
+
+        return line;
+    });
+
+    const filtered = filteredLines.join('\n');
+
+    logger.debug(
+        'file-operations - filterSkipAnalysis',
+        'Filtering complete',
+        {
+            originalLength: content.length,
+            filteredLength: filtered.length,
+            linesRemoved: lines.length - filteredLines.filter(l => l !== '').length
+        }
+    );
+
+    return filtered;
+};
+
+/**
+ * Validates file extension against allowed list
+ * Why: Pre-commit hook should only analyze specific file types
+ *
+ * @param {string} filePath - Path to file
+ * @param {Array<string>} allowedExtensions - Array of extensions (e.g., ['.java', '.xml'])
+ * @returns {boolean} True if extension is allowed
+ */
+const hasAllowedExtension = (filePath, allowedExtensions = []) => {
+    if (allowedExtensions.length === 0) {
+        return true; // No filter, all allowed
+    }
+
+    const ext = path.extname(filePath).toLowerCase();
+    const isAllowed = allowedExtensions.some(allowed =>
+        ext === allowed.toLowerCase()
+    );
+
+    logger.debug(
+        'file-operations - hasAllowedExtension',
+        'Extension check',
+        { filePath, ext, allowedExtensions, isAllowed }
+    );
+
+    return isAllowed;
+};
+
+/**
+ * Filters files by size and extension
+ * Why: Batch validation of files before processing
+ *
+ * @param {Array<string>} files - Array of file paths
+ * @param {Object} options - Filter options
+ * @param {number} options.maxSize - Max file size in bytes
+ * @param {Array<string>} options.extensions - Allowed extensions
+ * @returns {Promise<Array<Object>>} Filtered files with metadata
+ *
+ * Returned object structure:
+ * [
+ *   {
+ *     path: string,           // File path
+ *     size: number,           // Size in bytes
+ *     valid: boolean,         // Whether file passes filters
+ *     reason: string          // Why file was filtered (if valid=false)
+ *   }
+ * ]
+ */
+const filterFiles = async (files, { maxSize = 100000, extensions = [] } = {}) => {
+    logger.debug(
+        'file-operations - filterFiles',
+        'Filtering files',
+        { fileCount: files.length, maxSize, extensions }
+    );
+
+    const results = await Promise.allSettled(
+        files.map(async (filePath) => {
+            // Check extension first (fast)
+            if (!hasAllowedExtension(filePath, extensions)) {
+                return {
+                    path: filePath,
+                    size: 0,
+                    valid: false,
+                    reason: 'Extension not allowed'
+                };
+            }
+
+            // Check if file exists
+            const exists = await fileExists(filePath);
+            if (!exists) {
+                return {
+                    path: filePath,
+                    size: 0,
+                    valid: false,
+                    reason: 'File not found'
+                };
+            }
+
+            // Check size
+            try {
+                const size = await getFileSize(filePath);
+
+                if (size > maxSize) {
+                    return {
+                        path: filePath,
+                        size,
+                        valid: false,
+                        reason: `File too large (${size} > ${maxSize})`
+                    };
+                }
+
+                return {
+                    path: filePath,
+                    size,
+                    valid: true,
+                    reason: null
+                };
+
+            } catch (error) {
+                return {
+                    path: filePath,
+                    size: 0,
+                    valid: false,
+                    reason: `Error reading file: ${error.message}`
+                };
+            }
+        })
+    );
+
+    // Extract successful results
+    const fileMetadata = results
+        .filter(r => r.status === 'fulfilled')
+        .map(r => r.value);
+
+    const validCount = fileMetadata.filter(f => f.valid).length;
+
+    logger.debug(
+        'file-operations - filterFiles',
+        'Filtering complete',
+        {
+            totalFiles: files.length,
+            validFiles: validCount,
+            invalidFiles: fileMetadata.length - validCount
+        }
+    );
+
+    return fileMetadata;
+};
+
+/**
+ * Reads multiple files in parallel with filtering
+ * Why: Efficiently loads file contents for analysis
+ *
+ * @param {Array<string>} files - Array of file paths
+ * @param {Object} options - Read options
+ * @param {number} options.maxSize - Max file size
+ * @param {boolean} options.applySkipFilter - Apply SKIP-ANALYSIS filtering
+ * @returns {Promise<Array<Object>>} Files with content
+ *
+ * Returned object structure:
+ * [
+ *   {
+ *     path: string,           // File path
+ *     content: string,        // File content (filtered if requested)
+ *     size: number,           // Original size in bytes
+ *     error: Error            // Error if read failed
+ *   }
+ * ]
+ */
+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,
+    fileExists,
+    readFile,
+    filterSkipAnalysis,
+    hasAllowedExtension,
+    filterFiles,
+    readMultipleFiles
+};