agentsqripts/lib/utils/cliHelpers.js

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

/**
 * @file Command-line interface helper utilities for consistent tool behavior
 * @description Single responsibility: Provide foundational CLI operations with standardized argument processing
 * 
 * This utility module provides essential command-line interface helpers that standardize
 * argument parsing, path resolution, and option handling across all AgentSqripts CLI tools.
 * It implements consistent parameter processing, validation, and error handling to ensure
 * uniform user experience and reliable tool operation.
 * 
 * Design rationale:
 * - Standardized argument parsing ensures consistent CLI behavior across all tools
 * - Flexible option handling supports diverse analysis tool requirements with common patterns
 * - Path resolution and validation prevent common CLI usage errors
 * - Format and output standardization enables consistent tool integration workflows
 * - Comprehensive parameter support covers filtering, thresholds, and customization needs
 * 
 * CLI standardization framework:
 * - Target path detection with intelligent defaults for user convenience
 * - Output format specification supporting detailed, summary, and JSON formats
 * - File output configuration for analysis result persistence and integration
 * - Filtering and threshold parameters for customizable analysis scope
 * - Color output control for terminal compatibility and accessibility
 */

const path = require('path');

/**
 * Parse command line arguments
 * @param {Array} args - Command line arguments
 * @returns {Object} Parsed arguments
 */
function parseCliArgs(args) {
  const targetPath = args.find(arg => !arg.startsWith('--')) || '.';
  const format = args.includes('--format') ? 
    args[args.indexOf('--format') + 1] : 'detailed';
  const output = args.includes('--output') ? 
    args[args.indexOf('--output') + 1] : null;
  const filter = args.includes('--filter') ? 
    args[args.indexOf('--filter') + 1] : null;
  const threshold = args.includes('--threshold') ? 
    args[args.indexOf('--threshold') + 1] : null;
  const enableColors = !args.includes('--no-colors');
  
  return {
    targetPath,
    format,
    output,
    filter,
    threshold,
    enableColors
  };
}

/**
 * Validate target path
 * @param {string} targetPath - Path to validate
 * @returns {boolean} True if valid
 */
function validatePath(targetPath) {
  try {
    require('fs').statSync(targetPath);
    return true;
  } catch (error) {
    console.error(`Error: Path '${targetPath}' does not exist`);
    return false;
  }
}

/**
 * Get absolute path
 * @param {string} targetPath - Path to resolve
 * @returns {string} Absolute path
 */
function getAbsolutePath(targetPath) {
  return path.resolve(targetPath);
}

/**
 * Check if should show help
 * @param {Array} args - Command line arguments
 * @returns {boolean} True if should show help
 */
function shouldShowHelp(args) {
  return args.includes('--help') || args.length === 0;
}

module.exports = {
  parseCliArgs,
  validatePath,
  getAbsolutePath,
  shouldShowHelp
};