agentsqripts/lib/scalability/fileIODetector.js

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

/**
 * @file File I/O detector for synchronous operation identification and scalability optimization
 * @description Single responsibility: Detect file I/O operations that block request processing in scalable applications
 * 
 * This detector identifies file system operations that can block the event loop and prevent
 * concurrent request handling in Node.js applications. It analyzes synchronous file operations,
 * inefficient file handling patterns, and I/O-intensive code in request-critical paths to
 * prevent scalability bottlenecks and improve application throughput.
 * 
 * Design rationale:
 * - Context-aware analysis distinguishes between acceptable file operations and scalability threats
 * - Pattern-based detection efficiently identifies blocking file I/O operations
 * - Request path analysis focuses on performance-critical code sections
 * - Severity assessment considers operation impact on concurrent request processing
 * - Conservative approach flags potential bottlenecks before they impact production performance
 * 
 * File I/O detection scope:
 * - Synchronous file operations (fs.readFileSync, fs.writeFileSync) in request handlers
 * - Large file processing operations that block event loop execution
 * - Inefficient file handling patterns that reduce application scalability
 * - I/O-intensive operations in performance-critical request processing paths
 * - File system operations without proper async/await patterns for concurrent execution
 */

/**
 * Detects file I/O operations in request paths
 * @param {string} content - File content
 * @param {string} filePath - Path to the file
 * @returns {Array} Array of file I/O issues
 */
function detectFileIO(content, filePath) {
  const issues = [];
  const fileIOCalls = [
    'fs.readFile(',
    'fs.writeFile(',
    'fs.appendFile(',
    'fs.createReadStream(',
    'fs.createWriteStream(',
    'require.resolve(',
    'import('
  ];
  
  // Skip files that are clearly build/setup/demo related
  const isSetupFile = filePath.includes('scripts') || 
                     filePath.includes('build') || 
                     filePath.includes('config') ||
                     filePath.includes('setup') ||
                     filePath.includes('demo') ||
                     filePath.includes('debug') ||
                     filePath.includes('test') ||
                     filePath.includes('example');
  
  // Skip analysis tools that legitimately read source files
  const isAnalysisTool = filePath.includes('/lib/') && (
    filePath.includes('analyzer') ||
    filePath.includes('detector') ||
    filePath.includes('analysis') ||
    filePath.includes('helpers/') ||
    content.includes('analyze') ||
    content.includes('detect') ||
    content.includes('audit') ||
    filePath.endsWith('FileAnalyzer.js') ||
    filePath.endsWith('analyzeSingleFile.js')
  );
  
  // Skip CLI tools that process files as their primary function
  const isCLITool = filePath.includes('/cli/') || content.includes('#!/usr/bin/env node');
  
  // Skip core utilities that provide file operations as their main function
  const isFileUtility = filePath.includes('fileOperations') || filePath.includes('fileSystemUtils');
  
  if (!isSetupFile && !isAnalysisTool && !isCLITool && !isFileUtility) {
    fileIOCalls.forEach(call => {
      if (content.includes(call)) {
        issues.push({
          type: 'per_request_io',
          severity: 'MEDIUM',
          category: 'Infrastructure',
          location: filePath,
          pattern: call,
          summary: `File I/O '${call}' found outside startup/init — likely per-request`,
          recommendation: 'Move to startup/init phase, cache in memory, or use streaming',
          impact: 'File system operations in request path hurt response times'
        });
      }
    });
  }
  
  return issues;
}

module.exports = {
  detectFileIO
};