vibecheck-ai 2.0.1 → 5.0.0

package/bin/runners/lib/doctor/failure-signatures.js

@@ -0,0 +1,526 @@
+/**
+ * Known Failure Signatures Database
+ * 
+ * Maps common error patterns to specific diagnoses and remediation steps.
+ * This enables "legendary" instant diagnosis of environment issues.
+ */
+
+const { SEVERITY, CATEGORY, FIX_TYPE } = require('./types');
+
+/**
+ * Failure signature structure:
+ * {
+ *   id: string,           // Unique identifier
+ *   name: string,         // Human readable name
+ *   patterns: string[],   // Regex patterns to match
+ *   platforms: string[],  // ['win32', 'darwin', 'linux'] or ['all']
+ *   category: string,     // CATEGORY enum value
+ *   severity: string,     // SEVERITY enum value
+ *   diagnosis: string,    // What went wrong
+ *   remediation: string,  // How to fix
+ *   commands: object[],   // Fix commands
+ *   links: string[],      // Documentation links
+ * }
+ */
+
+const FAILURE_SIGNATURES = [
+  // ═══════════════════════════════════════════════════════════════════════════
+  // NODE / NPM ERRORS
+  // ═══════════════════════════════════════════════════════════════════════════
+  {
+    id: 'node-version-mismatch',
+    name: 'Node Version Mismatch',
+    patterns: [
+      /The engine "node" is incompatible with this module/i,
+      /error.*engine.*node.*required.*\d+/i,
+      /unsupported engine/i,
+      /NODE_MODULE_VERSION.*was compiled against/i,
+    ],
+    platforms: ['all'],
+    category: CATEGORY.RUNTIME,
+    severity: SEVERITY.ERROR,
+    diagnosis: 'Node.js version does not match project requirements',
+    remediation: 'Install the correct Node.js version specified in package.json engines field',
+    commands: [
+      { cmd: 'nvm install', desc: 'Install required Node version with nvm', safe: true },
+      { cmd: 'nvm use', desc: 'Switch to required Node version', safe: true },
+    ],
+    links: ['https://github.com/nvm-sh/nvm'],
+  },
+  {
+    id: 'npm-permission-error',
+    name: 'NPM Permission Error',
+    patterns: [
+      /EACCES.*permission denied/i,
+      /npm ERR! code EACCES/i,
+      /Error: EACCES/i,
+      /Missing write access to/i,
+    ],
+    platforms: ['darwin', 'linux'],
+    category: CATEGORY.SYSTEM,
+    severity: SEVERITY.ERROR,
+    diagnosis: 'npm lacks permission to write to global packages directory',
+    remediation: 'Fix npm permissions or use a Node version manager',
+    commands: [
+      { cmd: 'mkdir ~/.npm-global && npm config set prefix "~/.npm-global"', desc: 'Use local npm prefix', safe: true },
+      { cmd: 'export PATH=~/.npm-global/bin:$PATH', desc: 'Add to PATH (add to .bashrc/.zshrc)', safe: true },
+    ],
+    links: ['https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally'],
+  },
+  {
+    id: 'npm-cache-corrupt',
+    name: 'NPM Cache Corruption',
+    patterns: [
+      /npm ERR! code EINTEGRITY/i,
+      /EINTEGRITY.*sha512/i,
+      /Integrity checksum failed/i,
+      /npm ERR! code EBADPLATFORM/i,
+      /npm ERR! cache.*corrupt/i,
+    ],
+    platforms: ['all'],
+    category: CATEGORY.DEPENDENCIES,
+    severity: SEVERITY.ERROR,
+    diagnosis: 'npm cache is corrupted or has integrity issues',
+    remediation: 'Clear npm cache and reinstall dependencies',
+    commands: [
+      { cmd: 'npm cache clean --force', desc: 'Clear npm cache', safe: true },
+      { cmd: 'rm -rf node_modules package-lock.json && npm install', desc: 'Clean reinstall', safe: false },
+    ],
+    links: ['https://docs.npmjs.com/cli/commands/npm-cache'],
+  },
+  {
+    id: 'npm-network-error',
+    name: 'NPM Network Error',
+    patterns: [
+      /npm ERR! code ETIMEDOUT/i,
+      /npm ERR! code ENOTFOUND/i,
+      /npm ERR! network/i,
+      /npm ERR! code ECONNRESET/i,
+      /npm ERR! code ECONNREFUSED/i,
+      /getaddrinfo ENOTFOUND registry.npmjs.org/i,
+    ],
+    platforms: ['all'],
+    category: CATEGORY.NETWORK,
+    severity: SEVERITY.ERROR,
+    diagnosis: 'Cannot connect to npm registry',
+    remediation: 'Check internet connection and proxy settings',
+    commands: [
+      { cmd: 'npm config get proxy', desc: 'Check proxy setting', safe: true },
+      { cmd: 'npm config get https-proxy', desc: 'Check HTTPS proxy', safe: true },
+      { cmd: 'npm config set registry https://registry.npmjs.org/', desc: 'Reset registry URL', safe: true },
+    ],
+    links: ['https://docs.npmjs.com/cli/commands/npm-config'],
+  },
+  {
+    id: 'npm-peer-deps',
+    name: 'Peer Dependency Conflict',
+    patterns: [
+      /npm ERR! code ERESOLVE/i,
+      /ERESOLVE.*peer dep/i,
+      /Could not resolve dependency/i,
+      /peer dep missing/i,
+      /Conflicting peer dependency/i,
+    ],
+    platforms: ['all'],
+    category: CATEGORY.DEPENDENCIES,
+    severity: SEVERITY.WARNING,
+    diagnosis: 'Conflicting peer dependencies between packages',
+    remediation: 'Resolve conflicts or use legacy peer deps flag',
+    commands: [
+      { cmd: 'npm install --legacy-peer-deps', desc: 'Install with legacy peer deps', safe: true },
+      { cmd: 'npm ls --depth=0', desc: 'Check installed versions', safe: true },
+    ],
+    links: ['https://docs.npmjs.com/cli/commands/npm-install#legacy-peer-deps'],
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // FILE SYSTEM ERRORS
+  // ═══════════════════════════════════════════════════════════════════════════
+  {
+    id: 'enoent-file',
+    name: 'File Not Found',
+    patterns: [
+      /ENOENT.*no such file or directory/i,
+      /Error: Cannot find module/i,
+      /MODULE_NOT_FOUND/i,
+    ],
+    platforms: ['all'],
+    category: CATEGORY.PROJECT,
+    severity: SEVERITY.ERROR,
+    diagnosis: 'Required file or module is missing',
+    remediation: 'Reinstall dependencies or check file paths',
+    commands: [
+      { cmd: 'npm install', desc: 'Reinstall dependencies', safe: true },
+      { cmd: 'npm rebuild', desc: 'Rebuild native modules', safe: true },
+    ],
+    links: [],
+  },
+  {
+    id: 'enospc-disk',
+    name: 'Disk Space Exhausted',
+    patterns: [
+      /ENOSPC.*no space left on device/i,
+      /npm ERR! code ENOSPC/i,
+      /Error.*ENOSPC/i,
+    ],
+    platforms: ['all'],
+    category: CATEGORY.SYSTEM,
+    severity: SEVERITY.CRITICAL,
+    diagnosis: 'Disk is full or has no space for npm operations',
+    remediation: 'Free up disk space',
+    commands: [
+      { cmd: 'npm cache clean --force', desc: 'Clear npm cache', safe: true },
+      { cmd: 'rm -rf node_modules/.cache', desc: 'Clear node_modules cache', safe: true },
+      { cmd: 'docker system prune -a', desc: 'Clean Docker (if using)', safe: false },
+    ],
+    links: [],
+  },
+  {
+    id: 'enospc-inotify',
+    name: 'inotify Limit Exceeded',
+    patterns: [
+      /ENOSPC.*inotify/i,
+      /System limit for number of file watchers reached/i,
+      /Error.*ENOSPC.*watch/i,
+    ],
+    platforms: ['linux'],
+    category: CATEGORY.SYSTEM,
+    severity: SEVERITY.ERROR,
+    diagnosis: 'Linux inotify file watcher limit reached',
+    remediation: 'Increase inotify watcher limit',
+    commands: [
+      { cmd: 'echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf', desc: 'Increase limit permanently', safe: false },
+      { cmd: 'sudo sysctl -p', desc: 'Apply sysctl changes', safe: false },
+    ],
+    links: ['https://github.com/webpack/webpack/issues/2378'],
+  },
+  {
+    id: 'emfile-handles',
+    name: 'Too Many Open Files',
+    patterns: [
+      /EMFILE.*too many open files/i,
+      /Error.*EMFILE/i,
+    ],
+    platforms: ['darwin', 'linux'],
+    category: CATEGORY.SYSTEM,
+    severity: SEVERITY.ERROR,
+    diagnosis: 'Process has exceeded open file handle limit',
+    remediation: 'Increase ulimit for open files',
+    commands: [
+      { cmd: 'ulimit -n 10240', desc: 'Increase file limit for session', safe: true },
+      { cmd: 'echo "ulimit -n 10240" >> ~/.bashrc', desc: 'Make permanent', safe: true },
+    ],
+    links: [],
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // WINDOWS-SPECIFIC ERRORS
+  // ═══════════════════════════════════════════════════════════════════════════
+  {
+    id: 'win-long-path',
+    name: 'Windows Path Too Long',
+    patterns: [
+      /ENAMETOOLONG/i,
+      /path too long/i,
+      /filename.*260.*characters/i,
+      /Error.*path length/i,
+    ],
+    platforms: ['win32'],
+    category: CATEGORY.SYSTEM,
+    severity: SEVERITY.ERROR,
+    diagnosis: 'Windows path exceeds 260 character limit',
+    remediation: 'Enable long paths in Windows registry',
+    commands: [
+      { cmd: 'reg add "HKLM\\SYSTEM\\CurrentControlSet\\Control\\FileSystem" /v LongPathsEnabled /t REG_DWORD /d 1 /f', desc: 'Enable long paths (admin)', safe: false },
+    ],
+    links: ['https://docs.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation'],
+  },
+  {
+    id: 'win-powershell-policy',
+    name: 'PowerShell Execution Policy',
+    patterns: [
+      /cannot be loaded because running scripts is disabled/i,
+      /AuthorizationManager.*ExecutionPolicy/i,
+      /is not digitally signed/i,
+    ],
+    platforms: ['win32'],
+    category: CATEGORY.SYSTEM,
+    severity: SEVERITY.ERROR,
+    diagnosis: 'PowerShell execution policy blocks scripts',
+    remediation: 'Change PowerShell execution policy',
+    commands: [
+      { cmd: 'Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser', desc: 'Allow signed scripts', safe: true },
+    ],
+    links: ['https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy'],
+  },
+  {
+    id: 'win-eperm',
+    name: 'Windows Permission Error',
+    patterns: [
+      /EPERM.*operation not permitted/i,
+      /npm ERR! code EPERM/i,
+      /Error: EPERM/i,
+    ],
+    platforms: ['win32'],
+    category: CATEGORY.SYSTEM,
+    severity: SEVERITY.ERROR,
+    diagnosis: 'Windows file permission or locking issue',
+    remediation: 'Close applications using the files and retry',
+    commands: [
+      { cmd: 'taskkill /F /IM node.exe', desc: 'Kill all Node processes', safe: false },
+      { cmd: 'npm cache clean --force', desc: 'Clear npm cache', safe: true },
+    ],
+    links: [],
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // BUILD / COMPILE ERRORS
+  // ═══════════════════════════════════════════════════════════════════════════
+  {
+    id: 'native-module-build',
+    name: 'Native Module Build Failed',
+    patterns: [
+      /gyp ERR!/i,
+      /node-pre-gyp/i,
+      /prebuild-install/i,
+      /Cannot find module.*node_modules.*\.node/i,
+      /node-gyp rebuild/i,
+    ],
+    platforms: ['all'],
+    category: CATEGORY.DEPENDENCIES,
+    severity: SEVERITY.ERROR,
+    diagnosis: 'Native module compilation failed',
+    remediation: 'Install build tools and Python',
+    commands: [
+      { cmd: 'npm install -g node-gyp', desc: 'Install node-gyp globally', safe: true },
+      { cmd: 'npm rebuild', desc: 'Rebuild native modules', safe: true },
+    ],
+    links: ['https://github.com/nodejs/node-gyp#installation'],
+  },
+  {
+    id: 'typescript-error',
+    name: 'TypeScript Compilation Error',
+    patterns: [
+      /TS\d{4,5}:/,
+      /error TS\d+/i,
+      /Cannot find type definition/i,
+      /Could not find a declaration file/i,
+    ],
+    platforms: ['all'],
+    category: CATEGORY.PROJECT,
+    severity: SEVERITY.ERROR,
+    diagnosis: 'TypeScript compilation errors',
+    remediation: 'Fix TypeScript errors or check tsconfig.json',
+    commands: [
+      { cmd: 'npx tsc --noEmit', desc: 'Check TypeScript errors', safe: true },
+      { cmd: 'npm install @types/node', desc: 'Install Node types', safe: true },
+    ],
+    links: ['https://www.typescriptlang.org/docs/handbook/tsconfig-json.html'],
+  },
+  {
+    id: 'eslint-error',
+    name: 'ESLint Configuration Error',
+    patterns: [
+      /ESLint couldn't find the config/i,
+      /eslint.*configuration.*invalid/i,
+      /Error: No ESLint configuration/i,
+    ],
+    platforms: ['all'],
+    category: CATEGORY.PROJECT,
+    severity: SEVERITY.WARNING,
+    diagnosis: 'ESLint configuration is missing or invalid',
+    remediation: 'Initialize or fix ESLint configuration',
+    commands: [
+      { cmd: 'npx eslint --init', desc: 'Initialize ESLint', safe: true },
+    ],
+    links: ['https://eslint.org/docs/user-guide/configuring'],
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // GIT ERRORS
+  // ═══════════════════════════════════════════════════════════════════════════
+  {
+    id: 'git-not-installed',
+    name: 'Git Not Installed',
+    patterns: [
+      /git.*not recognized/i,
+      /git.*command not found/i,
+      /'git' is not recognized/i,
+    ],
+    platforms: ['all'],
+    category: CATEGORY.SYSTEM,
+    severity: SEVERITY.ERROR,
+    diagnosis: 'Git is not installed or not in PATH',
+    remediation: 'Install Git',
+    commands: [],
+    links: ['https://git-scm.com/downloads'],
+  },
+  {
+    id: 'git-lock-file',
+    name: 'Git Lock File Exists',
+    patterns: [
+      /\.git\/index\.lock.*exists/i,
+      /Unable to create.*\.lock.*File exists/i,
+      /fatal: Unable to create.*lock file/i,
+    ],
+    platforms: ['all'],
+    category: CATEGORY.PROJECT,
+    severity: SEVERITY.ERROR,
+    diagnosis: 'Git lock file exists from a crashed operation',
+    remediation: 'Remove the lock file',
+    commands: [
+      { cmd: 'rm -f .git/index.lock', desc: 'Remove git index lock', safe: true },
+      { cmd: 'rm -f .git/*.lock', desc: 'Remove all git locks', safe: true },
+    ],
+    links: [],
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // MEMORY / PERFORMANCE
+  // ═══════════════════════════════════════════════════════════════════════════
+  {
+    id: 'heap-out-of-memory',
+    name: 'JavaScript Heap Out of Memory',
+    patterns: [
+      /FATAL ERROR.*heap/i,
+      /JavaScript heap out of memory/i,
+      /Allocation failed.*JavaScript heap/i,
+    ],
+    platforms: ['all'],
+    category: CATEGORY.SYSTEM,
+    severity: SEVERITY.ERROR,
+    diagnosis: 'Node.js ran out of memory',
+    remediation: 'Increase Node.js memory limit',
+    commands: [
+      { cmd: 'export NODE_OPTIONS="--max-old-space-size=4096"', desc: 'Increase to 4GB', safe: true },
+      { cmd: 'node --max-old-space-size=8192', desc: 'Run with 8GB', safe: true },
+    ],
+    links: ['https://nodejs.org/api/cli.html#--max-old-space-sizesize-in-megabytes'],
+  },
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // DOCKER ERRORS
+  // ═══════════════════════════════════════════════════════════════════════════
+  {
+    id: 'docker-not-running',
+    name: 'Docker Not Running',
+    patterns: [
+      /Cannot connect to the Docker daemon/i,
+      /docker daemon is not running/i,
+      /Is the docker daemon running/i,
+    ],
+    platforms: ['all'],
+    category: CATEGORY.SYSTEM,
+    severity: SEVERITY.ERROR,
+    diagnosis: 'Docker daemon is not running',
+    remediation: 'Start Docker Desktop or docker service',
+    commands: [
+      { cmd: 'open -a Docker', desc: 'Start Docker Desktop (macOS)', safe: true },
+      { cmd: 'sudo systemctl start docker', desc: 'Start Docker (Linux)', safe: false },
+    ],
+    links: ['https://docs.docker.com/get-docker/'],
+  },
+];
+
+/**
+ * Match error output against known failure signatures
+ * @param {string} errorOutput - Error text to analyze
+ * @param {string} platform - Current platform (win32, darwin, linux)
+ * @returns {object[]} Matching failure signatures
+ */
+function matchFailureSignatures(errorOutput, platform = process.platform) {
+  if (!errorOutput) return [];
+  
+  const matches = [];
+  
+  for (const sig of FAILURE_SIGNATURES) {
+    // Check platform
+    if (!sig.platforms.includes('all') && !sig.platforms.includes(platform)) {
+      continue;
+    }
+    
+    // Check patterns
+    for (const pattern of sig.patterns) {
+      const regex = pattern instanceof RegExp ? pattern : new RegExp(pattern, 'i');
+      if (regex.test(errorOutput)) {
+        matches.push({
+          ...sig,
+          matchedPattern: pattern.toString(),
+        });
+        break; // Only match once per signature
+      }
+    }
+  }
+  
+  return matches;
+}
+
+/**
+ * Get all failure signatures for a specific category
+ * @param {string} category - Category to filter by
+ * @returns {object[]} Matching signatures
+ */
+function getSignaturesByCategory(category) {
+  return FAILURE_SIGNATURES.filter(sig => sig.category === category);
+}
+
+/**
+ * Get all safe fix commands from matched signatures
+ * @param {object[]} matches - Matched signatures
+ * @returns {object[]} Safe commands
+ */
+function getSafeCommands(matches) {
+  const commands = [];
+  
+  for (const match of matches) {
+    for (const cmd of match.commands || []) {
+      if (cmd.safe) {
+        commands.push({
+          signatureId: match.id,
+          signatureName: match.name,
+          ...cmd,
+        });
+      }
+    }
+  }
+  
+  return commands;
+}
+
+/**
+ * Format diagnosis for a matched signature
+ * @param {object} match - Matched signature
+ * @returns {string} Formatted diagnosis
+ */
+function formatDiagnosis(match) {
+  const lines = [];
+  lines.push(`  [${match.id}] ${match.name}`);
+  lines.push(`  Diagnosis: ${match.diagnosis}`);
+  lines.push(`  Fix: ${match.remediation}`);
+  
+  if (match.commands?.length > 0) {
+    lines.push('  Commands:');
+    for (const cmd of match.commands) {
+      const safeTag = cmd.safe ? '' : ' [DANGEROUS]';
+      lines.push(`    $ ${cmd.cmd}${safeTag}`);
+      lines.push(`      ${cmd.desc}`);
+    }
+  }
+  
+  if (match.links?.length > 0) {
+    lines.push('  Links:');
+    for (const link of match.links) {
+      lines.push(`    ${link}`);
+    }
+  }
+  
+  return lines.join('\n');
+}
+
+module.exports = {
+  FAILURE_SIGNATURES,
+  matchFailureSignatures,
+  getSignaturesByCategory,
+  getSafeCommands,
+  formatDiagnosis,
+};