thuban 0.3.0

package/packages/scanner/hallucination-detector.js

@@ -0,0 +1,507 @@
+/**
+ * @thuban-dna
+ * @purpose Detect AI hallucinations, phantom imports, invented APIs, and code drift
+ * @module thuban
+ * @layer application
+ * @imports-from fs, path
+ * @exports-to cli, tech-debt-analyzer, code-scanner
+ * @side-effects File system reads, Console output
+ * @critical-for Core differentiator — no other tool detects AI-generated code issues
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+class HallucinationDetector {
+  constructor(config = {}) {
+    this.config = {
+      rootPath: config.rootPath || process.cwd(),
+      ...config
+    };
+
+    // Known Node.js built-in modules
+    this.builtins = new Set([
+      'assert', 'async_hooks', 'buffer', 'child_process', 'cluster',
+      'console', 'constants', 'crypto', 'dgram', 'diagnostics_channel',
+      'dns', 'domain', 'events', 'fs', 'http', 'http2', 'https',
+      'inspector', 'module', 'net', 'os', 'path', 'perf_hooks',
+      'process', 'punycode', 'querystring', 'readline', 'repl',
+      'stream', 'string_decoder', 'sys', 'timers', 'tls', 'trace_events',
+      'tty', 'url', 'util', 'v8', 'vm', 'wasi', 'worker_threads', 'zlib',
+      'node:fs', 'node:path', 'node:os', 'node:crypto', 'node:http',
+      'node:https', 'node:events', 'node:util', 'node:stream',
+      'node:child_process', 'node:url', 'node:querystring', 'node:buffer',
+      'node:net', 'node:tls', 'node:dns', 'node:readline', 'node:zlib',
+      'node:worker_threads', 'node:cluster', 'node:vm', 'node:assert',
+      'node:timers', 'node:timers/promises', 'node:test',
+      'fs/promises', 'stream/promises', 'timers/promises', 'dns/promises',
+      'readline/promises',
+    ]);
+
+    // Common phantom packages that LLMs hallucinate
+    this.phantomPackages = new Set([
+      'node-fetch-extra', 'express-async', 'mongoose-v2',
+      'react-native-web-view', 'axios-retry-enhanced',
+      'lodash-extended', 'moment-timezone-v2', 'socket.io-extra',
+      'graphql-tools-v2', 'next-auth-v5', 'prisma-client-v2',
+      'tailwind-utils', 'react-query-v4', 'jest-extended-v2',
+    ]);
+
+    // Common hallucinated API patterns (methods that don't exist)
+    this.phantomAPIs = [
+      { pattern: /fs\.readFileAsync\s*\(/, suggestion: 'Use fs.promises.readFile() or fs.readFileSync()', name: 'fs.readFileAsync', id: 'HALL_API001' },
+      { pattern: /fs\.writeFileAsync\s*\(/, suggestion: 'Use fs.promises.writeFile() or fs.writeFileSync()', name: 'fs.writeFileAsync', id: 'HALL_API002' },
+      { pattern: /fs\.existsAsync\s*\(/, suggestion: 'Use fs.promises.access() or fs.existsSync()', name: 'fs.existsAsync', id: 'HALL_API003' },
+      { pattern: /path\.exists\s*\(/, suggestion: 'Use fs.existsSync() — path module has no exists()', name: 'path.exists', id: 'HALL_API004' },
+      { pattern: /path\.isFile\s*\(/, suggestion: 'Use fs.statSync().isFile() — path module has no isFile()', name: 'path.isFile', id: 'HALL_API005' },
+      { pattern: /path\.isDirectory\s*\(/, suggestion: 'Use fs.statSync().isDirectory()', name: 'path.isDirectory', id: 'HALL_API006' },
+      { pattern: /console\.success\s*\(/, suggestion: 'Use console.log() — console.success() does not exist', name: 'console.success', id: 'HALL_API007' },
+      { pattern: /console\.verbose\s*\(/, suggestion: 'Use console.log() or console.debug()', name: 'console.verbose', id: 'HALL_API008' },
+      { pattern: /JSON\.tryParse\s*\(/, suggestion: 'Use try/catch with JSON.parse()', name: 'JSON.tryParse', id: 'HALL_API009' },
+      { pattern: /JSON\.safeStringify\s*\(/, suggestion: 'Use JSON.stringify() with a replacer', name: 'JSON.safeStringify', id: 'HALL_API010' },
+      { pattern: /Array\.flatten\s*\(/, suggestion: 'Use Array.prototype.flat()', name: 'Array.flatten', id: 'HALL_API011' },
+      { pattern: /Object\.deepClone\s*\(/, suggestion: 'Use structuredClone() or JSON.parse(JSON.stringify())', name: 'Object.deepClone', id: 'HALL_API012' },
+      { pattern: /Object\.deepMerge\s*\(/, suggestion: 'Use a library like lodash.merge or write a custom function', name: 'Object.deepMerge', id: 'HALL_API013' },
+      { pattern: /String\.prototype\.replaceAll\s*&&.*polyfill/i, suggestion: 'replaceAll() is native since ES2021 — no polyfill needed', name: 'replaceAll polyfill', id: 'HALL_API014' },
+      { pattern: /require\s*\(\s*['"]fs\/sync['"]\s*\)/, suggestion: 'fs/sync is not a real module — use fs directly', name: 'fs/sync', id: 'HALL_API015' },
+      { pattern: /require\s*\(\s*['"]http\/server['"]\s*\)/, suggestion: 'http/server is not a real module — use http.createServer()', name: 'http/server', id: 'HALL_API016' },
+      { pattern: /process\.env\.get\s*\(/, suggestion: 'Use process.env.VAR_NAME — process.env is a plain object, not a Map', name: 'process.env.get()', id: 'HALL_API017' },
+      { pattern: /process\.exit\s*\(\s*['"]/, suggestion: 'process.exit() takes a number, not a string', name: 'process.exit(string)', id: 'HALL_API018' },
+    ];
+
+    // Patterns suggesting AI-generated code with common issues
+    this.aiCodeSmells = [
+      { pattern: /\/\/\s*TODO:?\s*(implement|add|fix|complete|finish)\s*(this|here|later)/i, id: 'AI_SMELL001', name: 'Placeholder TODO', message: 'AI-generated placeholder — likely unfinished implementation' },
+      { pattern: /throw new Error\(['"]Not implemented['"]\)/, id: 'AI_SMELL002', name: 'Not Implemented', message: 'Stub implementation — function body was not generated' },
+      { pattern: /\/\/\s*\.\.\.\s*(rest|remaining|more|other|additional)/i, id: 'AI_SMELL003', name: 'Truncated Code', message: 'AI output was truncated — code is incomplete' },
+      { pattern: /\/\/\s*(your|replace|insert|put)\s+(code|logic|implementation|api[_\s]?key)/i, id: 'AI_SMELL004', name: 'Template Placeholder', message: 'Template placeholder left in code — needs real implementation' },
+      { pattern: /['"]your-api-key-here['"]|['"]sk-[.]{3,}['"]|['"]xxx+['"]/i, id: 'AI_SMELL005', name: 'Dummy Credential', message: 'Placeholder credential — will fail at runtime' },
+      { pattern: /example\.com|test@test\.com|john@doe\.com|foo@bar\.com/i, id: 'AI_SMELL006', name: 'Example Domain', message: 'Example domain/email in production code' },
+      { pattern: /localhost:\d{4}(?!.*(?:dev|test|local|development))/i, id: 'AI_SMELL007', name: 'Hardcoded Localhost', message: 'Hardcoded localhost URL — will fail in production' },
+    ];
+
+    // Deprecated/removed Node.js APIs that LLMs still suggest
+    this.deprecatedAPIs = [
+      { pattern: /new Buffer\s*\(/, suggestion: 'Use Buffer.from(), Buffer.alloc(), or Buffer.allocUnsafe()', since: 'Node 6', name: 'new Buffer()', id: 'DEPR_API001' },
+      { pattern: /require\s*\(\s*['"]sys['"]\s*\)/, suggestion: 'Use require("util") — sys was removed in Node 1.0', since: 'Node 1.0', name: 'require("sys")', id: 'DEPR_API002' },
+      { pattern: /fs\.exists\s*\((?!Sync)/, suggestion: 'Use fs.access() or fs.stat() — fs.exists() is deprecated', since: 'Node 1.0', name: 'fs.exists()', id: 'DEPR_API003' },
+      { pattern: /domain\.create\s*\(/, suggestion: 'Use async_hooks or try/catch — domain module is deprecated', since: 'Node 4', name: 'domain.create()', id: 'DEPR_API004' },
+      { pattern: /require\s*\(\s*['"]punycode['"]\s*\)/, suggestion: 'Use userland punycode package — built-in is deprecated', since: 'Node 7', name: 'require("punycode")', id: 'DEPR_API005' },
+      { pattern: /url\.parse\s*\(/, suggestion: 'Use new URL() — url.parse() is legacy', since: 'Node 11', name: 'url.parse()', id: 'DEPR_API006' },
+      { pattern: /querystring\.(parse|stringify)\s*\(/, suggestion: 'Use URLSearchParams — querystring is legacy', since: 'Node 14', name: 'querystring', id: 'DEPR_API007' },
+      { pattern: /util\.isArray\s*\(/, suggestion: 'Use Array.isArray() — util type checks are deprecated', since: 'Node 4', name: 'util.isArray()', id: 'DEPR_API008' },
+      { pattern: /util\.isFunction\s*\(/, suggestion: 'Use typeof fn === "function"', since: 'Node 4', name: 'util.isFunction()', id: 'DEPR_API009' },
+      { pattern: /util\.pump\s*\(/, suggestion: 'Use stream.pipeline() — util.pump() was removed', since: 'Node 1.0', name: 'util.pump()', id: 'DEPR_API010' },
+    ];
+  }
+
+  /**
+   * Full hallucination scan across all files
+   */
+  async scan(files) {
+    const startTime = Date.now();
+    const results = {
+      phantomImports: [],
+      phantomAPIs: [],
+      aiSmells: [],
+      deprecatedAPIs: [],
+      unresolvedDeps: [],
+      stats: {
+        filesScanned: 0,
+        totalIssues: 0,
+        scanTime: 0,
+      },
+    };
+
+    // Load package.json dependencies
+    const declaredDeps = this._loadDeclaredDeps();
+
+    // Load .thubanrc.json ignore rules
+    const ignoreFiles = this._loadIgnoreRules();
+
+    for (const file of files) {
+      try {
+        const ext = path.extname(file).toLowerCase();
+        if (!['.js', '.ts', '.jsx', '.tsx', '.mjs', '.cjs'].includes(ext)) continue;
+
+        const relPath = path.relative(this.config.rootPath, file);
+
+        // Skip files in the ignore list
+        if (ignoreFiles.some(pattern => relPath.includes(pattern) || file.includes(pattern))) continue;
+
+        const content = fs.readFileSync(file, 'utf-8');
+        const lines = content.split('\n');
+
+        // Build set of lines with thuban-ignore comments
+        const ignoredLines = new Set();
+        for (let i = 0; i < lines.length; i++) {
+          if (lines[i].includes('thuban-ignore')) {
+            ignoredLines.add(i + 1); // 1-based
+            ignoredLines.add(i + 2); // Also ignore next line
+          }
+        }
+
+        // Skip files that are pattern definition files (contain regex pattern arrays)
+        // These files define what to look for, not actual violations
+        const isPatternFile = this._isPatternDefinitionFile(content);
+
+        results.stats.filesScanned++;
+
+        // 1. Phantom imports — packages that don't exist
+        this._checkPhantomImports(relPath, content, lines, declaredDeps, results, ignoredLines);
+
+        // 2. Phantom APIs — methods that don't exist on known objects
+        if (!isPatternFile) {
+          this._checkPhantomAPIs(relPath, content, lines, results, ignoredLines);
+        }
+
+        // 3. AI code smells — patterns typical of AI-generated code
+        this._checkAISmells(relPath, content, lines, results, ignoredLines);
+
+        // 4. Deprecated APIs — APIs that LLMs still suggest
+        if (!isPatternFile) {
+          this._checkDeprecatedAPIs(relPath, content, lines, results, ignoredLines);
+        }
+
+      } catch (e) { /* skip unreadable */ }
+    }
+
+    results.stats.totalIssues =
+      results.phantomImports.length +
+      results.phantomAPIs.length +
+      results.aiSmells.length +
+      results.deprecatedAPIs.length +
+      results.unresolvedDeps.length;
+
+    results.stats.scanTime = Date.now() - startTime;
+
+    return results;
+  }
+
+  /**
+   * Format results for terminal output
+   */
+  formatReport(results) {
+    const C = {
+      reset: '\x1b[0m', bold: '\x1b[1m',
+      red: '\x1b[31m', green: '\x1b[32m', yellow: '\x1b[33m',
+      cyan: '\x1b[36m', gray: '\x1b[90m', magenta: '\x1b[35m',
+    };
+
+    let output = '';
+    output += `\n${C.magenta}  ╔══════════════════════════════════════════════╗${C.reset}\n`;
+    output += `${C.magenta}  ║${C.bold}       THUBAN HALLUCINATION REPORT             ${C.reset}${C.magenta}║${C.reset}\n`;
+    output += `${C.magenta}  ╚══════════════════════════════════════════════╝${C.reset}\n\n`;
+
+    if (results.stats.totalIssues === 0) {
+      output += `  ${C.green}${C.bold}No hallucinations detected.${C.reset} ${C.gray}Clean codebase.${C.reset}\n\n`;
+      return output;
+    }
+
+    // Phantom imports
+    if (results.phantomImports.length > 0) {
+      output += `  ${C.red}${C.bold}Phantom Imports (${results.phantomImports.length})${C.reset}\n`;
+      output += `  ${C.gray}Packages that don't exist in package.json or node_modules${C.reset}\n\n`;
+      for (const item of results.phantomImports.slice(0, 10)) {
+        output += `    ${C.red}✗${C.reset} ${C.cyan}${item.file}${C.reset}:${item.line}\n`;
+        output += `      ${C.yellow}${item.module}${C.reset} ${C.gray}— ${item.reason}${C.reset}\n`;
+      }
+      if (results.phantomImports.length > 10) {
+        output += `    ${C.gray}... and ${results.phantomImports.length - 10} more${C.reset}\n`;
+      }
+      output += '\n';
+    }
+
+    // Phantom APIs
+    if (results.phantomAPIs.length > 0) {
+      output += `  ${C.red}${C.bold}Phantom APIs (${results.phantomAPIs.length})${C.reset}\n`;
+      output += `  ${C.gray}Methods/properties that don't exist on their objects${C.reset}\n\n`;
+      for (const item of results.phantomAPIs.slice(0, 10)) {
+        const ruleId = item.id ? `${C.gray}[${item.id}]${C.reset} ` : '';
+        output += `    ${C.red}✗${C.reset} ${ruleId}${C.cyan}${item.file}${C.reset}:${item.line}\n`;
+        output += `      ${C.yellow}${item.name}${C.reset} ${C.gray}— ${item.suggestion}${C.reset}\n`;
+        output += `      ${C.gray}Suppress: // thuban-ignore ${item.id || 'HALL_API'}${C.reset}\n`;
+      }
+      if (results.phantomAPIs.length > 10) {
+        output += `    ${C.gray}... and ${results.phantomAPIs.length - 10} more${C.reset}\n`;
+      }
+      output += '\n';
+    }
+
+    // AI code smells
+    if (results.aiSmells.length > 0) {
+      output += `  ${C.yellow}${C.bold}AI Code Smells (${results.aiSmells.length})${C.reset}\n`;
+      output += `  ${C.gray}Patterns typical of AI-generated code that needs review${C.reset}\n\n`;
+      for (const item of results.aiSmells.slice(0, 10)) {
+        output += `    ${C.yellow}!${C.reset} ${C.cyan}${item.file}${C.reset}:${item.line}\n`;
+        output += `      ${C.gray}${item.message}${C.reset}\n`;
+      }
+      if (results.aiSmells.length > 10) {
+        output += `    ${C.gray}... and ${results.aiSmells.length - 10} more${C.reset}\n`;
+      }
+      output += '\n';
+    }
+
+    // Deprecated APIs
+    if (results.deprecatedAPIs.length > 0) {
+      output += `  ${C.yellow}${C.bold}Deprecated APIs (${results.deprecatedAPIs.length})${C.reset}\n`;
+      output += `  ${C.gray}APIs that LLMs still suggest but are deprecated or removed${C.reset}\n\n`;
+      for (const item of results.deprecatedAPIs.slice(0, 10)) {
+        output += `    ${C.yellow}⚠${C.reset} ${C.cyan}${item.file}${C.reset}:${item.line}\n`;
+        output += `      ${C.yellow}${item.name}${C.reset} ${C.gray}(deprecated since ${item.since})${C.reset}\n`;
+        output += `      ${C.green}→${C.reset} ${C.gray}${item.suggestion}${C.reset}\n`;
+      }
+      if (results.deprecatedAPIs.length > 10) {
+        output += `    ${C.gray}... and ${results.deprecatedAPIs.length - 10} more${C.reset}\n`;
+      }
+      output += '\n';
+    }
+
+    // Summary
+    output += `  ${C.bold}Summary:${C.reset} ${C.cyan}${results.stats.filesScanned}${C.reset} files scanned, `;
+    output += `${results.stats.totalIssues > 0 ? C.red : C.green}${results.stats.totalIssues}${C.reset} hallucination issues found `;
+    output += `${C.gray}(${results.stats.scanTime}ms)${C.reset}\n\n`;
+
+    return output;
+  }
+
+  // ─── Private Methods ─────────────────────────────────────
+
+  _loadDeclaredDeps() {
+    const deps = new Set();
+    // Collect all package.json files — root + subdirectories (monorepo support)
+    this._packageJsonPaths = new Map(); // dir -> Set<dep names>
+    this._collectPackageJsonDeps(this.config.rootPath, deps, 0);
+    return deps;
+  }
+
+  /**
+   * Recursively collect deps from all package.json files in the project.
+   * Handles monorepos: workspaces, packages/*, apps/*, etc.
+   * Max depth prevents scanning into node_modules.
+   */
+  _collectPackageJsonDeps(dir, globalDeps, depth) {
+    if (depth > 5) return; // Don't go too deep
+    try {
+      const pkgPath = path.join(dir, 'package.json');
+      if (fs.existsSync(pkgPath)) {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        const localDeps = new Set();
+        for (const name of Object.keys(pkg.dependencies || {})) { globalDeps.add(name); localDeps.add(name); }
+        for (const name of Object.keys(pkg.devDependencies || {})) { globalDeps.add(name); localDeps.add(name); }
+        for (const name of Object.keys(pkg.peerDependencies || {})) { globalDeps.add(name); localDeps.add(name); }
+        this._packageJsonPaths.set(dir, localDeps);
+      }
+
+      // Scan subdirectories for more package.json files
+      // Skip node_modules, .git, dist, build, coverage
+      const skipDirs = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.next', '.cache', 'vendor']);
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory() && !skipDirs.has(entry.name) && !entry.name.startsWith('.')) {
+          this._collectPackageJsonDeps(path.join(dir, entry.name), globalDeps, depth + 1);
+        }
+      }
+    } catch (e) { /* skip unreadable dirs */ }
+  }
+
+  _checkPhantomImports(relPath, content, lines, declaredDeps, results, ignoredLines = new Set()) {
+    // Match require() and import statements
+    const requireRegex = /require\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+    const importRegex = /import\s+.*?from\s+['"]([^'"]+)['"]/g;
+    const dynamicImportRegex = /import\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+    const allImportRegexes = [requireRegex, importRegex, dynamicImportRegex];
+
+    for (const regex of allImportRegexes) {
+      let match;
+      while ((match = regex.exec(content)) !== null) {
+        const moduleName = match[1];
+
+        // Skip relative imports
+        if (moduleName.startsWith('.') || moduleName.startsWith('/')) continue;
+
+        // Skip builtins
+        const baseModule = moduleName.split('/')[0];
+        if (this.builtins.has(moduleName) || this.builtins.has(baseModule)) continue;
+
+        // Skip scoped packages base
+        const scopedBase = moduleName.startsWith('@')
+          ? moduleName.split('/').slice(0, 2).join('/')
+          : baseModule;
+
+        // Check if declared in any package.json (root or workspace)
+        if (!declaredDeps.has(scopedBase)) {
+          // Check if it physically exists in any node_modules (root or nearest parent)
+          const nmExists = this._findInNodeModules(file, scopedBase);
+          if (!nmExists) {
+            // Find line number
+            const lineIdx = this._findLineNumber(content, match.index);
+
+            // Skip if on an ignored line
+            if (ignoredLines.has(lineIdx)) continue;
+
+            // Check if it's a known phantom
+            const isKnownPhantom = this.phantomPackages.has(moduleName);
+
+            results.phantomImports.push({
+              file: relPath,
+              line: lineIdx,
+              module: moduleName,
+              reason: isKnownPhantom
+                ? 'Known AI-hallucinated package — does not exist on npm'
+                : 'Not in package.json and not in node_modules',
+              severity: isKnownPhantom ? 'critical' : 'high',
+              fixable: false,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  _checkPhantomAPIs(relPath, content, lines, results, ignoredLines = new Set()) {
+    for (const api of this.phantomAPIs) {
+      let match;
+      const regex = new RegExp(api.pattern.source, api.pattern.flags + (api.pattern.flags.includes('g') ? '' : 'g'));
+      while ((match = regex.exec(content)) !== null) {
+        const lineIdx = this._findLineNumber(content, match.index);
+        if (ignoredLines.has(lineIdx)) continue;
+        // Skip if inside a string literal or regex pattern (common in pattern definition files)
+        const line = lines[lineIdx - 1] || '';
+        if (this._isInsidePattern(line, match[0])) continue;
+        results.phantomAPIs.push({
+          file: relPath,
+          line: lineIdx,
+          name: api.name,
+          id: api.id,
+          suggestion: api.suggestion,
+          severity: 'high',
+          fixable: true,
+          fixAction: 'replace_phantom_api',
+        });
+      }
+    }
+  }
+
+  _checkAISmells(relPath, content, lines, results, ignoredLines = new Set()) {
+    for (const smell of this.aiCodeSmells) {
+      let match;
+      const regex = new RegExp(smell.pattern.source, smell.pattern.flags + (smell.pattern.flags.includes('g') ? '' : 'g'));
+      while ((match = regex.exec(content)) !== null) {
+        const lineIdx = this._findLineNumber(content, match.index);
+        if (ignoredLines.has(lineIdx)) continue;
+        results.aiSmells.push({
+          file: relPath,
+          line: lineIdx,
+          id: smell.id,
+          name: smell.name,
+          message: smell.message,
+          severity: 'warning',
+          code: lines[lineIdx - 1]?.trim().substring(0, 100),
+        });
+      }
+    }
+  }
+
+  _checkDeprecatedAPIs(relPath, content, lines, results, ignoredLines = new Set()) {
+    for (const api of this.deprecatedAPIs) {
+      let match;
+      const regex = new RegExp(api.pattern.source, api.pattern.flags + (api.pattern.flags.includes('g') ? '' : 'g'));
+      while ((match = regex.exec(content)) !== null) {
+        const lineIdx = this._findLineNumber(content, match.index);
+        if (ignoredLines.has(lineIdx)) continue;
+        const line = lines[lineIdx - 1] || '';
+        if (this._isInsidePattern(line, match[0])) continue;
+        results.deprecatedAPIs.push({
+          file: relPath,
+          line: lineIdx,
+          name: api.name,
+          id: api.id,
+          suggestion: api.suggestion,
+          since: api.since,
+          severity: 'warning',
+          fixable: true,
+          fixAction: 'update_deprecated_api',
+        });
+      }
+    }
+  }
+
+  _findLineNumber(content, charIndex) {
+    let line = 1;
+    for (let i = 0; i < charIndex && i < content.length; i++) {
+      if (content[i] === '\n') line++;
+    }
+    return line;
+  }
+
+  /**
+   * Detect if a file is a pattern definition file (like this detector itself)
+   * These files contain regex patterns that reference the APIs they detect
+   */
+  _isPatternDefinitionFile(content) {
+    // Count regex pattern definitions — if file has many, it's likely a detector/rule file
+    const regexPatterns = (content.match(/pattern:\s*\//g) || []).length;
+    const phantomRefs = (content.match(/phantom|hallucin/gi) || []).length;
+    return regexPatterns > 5 && phantomRefs > 2;
+  }
+
+  /**
+   * Check if a match is inside a regex pattern, string literal, or comment
+   */
+  _isInsidePattern(line, matchText) {
+    const trimmed = line.trim();
+    // Inside a regex pattern definition
+    if (/pattern:\s*\//.test(trimmed)) return true;
+    // Inside a comment
+    if (trimmed.startsWith('//') || trimmed.startsWith('*')) return true;
+    // Inside a string that's defining a name/suggestion/message
+    if (/(?:name|suggestion|message|description):\s*['"]/.test(trimmed)) return true;
+    return false;
+  }
+
+  /**
+   * Load ignore rules from .thubanrc.json
+   */
+  _loadIgnoreRules() {
+    const ignoreFiles = [];
+    try {
+      const rcPath = path.join(this.config.rootPath, '.thubanrc.json');
+      const rc = JSON.parse(fs.readFileSync(rcPath, 'utf-8'));
+      if (rc.hallucination?.ignore) {
+        ignoreFiles.push(...rc.hallucination.ignore);
+      }
+      if (rc.ignore) {
+        ignoreFiles.push(...rc.ignore);
+      }
+    } catch (e) { /* no config file */ }
+    return ignoreFiles;
+  }
+
+  /**
+   * Walk up directory tree from file location to project root,
+   * checking each node_modules directory for the package.
+   * This handles monorepos where deps are installed at workspace level.
+   */
+  _findInNodeModules(filePath, packageName) {
+    let dir = path.dirname(filePath);
+    const root = this.config.rootPath;
+
+    // Walk up from file to root, checking each node_modules
+    while (dir.length >= root.length) {
+      const nmPath = path.join(dir, 'node_modules', packageName);
+      try {
+        if (fs.existsSync(nmPath)) return true;
+      } catch (e) { /* skip */ }
+
+      const parent = path.dirname(dir);
+      if (parent === dir) break; // reached filesystem root
+      dir = parent;
+    }
+
+    return false;
+  }
+}
+
+module.exports = HallucinationDetector;