agentsqripts/cli/lib/helpFormatter.js

Comprehensive static code analysis toolkit for identifying technical debt, security vulnerabilities, performance issues, and code quality problems

/**
 * @file Centralized help system providing consistent CLI documentation across all analysis tools
 * @description Single responsibility: Generate standardized help output with flexible formatting options
 * 
 * This help formatter module ensures consistent documentation presentation across all
 * AgentSqripts CLI tools while providing flexible configuration for tool-specific content.
 * It implements standardized sections (options, examples, output descriptions) with
 * customizable additional sections to accommodate different analysis tool requirements.
 * 
 * Design rationale:
 * - Consistent help formatting reduces learning curve across multiple CLI tools
 * - Flexible section system accommodates tool-specific documentation requirements
 * - Standardized layout improves user experience and command discoverability
 * - Configuration-driven approach enables easy maintenance and updates
 * - Function factory pattern enables both direct usage and pre-configured help functions
 */

/**
 * Format and display help information for CLI tools
 * @param {Object} config - Help configuration
 * @param {string} config.command - Command name
 * @param {string} config.description - Tool description
 * @param {Array} config.options - Array of option objects
 * @param {string} config.modes - Analysis modes description
 * @param {Array} config.examples - Example usage strings
 * @param {string} config.output - Output description
 * @param {Object} config.sections - Additional sections (e.g., issue types, categories)
 */
function showHelp(config) {
  const {
    command,
    description,
    options = [],
    modes,
    examples = [],
    output,
    sections = {}
  } = config;

  // Header
  console.log(`Usage: node ${command} [OPTIONS] <path>\n`);
  
  // Description
  console.log(`${description}\n`);
  
  // Options
  if (options.length > 0) {
    console.log('OPTIONS:');
    options.forEach(opt => {
      console.log(`  ${opt.flag.padEnd(24)} ${opt.description}`);
    });
    console.log('');
  }
  
  // Modes
  if (modes) {
    console.log('Analysis Modes:');
    console.log(modes);
    console.log('');
  }
  
  // Examples
  if (examples.length > 0) {
    console.log('Examples:');
    examples.forEach(example => {
      console.log(`  ${example}`);
    });
    console.log('');
  }
  
  // Output description
  if (output) {
    console.log('OUTPUT:');
    console.log(output);
    console.log('');
  }
  
  // Additional sections (issue types, categories, etc.)
  Object.entries(sections).forEach(([title, content]) => {
    console.log(`${title}:`);
    console.log(content);
    console.log('');
  });
}

/**
 * Create a showHelp function with predefined configuration
 * @param {Object} config - Help configuration
 * @returns {Function} Configured showHelp function
 */
function createHelpFunction(config) {
  return () => showHelp(config);
}

module.exports = {
  showHelp,
  createHelpFunction
};