thuban 0.3.0

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

@@ -0,0 +1,483 @@
+/**
+ * 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');
+
+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 [file, result] of Object.entries(scanResults)) {
+      if (result.issues) {
+        for (const issue of result.issues) {
+          if (issue.id?.startsWith('SEC') || issue.category === 'security') {
+            securityIssues.push({
+              file: path.relative(this.config.rootPath, 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 = [];
+    for (const [file, result] of Object.entries(scanResults)) {
+      if (result.issues) {
+        for (const issue of result.issues) {
+          if (issue.id?.startsWith('QUAL') || issue.category === 'quality' || issue.category === 'maintainability') {
+            qualityIssues.push({
+              file: path.relative(this.config.rootPath, 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) {
+              fs.writeFileSync(fullPath, widget.widgetString + '\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) {
+              fs.writeFileSync(fullPath, widget.widgetString + '\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 '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;

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

@@ -0,0 +1,194 @@
+/**
+ * Thuban Tech Debt Cost Calculator
+ *
+ * @purpose Translate tech debt into £/hours so CTOs can see the business cost
+ * @module thuban
+ * @layer scanner
+ * @exports-to cli
+ * @critical-for Sales — CTOs buy when they see the number
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Cost model — conservative estimates
+const COST_MODEL = {
+  hourlyRate: 80,           // £/hr average UK developer
+  weeklyDriftHours: 3,      // Hours of new debt accumulated per week per 1000 files
+
+  // Minutes to fix each issue type manually (without Thuban)
+  manualFixMinutes: {
+    hallucination: 30,       // Finding + understanding + replacing a phantom API
+    deprecated: 15,          // Researching replacement + updating
+    security: 45,            // Security issues need careful review
+    circular_dep: 60,        // Untangling circular dependencies
+    orphan_file: 5,          // Reviewing and deleting
+    missing_annotation: 2,   // Adding Mother Code DNA
+    copy_paste: 20,          // Extracting to shared utility
+    ghost_code: 10,          // Reviewing and removing dead functions
+    code_smell: 10,          // General refactoring
+    drift: 15,               // Re-aligning annotation with reality
+  },
+
+  // Minutes with Thuban auto-fix
+  thubanFixMinutes: {
+    hallucination: 0.5,      // Auto-suggests replacement
+    deprecated: 0.5,         // Auto-replaces
+    security: 5,             // Flags + suggests but needs human review
+    circular_dep: 5,         // Shows the cycle, suggests break point
+    orphan_file: 0.5,        // Auto-flags for deletion
+    missing_annotation: 0.1, // Auto-injects
+    copy_paste: 2,           // Shows cluster, suggests extraction
+    ghost_code: 0.5,         // Auto-flags for removal
+    code_smell: 1,           // Auto-fixes common patterns
+    drift: 0.5,              // Auto-updates annotation
+  },
+};
+
+class TechDebtCostCalculator {
+  constructor(opts = {}) {
+    this.hourlyRate = opts.hourlyRate || COST_MODEL.hourlyRate;
+    this.currency = opts.currency || '£';
+  }
+
+  /**
+   * Calculate cost from a list of issues
+   */
+  calculate(issues, fileCount = 0) {
+    const breakdown = {};
+    let totalManualMinutes = 0;
+    let totalThubanMinutes = 0;
+
+    for (const issue of issues) {
+      const category = this._categorize(issue);
+      if (!breakdown[category]) {
+        breakdown[category] = { count: 0, manualMinutes: 0, thubanMinutes: 0 };
+      }
+
+      const manualMin = COST_MODEL.manualFixMinutes[category] || 10;
+      const thubanMin = COST_MODEL.thubanFixMinutes[category] || 1;
+
+      breakdown[category].count++;
+      breakdown[category].manualMinutes += manualMin;
+      breakdown[category].thubanMinutes += thubanMin;
+      totalManualMinutes += manualMin;
+      totalThubanMinutes += thubanMin;
+    }
+
+    const manualHours = totalManualMinutes / 60;
+    const thubanHours = totalThubanMinutes / 60;
+    const manualCost = manualHours * this.hourlyRate;
+    const thubanCost = thubanHours * this.hourlyRate;
+    const savings = manualCost - thubanCost;
+    const savingsPercent = manualCost > 0 ? Math.round((savings / manualCost) * 100) : 0;
+
+    // Weekly debt accumulation estimate
+    const weeklyNewDebt = (fileCount / 1000) * COST_MODEL.weeklyDriftHours;
+    const monthlyNewDebtCost = weeklyNewDebt * 4 * this.hourlyRate;
+
+    // ROI calculation
+    const thubanMonthlyCost = 19; // Pro tier
+    const monthlyROI = savings > 0 ? Math.round(savings / thubanMonthlyCost) : 0;
+
+    return {
+      summary: {
+        totalIssues: issues.length,
+        manualHours: Math.round(manualHours * 10) / 10,
+        manualCost: Math.round(manualCost),
+        thubanHours: Math.round(thubanHours * 10) / 10,
+        thubanCost: Math.round(thubanCost),
+        savings: Math.round(savings),
+        savingsPercent,
+        timeSaved: this._formatTime(totalManualMinutes - totalThubanMinutes),
+      },
+      breakdown: Object.entries(breakdown).map(([category, data]) => ({
+        category,
+        count: data.count,
+        manualTime: this._formatTime(data.manualMinutes),
+        thubanTime: this._formatTime(data.thubanMinutes),
+        manualCost: Math.round((data.manualMinutes / 60) * this.hourlyRate),
+        thubanCost: Math.round((data.thubanMinutes / 60) * this.hourlyRate),
+      })).sort((a, b) => b.manualCost - a.manualCost),
+      projection: {
+        weeklyNewDebtHours: Math.round(weeklyNewDebt * 10) / 10,
+        monthlyNewDebtCost: Math.round(monthlyNewDebtCost),
+        monthlyThubanCost: thubanMonthlyCost,
+        monthlyROI: `${monthlyROI}x`,
+        annualSavings: Math.round(savings + (monthlyNewDebtCost * 12)),
+        verdict: monthlyROI >= 5
+          ? 'Thuban pays for itself within the first scan.'
+          : monthlyROI >= 2
+          ? 'Thuban pays for itself within the first week.'
+          : 'Thuban will save you money within the first month.',
+      },
+    };
+  }
+
+  /**
+   * Format for CLI output
+   */
+  formatCLI(result) {
+    const lines = [];
+    const s = result.summary;
+    const p = result.projection;
+    const c = this.currency;
+
+    lines.push('');
+    lines.push('  TECH DEBT COST ESTIMATE');
+    lines.push('');
+    lines.push(`  Current debt:        ${s.manualHours} developer-hours to fix manually`);
+    lines.push(`  At ${c}${this.hourlyRate}/hr:          ${c}${s.manualCost.toLocaleString()} if you fix it yourself`);
+    lines.push(`  With Thuban:         ${s.thubanHours} hours (${s.timeSaved} saved)`);
+    lines.push(`  You save:            ${c}${s.savings.toLocaleString()} (${s.savingsPercent}%)`);
+    lines.push('');
+
+    // Breakdown table
+    lines.push('  BREAKDOWN');
+    lines.push(`  ${'Category'.padEnd(20)} ${'Count'.padEnd(8)} ${'Manual'.padEnd(12)} ${'Thuban'.padEnd(12)} ${'Saving'.padEnd(10)}`);
+    lines.push('  ' + '-'.repeat(62));
+    for (const b of result.breakdown) {
+      const saving = `${c}${b.manualCost - b.thubanCost}`;
+      lines.push(`  ${b.category.padEnd(20)} ${String(b.count).padEnd(8)} ${(c + b.manualCost).padEnd(12)} ${(c + b.thubanCost).padEnd(12)} ${saving.padEnd(10)}`);
+    }
+    lines.push('');
+
+    // Projection
+    lines.push('  PROJECTION');
+    lines.push(`  Every week you wait, ${p.weeklyNewDebtHours} hours of new debt accumulates.`);
+    lines.push(`  That's ${c}${p.monthlyNewDebtCost}/month in growing technical debt.`);
+    lines.push(`  Thuban Pro costs ${c}${p.monthlyThubanCost}/month. ROI: ${p.monthlyROI}.`);
+    lines.push('');
+    lines.push(`  ${p.verdict}`);
+    lines.push('');
+
+    return lines.join('\n');
+  }
+
+  // ─── Private ─────────────────────────────────────────────
+
+  _categorize(issue) {
+    const cat = (issue.category || '').toLowerCase();
+    const id = (issue.id || '').toLowerCase();
+
+    if (cat === 'hallucination' || id.startsWith('hall')) return 'hallucination';
+    if (cat === 'deprecated' || id.startsWith('depr')) return 'deprecated';
+    if (cat === 'security') return 'security';
+    if (cat === 'circular' || id.includes('circular')) return 'circular_dep';
+    if (cat === 'orphan' || id.includes('orphan')) return 'orphan_file';
+    if (cat === 'drift') return 'drift';
+    if (cat === 'ghost' || id.includes('ghost')) return 'ghost_code';
+    if (cat === 'copy_paste' || id.includes('duplicate')) return 'copy_paste';
+    if (cat === 'annotation' || id.includes('mother')) return 'missing_annotation';
+    return 'code_smell';
+  }
+
+  _formatTime(minutes) {
+    if (minutes < 60) return `${Math.round(minutes)} mins`;
+    const hours = Math.floor(minutes / 60);
+    const mins = Math.round(minutes % 60);
+    if (mins === 0) return `${hours}h`;
+    return `${hours}h ${mins}m`;
+  }
+}
+
+module.exports = TechDebtCostCalculator;