claude-mem/scripts/anti-pattern-test/detect-error-handling-antipatterns.ts

#!/usr/bin/env bun
/**
 * Error Handling Anti-Pattern Detector
 *
 * Detects try-catch anti-patterns that cause silent failures and debugging nightmares.
 * Run this before committing code that touches error handling.
 *
 * Based on hard-learned lessons: defensive try-catch wastes 10+ hours of debugging time.
 */

import { readFileSync, readdirSync, statSync } from 'fs';
import { join, relative } from 'path';

interface AntiPattern {
  file: string;
  line: number;
  pattern: string;
  severity: 'ISSUE' | 'APPROVED_OVERRIDE';
  description: string;
  code: string;
  overrideReason?: string;
}

const CRITICAL_PATHS = [
  'SDKAgent.ts',
  'GeminiAgent.ts',
  'OpenRouterAgent.ts',
  'SessionStore.ts',
  'worker-service.ts'
];

function findFilesRecursive(dir: string, pattern: RegExp): string[] {
  const files: string[] = [];

  const items = readdirSync(dir);
  for (const item of items) {
    const fullPath = join(dir, item);
    const stat = statSync(fullPath);

    if (stat.isDirectory()) {
      if (!item.startsWith('.') && item !== 'node_modules' && item !== 'dist' && item !== 'plugin') {
        files.push(...findFilesRecursive(fullPath, pattern));
      }
    } else if (pattern.test(item)) {
      files.push(fullPath);
    }
  }

  return files;
}

function detectAntiPatterns(filePath: string, projectRoot: string): AntiPattern[] {
  const content = readFileSync(filePath, 'utf-8');
  const lines = content.split('\n');
  const antiPatterns: AntiPattern[] = [];
  const relPath = relative(projectRoot, filePath);
  const isCriticalPath = CRITICAL_PATHS.some(cp => filePath.includes(cp));

  // Detect error message string matching for type detection (line-by-line patterns)
  for (let i = 0; i < lines.length; i++) {
    const line = lines[i];
    const trimmed = line.trim();

    // Check for [ANTI-PATTERN IGNORED] on the same or previous line
    const hasOverride = trimmed.includes('[ANTI-PATTERN IGNORED]') ||
                       (i > 0 && lines[i - 1].includes('[ANTI-PATTERN IGNORED]'));
    const overrideMatch = (trimmed + (i > 0 ? lines[i - 1] : '')).match(/\[ANTI-PATTERN IGNORED\]:\s*(.+)/i);
    const overrideReason = overrideMatch?.[1]?.trim();

    // CRITICAL: Error message string matching for type detection
    // Patterns like: errorMessage.includes('connection') or error.message.includes('timeout')
    const errorStringMatchPatterns = [
      /error(?:Message|\.message)\s*\.includes\s*\(\s*['"`](\w+)['"`]\s*\)/i,
      /(?:err|e)\.message\s*\.includes\s*\(\s*['"`](\w+)['"`]\s*\)/i,
      /String\s*\(\s*(?:error|err|e)\s*\)\s*\.includes\s*\(\s*['"`](\w+)['"`]\s*\)/i,
    ];

    for (const pattern of errorStringMatchPatterns) {
      const match = trimmed.match(pattern);
      if (match) {
        const matchedString = match[1];
        // Common generic patterns that are too broad
        const genericPatterns = ['error', 'fail', 'connection', 'timeout', 'not', 'invalid', 'unable'];
        const isGeneric = genericPatterns.some(gp => matchedString.toLowerCase().includes(gp));

        if (hasOverride && overrideReason) {
          antiPatterns.push({
            file: relPath,
            line: i + 1,
            pattern: 'ERROR_STRING_MATCHING',
            severity: 'APPROVED_OVERRIDE',
            description: `Error type detection via string matching on "${matchedString}" - approved override.`,
            code: trimmed,
            overrideReason
          });
        } else {
          antiPatterns.push({
            file: relPath,
            line: i + 1,
            pattern: 'ERROR_STRING_MATCHING',
            severity: 'ISSUE',
            description: `Error type detection via string matching on "${matchedString}" - fragile and masks the real error. Log the FULL error object. We don't care about pretty error handling, we care about SEEING what went wrong.`,
            code: trimmed
          });
        }
      }
    }

    // HIGH: Logging only error.message instead of the full error object
    // Patterns like: logger.error('X', 'Y', {}, error.message) or console.error(error.message)
    const partialErrorLoggingPatterns = [
      /logger\.(error|warn|info|debug|failure)\s*\([^)]*,\s*(?:error|err|e)\.message\s*\)/,
      /logger\.(error|warn|info|debug|failure)\s*\([^)]*\{\s*(?:error|err|e):\s*(?:error|err|e)\.message\s*\}/,
      /console\.(error|warn|log)\s*\(\s*(?:error|err|e)\.message\s*\)/,
      /console\.(error|warn|log)\s*\(\s*['"`][^'"`]+['"`]\s*,\s*(?:error|err|e)\.message\s*\)/,
    ];

    for (const pattern of partialErrorLoggingPatterns) {
      if (pattern.test(trimmed)) {
        if (hasOverride && overrideReason) {
          antiPatterns.push({
            file: relPath,
            line: i + 1,
            pattern: 'PARTIAL_ERROR_LOGGING',
            severity: 'APPROVED_OVERRIDE',
            description: 'Logging only error.message instead of full error object - approved override.',
            code: trimmed,
            overrideReason
          });
        } else {
          antiPatterns.push({
            file: relPath,
            line: i + 1,
            pattern: 'PARTIAL_ERROR_LOGGING',
            severity: 'ISSUE',
            description: 'Logging only error.message HIDES the stack trace, error type, and all properties. ALWAYS pass the full error object - you need the complete picture, not a summary.',
            code: trimmed
          });
        }
      }
    }

    // CRITICAL: Catch-all error type guessing based on message content
    // Pattern: if (errorMessage.includes('X') || errorMessage.includes('Y'))
    const multipleIncludes = trimmed.match(/(?:error(?:Message|\.message)|(?:err|e)\.message).*\.includes.*\|\|.*\.includes/i);
    if (multipleIncludes) {
      if (hasOverride && overrideReason) {
        antiPatterns.push({
          file: relPath,
          line: i + 1,
          pattern: 'ERROR_MESSAGE_GUESSING',
          severity: 'APPROVED_OVERRIDE',
          description: 'Multiple string checks on error message to guess error type - approved override.',
          code: trimmed,
          overrideReason
        });
      } else {
        antiPatterns.push({
          file: relPath,
          line: i + 1,
          pattern: 'ERROR_MESSAGE_GUESSING',
          severity: 'ISSUE',
          description: 'Multiple string checks on error message to guess error type. STOP GUESSING. Log the FULL error object. We don\'t care what the library throws - we care about SEEING the error when it happens.',
          code: trimmed
        });
      }
    }
  }

  // Track try-catch blocks
  let inTry = false;
  let tryStartLine = 0;
  let tryLines: string[] = [];
  let braceDepth = 0;
  let catchStartLine = 0;
  let catchLines: string[] = [];
  let inCatch = false;

  for (let i = 0; i < lines.length; i++) {
    const line = lines[i];
    const trimmed = line.trim();

    // Detect standalone promise empty catch: .catch(() => {})
    const emptyPromiseCatch = trimmed.match(/\.catch\s*\(\s*\(\s*\)\s*=>\s*\{\s*\}\s*\)/);
    if (emptyPromiseCatch) {
      antiPatterns.push({
        file: relPath,
        line: i + 1,
        pattern: 'PROMISE_EMPTY_CATCH',
        severity: 'ISSUE',
        description: 'Promise .catch() with empty handler - errors disappear into the void.',
        code: trimmed
      });
    }

    // Detect standalone promise catch without logging: .catch(err => ...)
    const promiseCatchMatch = trimmed.match(/\.catch\s*\(\s*(?:\(\s*)?(\w+)(?:\s*\))?\s*=>/);
    if (promiseCatchMatch && !emptyPromiseCatch) {
      // Look ahead up to 10 lines to see if there's logging in the handler body
      let catchBody = trimmed.substring(promiseCatchMatch.index || 0);
      let braceCount = (catchBody.match(/{/g) || []).length - (catchBody.match(/}/g) || []).length;

      // Collect subsequent lines if the handler spans multiple lines
      let lookAhead = 0;
      while (braceCount > 0 && lookAhead < 10 && i + lookAhead + 1 < lines.length) {
        lookAhead++;
        const nextLine = lines[i + lookAhead];
        catchBody += '\n' + nextLine;
        braceCount += (nextLine.match(/{/g) || []).length - (nextLine.match(/}/g) || []).length;
      }

      const hasLogging = catchBody.match(/logger\.(error|warn|debug|info|failure)/) ||
                        catchBody.match(/console\.(error|warn)/);

      if (!hasLogging && lookAhead > 0) {  // Only flag if it's actually a multi-line handler
        antiPatterns.push({
          file: relPath,
          line: i + 1,
          pattern: 'PROMISE_CATCH_NO_LOGGING',
          severity: 'ISSUE',
          description: 'Promise .catch() without logging - errors are silently swallowed.',
          code: catchBody.trim().split('\n').slice(0, 5).join('\n')
        });
      }
    }

    // Detect try block start
    if (trimmed.match(/^\s*try\s*{/) || trimmed.match(/}\s*try\s*{/)) {
      inTry = true;
      tryStartLine = i + 1;
      tryLines = [line];
      braceDepth = 1;
      continue;
    }

    // Track try block content
    if (inTry && !inCatch) {
      tryLines.push(line);

      // Count braces to find try block end
      const openBraces = (line.match(/{/g) || []).length;
      const closeBraces = (line.match(/}/g) || []).length;
      braceDepth += openBraces - closeBraces;

      // Found catch
      if (trimmed.match(/}\s*catch\s*(\(|{)/)) {
        inCatch = true;
        catchStartLine = i + 1;
        catchLines = [line];
        braceDepth = 1;
        continue;
      }
    }

    // Track catch block
    if (inCatch) {
      catchLines.push(line);

      const openBraces = (line.match(/{/g) || []).length;
      const closeBraces = (line.match(/}/g) || []).length;
      braceDepth += openBraces - closeBraces;

      // Catch block ended
      if (braceDepth === 0) {
        // Analyze the try-catch block
        analyzeTryCatchBlock(
          filePath,
          relPath,
          tryStartLine,
          tryLines,
          catchStartLine,
          catchLines,
          isCriticalPath,
          antiPatterns
        );

        // Reset
        inTry = false;
        inCatch = false;
        tryLines = [];
        catchLines = [];
      }
    }
  }

  return antiPatterns;
}

function analyzeTryCatchBlock(
  filePath: string,
  relPath: string,
  tryStartLine: number,
  tryLines: string[],
  catchStartLine: number,
  catchLines: string[],
  isCriticalPath: boolean,
  antiPatterns: AntiPattern[]
): void {
  const tryBlock = tryLines.join('\n');
  const catchBlock = catchLines.join('\n');

  // CRITICAL: Empty catch block
  const catchContent = catchBlock
    .replace(/}\s*catch\s*\([^)]*\)\s*{/, '') // Remove catch signature
    .replace(/}\s*catch\s*{/, '') // Remove catch without param
    .replace(/}$/, '') // Remove closing brace
    .trim();

  // Check for comment-only catch blocks
  const nonCommentContent = catchContent
    .split('\n')
    .filter(line => {
      const t = line.trim();
      return t && !t.startsWith('//') && !t.startsWith('/*') && !t.startsWith('*');
    })
    .join('\n')
    .trim();

  if (!nonCommentContent || nonCommentContent === '') {
    antiPatterns.push({
      file: relPath,
      line: catchStartLine,
      pattern: 'EMPTY_CATCH',
      severity: 'CRITICAL',
      description: 'Empty catch block - errors are silently swallowed. User will waste hours debugging.',
      code: catchBlock.trim()
    });
  }

  // Check for [ANTI-PATTERN IGNORED] marker
  const overrideMatch = catchContent.match(/\/\/\s*\[ANTI-PATTERN IGNORED\]:\s*(.+)/i);
  const overrideReason = overrideMatch?.[1]?.trim();

  // CRITICAL: No logging in catch block (unless explicitly approved)
  const hasLogging = catchContent.match(/logger\.(error|warn|debug|info|failure)/);
  const hasConsoleError = catchContent.match(/console\.(error|warn)/);
  const hasStderr = catchContent.match(/process\.stderr\.write/);
  const hasThrow = catchContent.match(/throw/);

  if (!hasLogging && !hasConsoleError && !hasStderr && !hasThrow && nonCommentContent) {
    if (overrideReason) {
      antiPatterns.push({
        file: relPath,
        line: catchStartLine,
        pattern: 'NO_LOGGING_IN_CATCH',
        severity: 'APPROVED_OVERRIDE',
        description: 'Catch block has no logging - approved override.',
        code: catchBlock.trim(),
        overrideReason
      });
    } else {
      antiPatterns.push({
        file: relPath,
        line: catchStartLine,
        pattern: 'NO_LOGGING_IN_CATCH',
        severity: 'ISSUE',
        description: 'Catch block has no logging - errors occur invisibly.',
        code: catchBlock.trim()
      });
    }
  }

  // HIGH: Large try block (>10 lines)
  const significantTryLines = tryLines.filter(line => {
    const t = line.trim();
    return t && !t.startsWith('//') && t !== '{' && t !== '}';
  }).length;

  if (significantTryLines > 10) {
    antiPatterns.push({
      file: relPath,
      line: tryStartLine,
      pattern: 'LARGE_TRY_BLOCK',
      severity: 'ISSUE',
      description: `Try block has ${significantTryLines} lines - too broad. Multiple errors lumped together.`,
      code: `${tryLines.slice(0, 3).join('\n')}\n... (${significantTryLines} lines) ...`
    });
  }

  // HIGH: Generic catch without type checking
  const catchParam = catchBlock.match(/catch\s*\(([^)]+)\)/)?.[1]?.trim();
  const hasTypeCheck = catchContent.match(/instanceof\s+Error/) ||
                       catchContent.match(/\.name\s*===/) ||
                       catchContent.match(/typeof.*===\s*['"]object['"]/);

  if (catchParam && !hasTypeCheck && nonCommentContent) {
    antiPatterns.push({
      file: relPath,
      line: catchStartLine,
      pattern: 'GENERIC_CATCH',
      severity: 'ISSUE',
      description: 'Catch block handles all errors identically - no error type discrimination.',
      code: catchBlock.trim()
    });
  }

  // CRITICAL on critical paths: Catch-and-continue
  if (isCriticalPath && nonCommentContent && !hasThrow) {
    const hasReturn = catchContent.match(/return/);
    const hasProcessExit = catchContent.match(/process\.exit/);
    const terminatesExecution = hasReturn || hasProcessExit;

    if (!terminatesExecution && hasLogging) {
      if (overrideReason) {
        antiPatterns.push({
          file: relPath,
          line: catchStartLine,
          pattern: 'CATCH_AND_CONTINUE_CRITICAL_PATH',
          severity: 'APPROVED_OVERRIDE',
          description: 'Critical path continues after error - anti-pattern ignored.',
          code: catchBlock.trim(),
          overrideReason
        });
      } else {
        antiPatterns.push({
          file: relPath,
          line: catchStartLine,
          pattern: 'CATCH_AND_CONTINUE_CRITICAL_PATH',
          severity: 'ISSUE',
          description: 'Critical path continues after error - may cause silent data corruption.',
          code: catchBlock.trim()
        });
      }
    }
  }

}

function formatReport(antiPatterns: AntiPattern[]): string {
  const issues = antiPatterns.filter(a => a.severity === 'ISSUE');
  const approved = antiPatterns.filter(a => a.severity === 'APPROVED_OVERRIDE');

  if (antiPatterns.length === 0) {
    return '✅ No error handling anti-patterns detected!\n';
  }

  let report = '\n';
  report += '═══════════════════════════════════════════════════════════════\n';
  report += '  ERROR HANDLING ANTI-PATTERNS DETECTED\n';
  report += '═══════════════════════════════════════════════════════════════\n\n';
  report += `Found ${issues.length} anti-patterns that must be fixed:\n`;
  if (approved.length > 0) {
    report += `  ⚪ APPROVED OVERRIDES: ${approved.length}\n`;
  }
  report += '\n';

  if (issues.length > 0) {
    report += '❌ ISSUES TO FIX:\n';
    report += '─────────────────────────────────────────────────────────────\n\n';
    for (const ap of issues) {
      report += `📁 ${ap.file}:${ap.line} - ${ap.pattern}\n`;
      report += `   ${ap.description}\n\n`;
    }
  }

  if (approved.length > 0) {
    report += '⚪ APPROVED OVERRIDES (Review reasons for accuracy):\n';
    report += '─────────────────────────────────────────────────────────────\n\n';
    for (const ap of approved) {
      report += `📁 ${ap.file}:${ap.line} - ${ap.pattern}\n`;
      report += `   Reason: ${ap.overrideReason}\n`;
      report += `   Code:\n`;
      const codeLines = ap.code.split('\n');
      for (const line of codeLines.slice(0, 3)) {
        report += `   ${line}\n`;
      }
      if (codeLines.length > 3) {
        report += `   ... (${codeLines.length - 3} more lines)\n`;
      }
      report += '\n';
    }
  }

  report += '═══════════════════════════════════════════════════════════════\n';
  report += 'REMINDER: Every try-catch must answer these questions:\n';
  report += '1. What SPECIFIC error am I catching? (Name it)\n';
  report += '2. Show me documentation proving this error can occur\n';
  report += '3. Why can\'t this error be prevented?\n';
  report += '4. What will the catch block DO? (Log + rethrow? Fallback?)\n';
  report += '5. Why shouldn\'t this error propagate to the caller?\n';
  report += '\n';
  report += 'To ignore an anti-pattern, add: // [ANTI-PATTERN IGNORED]: reason\n';
  report += '═══════════════════════════════════════════════════════════════\n\n';

  return report;
}

// Main execution
const projectRoot = process.cwd();
const srcDir = join(projectRoot, 'src');

console.log('🔍 Scanning for error handling anti-patterns...\n');

const tsFiles = findFilesRecursive(srcDir, /\.ts$/);
console.log(`Found ${tsFiles.length} TypeScript files\n`);

let allAntiPatterns: AntiPattern[] = [];

for (const file of tsFiles) {
  const patterns = detectAntiPatterns(file, projectRoot);
  allAntiPatterns = allAntiPatterns.concat(patterns);
}

const report = formatReport(allAntiPatterns);
console.log(report);

// Exit with error code if any issues found
const issues = allAntiPatterns.filter(a => a.severity === 'ISSUE');
if (issues.length > 0) {
  console.error(`❌ FAILED: ${issues.length} error handling anti-patterns must be fixed.\n`);
  process.exit(1);
}

process.exit(0);