codesummary 1.0.0

package/src/errorHandler.js

@@ -0,0 +1,343 @@
+import chalk from 'chalk';
+import path from 'path';
+import fs from 'fs';
+import os from 'os';
+
+/**
+ * Error Handler and Validation Utilities for CodeSummary
+ * Centralized error handling and validation logic
+ */
+export class ErrorHandler {
+  /**
+   * Handle and format CLI errors consistently
+   * @param {Error} error - The error object
+   * @param {string} context - Context where error occurred
+   * @param {boolean} exit - Whether to exit process
+   */
+  static handleError(error, context = 'Unknown', exit = true) {
+    console.error(chalk.red('ERROR:'), chalk.white(error.message));
+    
+    if (process.env.NODE_ENV === 'development' || process.env.DEBUG) {
+      console.error(chalk.gray('Context:'), context);
+      console.error(chalk.gray('Stack:'), error.stack);
+    }
+
+    if (exit) {
+      process.exit(1);
+    }
+  }
+
+  /**
+   * Handle configuration validation errors
+   * @param {Error} error - Configuration error
+   * @param {string} configPath - Path to config file
+   */
+  static handleConfigError(error, configPath) {
+    console.error(chalk.red('CONFIGURATION ERROR'));
+    console.error(chalk.gray(`Config file: ${configPath}`));
+    console.error(chalk.white(error.message));
+    console.error(chalk.yellow('\nTry running: codesummary --reset-config'));
+    process.exit(1);
+  }
+
+  /**
+   * Handle file system errors with helpful messages
+   * @param {Error} error - File system error
+   * @param {string} operation - The operation being performed
+   * @param {string} filePath - Path involved in the operation
+   */
+  static handleFileSystemError(error, operation, filePath) {
+    let message = `Failed to ${operation}`;
+    
+    switch (error.code) {
+      case 'ENOENT':
+        message = `File or directory not found: ${filePath}`;
+        break;
+      case 'EACCES':
+      case 'EPERM':
+        message = `Permission denied: ${filePath}`;
+        console.error(chalk.yellow('SUGGESTION: Try running with elevated privileges or check file permissions'));
+        break;
+      case 'ENOSPC':
+        message = 'No space left on device';
+        break;
+      case 'EMFILE':
+      case 'ENFILE':
+        message = 'Too many open files';
+        break;
+      default:
+        message = `${message}: ${error.message}`;
+    }
+
+    console.error(chalk.red('FILE SYSTEM ERROR:'), chalk.white(message));
+    
+    if (error.code === 'EACCES' || error.code === 'EPERM') {
+      console.error(chalk.yellow('SUGGESTIONS:'));
+      console.error(chalk.gray('  - Check file/directory permissions'));
+      console.error(chalk.gray('  - Try running as administrator/sudo'));
+      console.error(chalk.gray('  - Ensure the file is not locked by another process'));
+    }
+  }
+
+  /**
+   * Handle PDF generation errors
+   * @param {Error} error - PDF generation error
+   * @param {string} outputPath - Intended output path
+   */
+  static handlePDFError(error, outputPath) {
+    console.error(chalk.red('PDF GENERATION FAILED'));
+    console.error(chalk.gray(`Output path: ${outputPath}`));
+    
+    if (error.message.includes('ENOSPC')) {
+      console.error(chalk.white('Not enough disk space to generate PDF'));
+      console.error(chalk.yellow('SUGGESTION: Try freeing up disk space or using a different output location'));
+    } else if (error.message.includes('EACCES')) {
+      console.error(chalk.white('Permission denied writing to output location'));
+      console.error(chalk.yellow('SUGGESTION: Check permissions or try a different output directory'));
+    } else {
+      console.error(chalk.white(error.message));
+    }
+    
+    process.exit(1);
+  }
+
+  /**
+   * Validate file path for security and validity
+   * @param {string} filePath - Path to validate
+   * @param {object} options - Validation options
+   * @returns {boolean} True if valid
+   */
+  static validatePath(filePath, options = {}) {
+    const { 
+      mustExist = false, 
+      mustBeAbsolute = false, 
+      allowedExtensions = null,
+      preventTraversal = true 
+    } = options;
+
+    if (!filePath || typeof filePath !== 'string') {
+      throw new Error('Invalid file path: must be a non-empty string');
+    }
+
+    // Prevent path traversal attacks
+    if (preventTraversal && (filePath.includes('..') || filePath.includes('\0'))) {
+      throw new Error('Invalid file path: path traversal detected');
+    }
+
+    // Check if path should be absolute
+    if (mustBeAbsolute && !path.isAbsolute(filePath)) {
+      throw new Error('Path must be absolute');
+    }
+
+    // Check if file must exist
+    if (mustExist && !fs.existsSync(filePath)) {
+      throw new Error(`Path does not exist: ${filePath}`);
+    }
+
+    // Check file extension if specified
+    if (allowedExtensions && allowedExtensions.length > 0) {
+      const ext = path.extname(filePath).toLowerCase();
+      if (!allowedExtensions.includes(ext)) {
+        throw new Error(`Invalid file extension. Allowed: ${allowedExtensions.join(', ')}`);
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Validate configuration object structure
+   * @param {object} config - Configuration to validate
+   * @returns {boolean} True if valid
+   */
+  static validateConfig(config) {
+    if (!config || typeof config !== 'object') {
+      throw new Error('Configuration must be an object');
+    }
+
+    // Validate output section
+    if (!config.output || typeof config.output !== 'object') {
+      throw new Error('Configuration missing output section');
+    }
+
+    if (!config.output.mode || !['relative', 'fixed'].includes(config.output.mode)) {
+      throw new Error('Output mode must be either "relative" or "fixed"');
+    }
+
+    if (config.output.mode === 'fixed' && !config.output.fixedPath) {
+      throw new Error('Fixed output mode requires fixedPath');
+    }
+
+    // Validate allowedExtensions
+    if (!Array.isArray(config.allowedExtensions)) {
+      throw new Error('allowedExtensions must be an array');
+    }
+
+    if (config.allowedExtensions.length === 0) {
+      throw new Error('At least one file extension must be allowed');
+    }
+
+    // Validate excludeDirs
+    if (!Array.isArray(config.excludeDirs)) {
+      throw new Error('excludeDirs must be an array');
+    }
+
+    // Validate styles section
+    if (!config.styles || typeof config.styles !== 'object') {
+      throw new Error('Configuration missing styles section');
+    }
+
+    // Validate settings section
+    if (!config.settings || typeof config.settings !== 'object') {
+      throw new Error('Configuration missing settings section');
+    }
+
+    if (typeof config.settings.maxFilesBeforePrompt !== 'number' || 
+        config.settings.maxFilesBeforePrompt < 1) {
+      throw new Error('maxFilesBeforePrompt must be a positive number');
+    }
+
+    return true;
+  }
+
+  /**
+   * Sanitize user input to prevent injection attacks
+   * @param {string} input - User input to sanitize
+   * @returns {string} Sanitized input
+   */
+  static sanitizeInput(input) {
+    if (typeof input !== 'string') {
+      return '';
+    }
+
+    return input
+      .replace(/[<>]/g, '') // Remove potential HTML/XML tags
+      .replace(/[\x00-\x1f\x7f-\x9f]/g, '') // Remove control characters
+      .trim()
+      .substring(0, 1000); // Limit length
+  }
+
+  /**
+   * Validate file content before processing
+   * @param {string} filePath - Path to file
+   * @param {Buffer} content - File content buffer
+   * @returns {boolean} True if content appears to be text
+   */
+  static validateFileContent(filePath, content) {
+    // Check for null bytes (common in binary files)
+    if (content.includes(0)) {
+      console.warn(chalk.yellow(`WARNING: Skipping potentially binary file: ${filePath}`));
+      return false;
+    }
+
+    // Check file size (warn for very large files)
+    const maxSize = 10 * 1024 * 1024; // 10MB
+    if (content.length > maxSize) {
+      console.warn(chalk.yellow(`WARNING: Large file detected (${Math.round(content.length / 1024 / 1024)}MB): ${filePath}`));
+      console.warn(chalk.gray('This may affect PDF generation performance'));
+    }
+
+    return true;
+  }
+
+  /**
+   * Graceful shutdown handler
+   * @param {string} signal - Signal received
+   */
+  static gracefulShutdown(signal) {
+    console.log(chalk.yellow(`\nWARNING: Received ${signal}. Shutting down gracefully...`));
+    
+    // Cleanup operations could go here
+    // For example: close open file handles, cleanup temp files, etc.
+    
+    console.log(chalk.green('SUCCESS: Cleanup completed'));
+    process.exit(0);
+  }
+
+  /**
+   * Setup global error handlers
+   */
+  static setupGlobalHandlers() {
+    // Handle uncaught exceptions
+    process.on('uncaughtException', (error) => {
+      console.error(chalk.red('UNCAUGHT EXCEPTION:'));
+      console.error(error.stack);
+      console.error(chalk.yellow('Please report this error to: https://github.com/skamoll/CodeSummary/issues'));
+      process.exit(1);
+    });
+
+    // Handle unhandled promise rejections
+    process.on('unhandledRejection', (reason, promise) => {
+      console.error(chalk.red('UNHANDLED PROMISE REJECTION:'));
+      console.error('Promise:', promise);
+      console.error('Reason:', reason);
+      console.error(chalk.yellow('Please report this error to: https://github.com/skamoll/CodeSummary/issues'));
+      process.exit(1);
+    });
+
+    // Handle graceful shutdown signals
+    process.on('SIGINT', () => ErrorHandler.gracefulShutdown('SIGINT'));
+    process.on('SIGTERM', () => ErrorHandler.gracefulShutdown('SIGTERM'));
+
+    // Handle warnings
+    process.on('warning', (warning) => {
+      if (process.env.NODE_ENV === 'development') {
+        console.warn(chalk.yellow('WARNING:'), warning.message);
+      }
+    });
+  }
+
+  /**
+   * Create context-aware error wrapper
+   * @param {string} context - Context description
+   * @returns {Function} Error wrapper function
+   */
+  static createErrorWrapper(context) {
+    return (error) => {
+      if (error.name === 'AbortError') {
+        console.log(chalk.yellow('\nWARNING: Operation cancelled by user'));
+        process.exit(0);
+      }
+      
+      ErrorHandler.handleError(error, context);
+    };
+  }
+
+  /**
+   * Validate environment and dependencies
+   */
+  static validateEnvironment() {
+    // Check Node.js version
+    const nodeVersion = process.version;
+    const majorVersion = parseInt(nodeVersion.split('.')[0].substring(1));
+    
+    if (majorVersion < 18) {
+      console.error(chalk.red('ERROR: Node.js version requirement not met'));
+      console.error(chalk.white(`Current version: ${nodeVersion}`));
+      console.error(chalk.white('Required version: >=18.0.0'));
+      console.error(chalk.yellow('Please upgrade Node.js: https://nodejs.org/'));
+      process.exit(1);
+    }
+
+    // Check available memory
+    const totalMemory = os.totalmem();
+    const freeMemory = os.freemem();
+    const memoryUsage = process.memoryUsage();
+    
+    if (freeMemory < 100 * 1024 * 1024) { // Less than 100MB free
+      console.warn(chalk.yellow('WARNING: Low system memory detected'));
+      console.warn(chalk.gray('PDF generation may be slower for large projects'));
+    }
+
+    // Check platform compatibility
+    const platform = process.platform;
+    const supportedPlatforms = ['win32', 'darwin', 'linux'];
+    
+    if (!supportedPlatforms.includes(platform)) {
+      console.warn(chalk.yellow(`WARNING: Untested platform: ${platform}`));
+      console.warn(chalk.gray('CodeSummary may not work correctly on this platform'));
+    }
+  }
+}
+
+export default ErrorHandler;

package/src/index.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import CLI from './cli.js';
+import ErrorHandler from './errorHandler.js';
+
+/**
+ * CodeSummary - Main Entry Point
+ * A cross-platform CLI tool for generating PDF documentation from source code
+ */
+
+async function main() {
+  try {
+    // Setup global error handlers and validate environment
+    ErrorHandler.setupGlobalHandlers();
+    ErrorHandler.validateEnvironment();
+
+    const cli = new CLI();
+    const args = process.argv.slice(2);
+    await cli.run(args);
+  } catch (error) {
+    ErrorHandler.handleError(error, 'Main Application');
+  }
+}
+
+// Execute main function
+main();