thuban 0.3.3 → 0.4.0

package/packages/scanner/tech-debt-analyzer.js

@@ -1,583 +0,0 @@
-/**
- * Thuban Tech Debt Analyzer & Auto-Fixer
- *
- * @purpose Score, visualise, and auto-fix technical debt
- * @module thuban
- * @layer application
- * @imports-from code-scanner, dependency-graph, drift-detector, widget-generator
- * @exports-to cli, dashboard, reports
- * @side-effects File system reads and writes when fixing
- * @critical-for Core Thuban value proposition — the "fix it" button
- */
-
-const fs = require('fs');
-const path = require('path');
-const CodeScanner = require('./code-scanner');
-const DependencyGraph = require('./dependency-graph');
-const DriftDetector = require('./drift-detector');
-const WidgetGenerator = require('./widget-generator');
-
-/**
- * Convert a JSDoc-style /** ... * / widget string to the appropriate comment
- * style for the target file's language.
- */
-function formatWidgetComment(jsDocWidget, filePath) {
-  const ext = path.extname(filePath).toLowerCase();
-  if (ext === '.py') {
-    return jsDocWidget
-      .replace(/^\/\*\*\n/, '')
-      .replace(/\s*\*\/\s*$/, '')
-      .split('\n')
-      .map(l => l.replace(/^\s*\*\s?/, '# '))
-      .join('\n');
-  } else if (ext === '.go') {
-    return jsDocWidget
-      .replace(/^\/\*\*\n/, '')
-      .replace(/\s*\*\/\s*$/, '')
-      .split('\n')
-      .map(l => l.replace(/^\s*\*\s?/, '// '))
-      .join('\n');
-  }
-  // JS, TS, Java, C# — keep /** */ format
-  return jsDocWidget;
-}
-
-class TechDebtAnalyzer {
-  constructor(config = {}) {
-    this.config = {
-      rootPath: config.rootPath || process.cwd(),
-      ...config
-    };
-
-    this.scanner = new CodeScanner(this.config);
-    this.depGraph = new DependencyGraph(this.config);
-    this.driftDetector = new DriftDetector(this.config);
-    this.widgetGen = new WidgetGenerator({ ...this.config, dryRun: true });
-  }
-
-  /**
-   * Full tech debt analysis — the complete health picture
-   * Returns a structured report with scores, categories, and fixable items
-   */
-  async analyze(files) {
-    const startTime = Date.now();
-
-    // Build dependency graph
-    await this.depGraph.build(files);
-    this.widgetGen.dependencyGraph = this.depGraph;
-
-    // Run all analyses
-    const scanResults = await this.scanner.scanFiles(files);
-    const driftResults = await this.driftDetector.detectAll();
-
-    // Categorise all issues into tech debt buckets
-    const debt = {
-      // Category scores (0-100, lower = more debt)
-      scores: {
-        overall: 100,
-        security: 100,
-        architecture: 100,
-        codeQuality: 100,
-        documentation: 100,
-        dependencies: 100,
-        motherCode: 100,
-      },
-
-      // Fixable items (can be auto-fixed)
-      fixable: [],
-      // Manual items (need human decision)
-      manual: [],
-      // Info items (awareness only)
-      info: [],
-
-      // Summary stats
-      stats: {
-        totalFiles: files.length,
-        totalIssues: 0,
-        fixableCount: 0,
-        manualCount: 0,
-        estimatedFixTime: '0 minutes',
-        scanTime: 0,
-      },
-
-      // Detailed categories for dashboard
-      categories: {},
-    };
-
-    // ─── 1. Security Debt ───────────────────────────────────
-    const securityIssues = [];
-    for (const issue of (scanResults.issues || [])) {
-      if (issue.id?.startsWith('SEC') || issue.category === 'security') {
-        securityIssues.push({
-          file: path.relative(this.config.rootPath, issue.file),
-          ...issue,
-          fixable: issue.id === 'SEC001' || issue.id === 'SEC002', // Can extract to env vars
-          fixAction: issue.id === 'SEC001' ? 'extract_to_env' : issue.id === 'SEC002' ? 'extract_to_env' : null,
-        });
-      }
-    }
-    debt.scores.security = Math.max(0, 100 - (securityIssues.filter(i => i.severity === 'critical').length * 25) - (securityIssues.filter(i => i.severity === 'high').length * 10));
-    debt.categories.security = { score: debt.scores.security, issues: securityIssues, label: 'Security', icon: 'shield' };
-
-    // ─── 2. Architecture Debt ───────────────────────────────
-    const archIssues = [];
-    const circular = this.depGraph.circularDeps || [];
-    const orphans = this.depGraph.getOrphanFiles() || [];
-    const critical = this.depGraph.getMostCriticalFiles(5) || [];
-
-    for (const cycle of circular) {
-      archIssues.push({
-        type: 'circular_dependency',
-        severity: 'high',
-        files: Array.isArray(cycle) ? cycle.map(f => path.relative(this.config.rootPath, f)) : [String(cycle)],
-        message: 'Circular dependency detected',
-        fixable: true,
-        fixAction: 'break_circular',
-        suggestion: 'Extract shared code into a new module to break the cycle',
-      });
-    }
-
-    for (const orphan of orphans) {
-      const orphanPath = typeof orphan === 'string' ? orphan : (orphan.file || orphan.path || String(orphan));
-      archIssues.push({
-        type: 'orphan_file',
-        severity: 'low',
-        file: path.relative(this.config.rootPath, orphanPath),
-        message: 'File has no imports and no exports consumed — potential dead code',
-        fixable: true,
-        fixAction: 'flag_for_removal',
-        suggestion: 'Review and remove if truly unused',
-      });
-    }
-
-    for (const crit of critical) {
-      const critPath = typeof crit === 'string' ? crit : (crit.file || crit.path || String(crit));
-      const dependents = typeof crit === 'object' ? (crit.dependents || crit.score || crit.count || 0) : 0;
-      if (dependents > 10) {
-        archIssues.push({
-          type: 'god_file',
-          severity: 'medium',
-          file: path.relative(this.config.rootPath, critPath),
-          dependents,
-          message: `${dependents} files depend on this — high blast radius if changed`,
-          fixable: false,
-          suggestion: 'Consider splitting into smaller, focused modules',
-        });
-      }
-    }
-
-    debt.scores.architecture = Math.max(0, 100 - (circular.length * 15) - (orphans.length * 1) - (archIssues.filter(i => i.type === 'god_file').length * 5));
-    debt.categories.architecture = { score: debt.scores.architecture, issues: archIssues, label: 'Architecture', icon: 'building' };
-
-    // ─── 3. Code Quality Debt ───────────────────────────────
-    const qualityIssues = [];
-    const HallucinationDetector = require('./hallucination-detector');
-    const hallDetector = new HallucinationDetector(this.config);
-    const hallResults = await hallDetector.scan(files);
-
-    // Add deprecated APIs as fixable items
-    for (const item of (hallResults.deprecatedAPIs || [])) {
-      qualityIssues.push({
-        file: path.relative(this.config.rootPath, item.file),
-        type: 'deprecated_api',
-        severity: 'high',
-        message: `${item.name} — deprecated since ${item.since}`,
-        fixable: true,
-        fixAction: 'update_deprecated_api',
-        suggestion: item.fix,
-      });
-    }
-
-    // Add hardcoded localhost URLs as fixable items
-    for (const item of (hallResults.aiSmells || [])) {
-      if (item.message && item.message.includes('localhost')) {
-        qualityIssues.push({
-          file: path.relative(this.config.rootPath, item.file),
-          type: 'hardcoded_localhost',
-          severity: 'medium',
-          message: item.message,
-          fixable: true,
-          fixAction: 'wrap_localhost_url',
-          suggestion: 'Use environment variable with localhost fallback',
-        });
-      }
-    }
-
-    for (const issue of (scanResults.issues || [])) {
-      if (issue.id?.startsWith('QUAL') || issue.category === 'quality' || issue.category === 'maintainability') {
-        qualityIssues.push({
-          file: path.relative(this.config.rootPath, issue.file),
-          ...issue,
-          fixable: ['QUAL001', 'QUAL003', 'QUAL005'].includes(issue.id), // console.log removal, etc.
-          fixAction: issue.id === 'QUAL001' ? 'remove_console_log' : null,
-        });
-      }
-    }
-    debt.scores.codeQuality = Math.max(0, 100 - (qualityIssues.filter(i => i.severity === 'high').length * 5) - (qualityIssues.filter(i => i.severity === 'medium').length * 2));
-    debt.categories.codeQuality = { score: debt.scores.codeQuality, issues: qualityIssues, label: 'Code Quality', icon: 'code' };
-
-    // ─── 4. Documentation / Mother Code Debt ────────────────
-    const docIssues = [];
-    let filesWithWidget = 0;
-    let filesWithoutWidget = 0;
-    let filesWithDrift = 0;
-
-    for (const file of files) {
-      try {
-        const content = fs.readFileSync(file, 'utf-8');
-        const hasWidget = /\/\*\*[\s\S]*?@(purpose|module|layer)[\s\S]*?\*\//.test(content);
-        if (hasWidget) {
-          filesWithWidget++;
-          // Check for drift
-          const analysis = await this.driftDetector.analyzeFile(file);
-          if (analysis.issues && analysis.issues.length > 0) {
-            filesWithDrift++;
-            for (const issue of analysis.issues) {
-              docIssues.push({
-                file: path.relative(this.config.rootPath, file),
-                ...issue,
-                fixable: true,
-                fixAction: 'regenerate_widget',
-              });
-            }
-          }
-        } else {
-          filesWithoutWidget++;
-          docIssues.push({
-            file: path.relative(this.config.rootPath, file),
-            type: 'missing_mother_code',
-            severity: 'info',
-            message: 'No Mother Code DNA — file lacks contextual awareness',
-            fixable: true,
-            fixAction: 'inject_widget',
-          });
-        }
-      } catch (e) { /* skip unreadable */ }
-    }
-
-    const coverage = files.length > 0 ? Math.round((filesWithWidget / files.length) * 100) : 0;
-    debt.scores.motherCode = Math.min(100, coverage + (filesWithDrift > 0 ? -10 : 0));
-    debt.scores.documentation = debt.scores.motherCode;
-    debt.categories.motherCode = {
-      score: debt.scores.motherCode,
-      coverage,
-      annotated: filesWithWidget,
-      missing: filesWithoutWidget,
-      drifted: filesWithDrift,
-      issues: docIssues,
-      label: 'Mother Code',
-      icon: 'dna',
-    };
-
-    // ─── 5. Dependency Health ───────────────────────────────
-    const depIssues = [];
-    // Check for very deep dependency chains
-    const summary = this.depGraph.getModuleSummary ? this.depGraph.getModuleSummary() : {};
-    debt.scores.dependencies = Math.max(0, 100 - (circular.length * 10) - (orphans.length * 0.5));
-    debt.categories.dependencies = { score: debt.scores.dependencies, issues: depIssues, label: 'Dependencies', icon: 'link' };
-
-    // ─── Calculate overall score ────────────────────────────
-    const weights = { security: 0.25, architecture: 0.2, codeQuality: 0.2, motherCode: 0.2, dependencies: 0.15 };
-    debt.scores.overall = Math.round(
-      debt.scores.security * weights.security +
-      debt.scores.architecture * weights.architecture +
-      debt.scores.codeQuality * weights.codeQuality +
-      debt.scores.motherCode * weights.motherCode +
-      debt.scores.dependencies * weights.dependencies
-    );
-
-    // ─── Sort into fixable / manual / info ──────────────────
-    for (const cat of Object.values(debt.categories)) {
-      for (const issue of cat.issues || []) {
-        debt.stats.totalIssues++;
-        if (issue.fixable) {
-          debt.fixable.push(issue);
-          debt.stats.fixableCount++;
-        } else if (issue.severity === 'info') {
-          debt.info.push(issue);
-        } else {
-          debt.manual.push(issue);
-          debt.stats.manualCount++;
-        }
-      }
-    }
-
-    // Estimate fix time
-    const fixMinutes = debt.stats.fixableCount * 0.5 + debt.stats.manualCount * 15;
-    debt.stats.estimatedFixTime = fixMinutes < 60
-      ? `${Math.round(fixMinutes)} minutes`
-      : `${Math.round(fixMinutes / 60)} hours`;
-
-    debt.stats.scanTime = Date.now() - startTime;
-
-    return debt;
-  }
-
-  /**
-   * THE FIX BUTTON
-   * Auto-fixes all fixable tech debt items
-   * Returns a report of what was fixed
-   */
-  async fix(files, options = {}) {
-    const debt = await this.analyze(files);
-    const fixes = [];
-    const failures = [];
-
-    for (const item of debt.fixable) {
-      if (options.dryRun) {
-        fixes.push({ ...item, status: 'would_fix' });
-        continue;
-      }
-
-      try {
-        switch (item.fixAction) {
-          case 'inject_widget': {
-            const fullPath = path.resolve(this.config.rootPath, item.file);
-            const content = fs.readFileSync(fullPath, 'utf-8');
-            const widget = await this.widgetGen.generateWidget(fullPath, content);
-            if (widget && widget.widgetString) {
-              const commentBlock = formatWidgetComment(widget.widgetString, fullPath);
-              fs.writeFileSync(fullPath, commentBlock + '\n\n' + content, 'utf-8');
-              fixes.push({ ...item, status: 'fixed' });
-            }
-            break;
-          }
-
-          case 'regenerate_widget': {
-            const fullPath = path.resolve(this.config.rootPath, item.file);
-            const content = fs.readFileSync(fullPath, 'utf-8');
-            // Remove old widget
-            const stripped = content.replace(/\/\*\*[\s\S]*?@(purpose|module|layer)[\s\S]*?\*\/\s*\n?\s*\n?/, '');
-            // Generate new widget with current state
-            const widget = await this.widgetGen.generateWidget(fullPath, stripped);
-            if (widget && widget.widgetString) {
-              const commentBlock = formatWidgetComment(widget.widgetString, fullPath);
-              fs.writeFileSync(fullPath, commentBlock + '\n\n' + stripped, 'utf-8');
-              fixes.push({ ...item, status: 'fixed' });
-            }
-            break;
-          }
-
-          case 'remove_console_log': {
-            const fullPath = path.resolve(this.config.rootPath, item.file);
-            let content = fs.readFileSync(fullPath, 'utf-8');
-            const before = content;
-            // Remove console.log lines (but not console.error or console.warn)
-            content = content.replace(/^\s*console\.log\(.*?\);\s*$/gm, '');
-            if (content !== before) {
-              fs.writeFileSync(fullPath, content, 'utf-8');
-              fixes.push({ ...item, status: 'fixed' });
-            }
-            break;
-          }
-
-          case 'update_deprecated_api': {
-            const fullPath = path.resolve(this.config.rootPath, item.file);
-            let content = fs.readFileSync(fullPath, 'utf-8');
-            const before = content;
-            // url.parse() → new URL()
-            content = content.replace(/url\.parse\(([^)]+)\)/g, 'new URL($1)');
-            // new Buffer() → Buffer.from()
-            content = content.replace(/new Buffer\(([^)]+)\)/g, 'Buffer.from($1)');
-            // require('sys') → require('util')
-            content = content.replace(/require\(['"]sys['"]\)/g, "require('util')");
-            // util.isArray() → Array.isArray()
-            content = content.replace(/util\.isArray\(/g, 'Array.isArray(');
-            // util.isFunction() is skipped — regex cannot safely handle arrow function arguments
-            // fs.exists() callback → fs.existsSync or fs.access
-            content = content.replace(/fs\.exists\(([^,]+),\s*/g, 'fs.access($1, ');
-            if (content !== before) {
-              fs.writeFileSync(fullPath, content, 'utf-8');
-              fixes.push({ ...item, status: 'fixed', detail: 'Replaced deprecated API with modern equivalent' });
-            } else {
-              fixes.push({ ...item, status: 'skipped', reason: 'Pattern not matched for auto-replacement' });
-            }
-            break;
-          }
-
-          case 'wrap_localhost_url': {
-            const fullPath = path.resolve(this.config.rootPath, item.file);
-            let content = fs.readFileSync(fullPath, 'utf-8');
-            const before = content;
-            // Wrap hardcoded localhost URLs in env var fallback
-            // Match: 'http://localhost:NNNN' or "http://localhost:NNNN" or `http://localhost:NNNN`
-            content = content.replace(
-              /(['"`])(https?:\/\/localhost:\d{2,5}(?:\/[^'"`]*)?)\1/g,
-              (match, quote, url) => {
-                // Generate an env var name from the URL
-                const portMatch = url.match(/:(\d+)/);
-                const port = portMatch ? portMatch[1] : 'PORT';
-                const envVar = `SERVICE_URL_${port}`;
-                return `(process.env.${envVar} || ${quote}${url}${quote})`;
-              }
-            );
-            if (content !== before) {
-              fs.writeFileSync(fullPath, content, 'utf-8');
-              fixes.push({ ...item, status: 'fixed', detail: 'Wrapped localhost URL in env var fallback' });
-            } else {
-              fixes.push({ ...item, status: 'skipped', reason: 'Pattern not matched for auto-replacement' });
-            }
-            break;
-          }
-
-          case 'extract_to_env': {
-            // Don't auto-fix secrets — too risky. Flag for manual review.
-            fixes.push({ ...item, status: 'flagged_for_review', reason: 'Secrets require manual extraction to .env' });
-            break;
-          }
-
-          case 'flag_for_removal': {
-            // Don't auto-delete files — just confirm they're orphans
-            fixes.push({ ...item, status: 'confirmed_orphan', reason: 'Verified no imports. Safe to remove manually.' });
-            break;
-          }
-
-          default:
-            fixes.push({ ...item, status: 'skipped', reason: 'No auto-fix available' });
-        }
-      } catch (err) {
-        failures.push({ ...item, status: 'failed', error: err.message });
-      }
-    }
-
-    return {
-      totalFixable: debt.fixable.length,
-      fixed: fixes.filter(f => f.status === 'fixed').length,
-      flagged: fixes.filter(f => f.status === 'flagged_for_review' || f.status === 'confirmed_orphan').length,
-      skipped: fixes.filter(f => f.status === 'skipped').length,
-      failed: failures.length,
-      fixes,
-      failures,
-      debtBefore: debt.scores.overall,
-      // Re-analyze after fixes to show improvement
-      ...(options.dryRun ? {} : { note: 'Run thuban report again to see updated scores' }),
-    };
-  }
-
-  /**
-   * Generate a human-readable tech debt report
-   * Suitable for dashboard display or terminal output
-   */
-  formatReport(debt) {
-    const C = {
-      reset: '\x1b[0m', bold: '\x1b[1m',
-      red: '\x1b[31m', green: '\x1b[32m', yellow: '\x1b[33m',
-      blue: '\x1b[34m', cyan: '\x1b[36m', gray: '\x1b[90m',
-      bgRed: '\x1b[41m', bgGreen: '\x1b[42m', bgYellow: '\x1b[43m',
-    };
-
-    const scoreBar = (score) => {
-      const filled = Math.round(score / 5);
-      const empty = 20 - filled;
-      const color = score >= 80 ? C.green : score >= 60 ? C.yellow : C.red;
-      return `${color}${'█'.repeat(filled)}${C.gray}${'░'.repeat(empty)}${C.reset} ${color}${score}%${C.reset}`;
-    };
-
-    const grade = (score) => {
-      if (score >= 90) return `${C.green}A${C.reset}`;
-      if (score >= 80) return `${C.green}B${C.reset}`;
-      if (score >= 70) return `${C.yellow}C${C.reset}`;
-      if (score >= 60) return `${C.yellow}D${C.reset}`;
-      return `${C.red}F${C.reset}`;
-    };
-
-    let output = '';
-    output += `\n${C.cyan}  ╔══════════════════════════════════════════════╗${C.reset}\n`;
-    output += `${C.cyan}  ║${C.bold}         THUBAN TECH DEBT REPORT               ${C.reset}${C.cyan}║${C.reset}\n`;
-    output += `${C.cyan}  ╚══════════════════════════════════════════════╝${C.reset}\n\n`;
-
-    output += `  ${C.bold}Overall Health:${C.reset}  ${scoreBar(debt.scores.overall)}  Grade: ${grade(debt.scores.overall)}\n\n`;
-
-    // Category breakdown
-    output += `  ${C.bold}Category Breakdown:${C.reset}\n\n`;
-    const categories = [
-      ['Security', debt.scores.security, 'shield'],
-      ['Architecture', debt.scores.architecture, 'building'],
-      ['Code Quality', debt.scores.codeQuality, 'code'],
-      ['Mother Code', debt.scores.motherCode, 'dna'],
-      ['Dependencies', debt.scores.dependencies, 'link'],
-    ];
-
-    for (const [name, score] of categories) {
-      output += `  ${name.padEnd(18)} ${scoreBar(score)}\n`;
-    }
-    output += '\n';
-
-    // Mother Code specific
-    if (debt.categories.motherCode) {
-      const mc = debt.categories.motherCode;
-      output += `  ${C.bold}Mother Code Coverage:${C.reset}\n`;
-      output += `  Annotated: ${C.cyan}${mc.annotated}${C.reset}  |  Missing: ${C.yellow}${mc.missing}${C.reset}  |  Drifted: ${mc.drifted > 0 ? C.red : C.green}${mc.drifted}${C.reset}  |  Coverage: ${mc.coverage >= 80 ? C.green : mc.coverage >= 40 ? C.yellow : C.red}${mc.coverage}%${C.reset}\n\n`;
-    }
-
-    // Summary
-    output += `  ${C.bold}Tech Debt Summary:${C.reset}\n`;
-    output += `  Total issues:     ${C.bold}${debt.stats.totalIssues}${C.reset}\n`;
-    output += `  Auto-fixable:     ${C.green}${debt.stats.fixableCount}${C.reset}  ${C.gray}← run 'thuban fix' to resolve${C.reset}\n`;
-    output += `  Manual review:    ${C.yellow}${debt.stats.manualCount}${C.reset}\n`;
-    output += `  Est. manual time: ${C.gray}${debt.stats.estimatedFixTime}${C.reset}\n`;
-    output += `  Scan time:        ${C.gray}${debt.stats.scanTime}ms${C.reset}\n\n`;
-
-    // Top fixable items
-    if (debt.fixable.length > 0) {
-      output += `  ${C.bold}Top Auto-Fixable Items:${C.reset}\n`;
-      const grouped = {};
-      for (const item of debt.fixable) {
-        const action = item.fixAction || 'unknown';
-        if (!grouped[action]) grouped[action] = { count: 0, label: action };
-        grouped[action].count++;
-      }
-      for (const [action, data] of Object.entries(grouped).sort((a, b) => b[1].count - a[1].count)) {
-        const label = {
-          'inject_widget': 'Inject Mother Code DNA',
-          'regenerate_widget': 'Update stale annotations',
-          'remove_console_log': 'Remove debug console.logs',
-          'extract_to_env': 'Extract hardcoded secrets to .env',
-          'flag_for_removal': 'Remove orphan files',
-          'break_circular': 'Break circular dependencies',
-        }[action] || action;
-        output += `    ${C.green}→${C.reset} ${label}: ${C.bold}${data.count}${C.reset} items\n`;
-      }
-      output += `\n  ${C.cyan}Run 'thuban fix [path]' to auto-fix all ${debt.stats.fixableCount} items${C.reset}\n\n`;
-    }
-
-    // Manual items (top 5)
-    if (debt.manual.length > 0) {
-      output += `  ${C.bold}Manual Review Required:${C.reset}\n`;
-      for (const item of debt.manual.slice(0, 5)) {
-        const sevColor = item.severity === 'critical' ? C.red : item.severity === 'high' ? C.red : C.yellow;
-        output += `  ${sevColor}${(item.severity || '').toUpperCase().padEnd(8)}${C.reset} ${C.cyan}${item.file || ''}${C.reset}\n`;
-        output += `  ${C.gray}         ${item.message || item.suggestion || ''}${C.reset}\n`;
-      }
-      if (debt.manual.length > 5) {
-        output += `  ${C.gray}  ... and ${debt.manual.length - 5} more${C.reset}\n`;
-      }
-      output += '\n';
-    }
-
-    return output;
-  }
-
-  /**
-   * Generate JSON report for dashboard / API consumption
-   */
-  toJSON(debt) {
-    return {
-      timestamp: new Date().toISOString(),
-      scores: debt.scores,
-      categories: Object.fromEntries(
-        Object.entries(debt.categories).map(([key, cat]) => [key, {
-          score: cat.score,
-          label: cat.label,
-          issueCount: cat.issues?.length || 0,
-          coverage: cat.coverage,
-        }])
-      ),
-      stats: debt.stats,
-      fixable: debt.fixable.map(i => ({ file: i.file, action: i.fixAction, severity: i.severity })),
-      manual: debt.manual.map(i => ({ file: i.file, message: i.message, severity: i.severity })),
-    };
-  }
-}
-
-module.exports = TechDebtAnalyzer;