thuban 0.3.3 → 0.4.0

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

@@ -1,194 +0,0 @@
-/**
- * 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;

package/packages/scanner/widget-generator.js

@@ -1,415 +0,0 @@
-/**
- * Sentinel Widget Generator
- *
- * Automatically generates widget contracts for files that don't have them.
- * Uses dependency graph, code analysis, and file path heuristics to
- * create meaningful @purpose, @module, @layer, etc. annotations.
- *
- * @purpose Generate widget contracts for undocumented files
- * @module sentinel
- * @layer infrastructure
- * @imports-from dependency-graph, fs, path
- * @exports-to sentinel-core, CLI tools
- * @side-effects File system reads; optionally writes widgets to files
- */
-
-const fs = require('fs');
-const path = require('path');
-const DependencyGraph = require('./dependency-graph');
-
-class WidgetGenerator {
-  constructor(config = {}) {
-    this.config = {
-      rootPath: config.rootPath || process.cwd(),
-      dryRun: config.dryRun !== false, // Default to dry run (don't write)
-      ...config
-    };
-
-    this.dependencyGraph = config.dependencyGraph || null;
-
-    // Module detection patterns
-    this.modulePatterns = {
-      'sentinel': /^sentinel[\\\/]/,
-      'citadel': /^citadel[\\\/]/,
-      'forge': /^forge[\\\/]/,
-      'server': /^server[\\\/]/,
-      'build-engine': /^build-engine[\\\/]/,
-      'autopilot': /^autopilot[\\\/]/,
-      'silverwings': /^silverwings[\\\/]/,
-      'output': /^output[\\\/]/
-    };
-
-    // Layer detection patterns
-    this.layerPatterns = {
-      'presentation': /routes|api|handlers|controllers|views/i,
-      'application': /service|manager|orchestrat|core|engine/i,
-      'domain': /model|entity|domain|types/i,
-      'infrastructure': /utils|helpers|lib|data|store|memory/i
-    };
-
-    // Side effect patterns
-    this.sideEffectPatterns = [
-      { pattern: /fs\.(write|append|unlink|mkdir|rmdir|rename)/i, effect: 'File system writes' },
-      { pattern: /fs\.read/i, effect: 'File system reads' },
-      { pattern: /fetch\(|axios\.|http\.|https\./i, effect: 'HTTP requests' },
-      { pattern: /process\.exit/i, effect: 'Process termination' },
-      { pattern: /child_process|spawn|exec\(/i, effect: 'Spawns child processes' },
-      { pattern: /console\.(log|error|warn)/i, effect: 'Console output' },
-      { pattern: /\.emit\(|EventEmitter/i, effect: 'Event emission' },
-      { pattern: /supabase|createClient/i, effect: 'Database operations' },
-      { pattern: /twilio|sendgrid|resend/i, effect: 'External API calls' }
-    ];
-
-    // Purpose detection from common patterns
-    this.purposePatterns = [
-      { pattern: /class\s+(\w+).*extends.*Router/i, purpose: (m) => `Express router for ${m[1]}` },
-      { pattern: /class\s+(\w+).*extends.*EventEmitter/i, purpose: (m) => `Event-driven ${m[1]} component` },
-      { pattern: /class\s+(\w+)/i, purpose: (m) => `${m[1]} class implementation` },
-      { pattern: /module\.exports\s*=\s*\{([^}]+)\}/i, purpose: (m) => `Exports: ${m[1].match(/\w+/g)?.slice(0, 5).join(', ')}` },
-      { pattern: /router\.(get|post|put|delete)/i, purpose: () => 'API route handlers' },
-      { pattern: /async function\s+(\w+)/i, purpose: (m) => `Provides ${m[1]} functionality` },
-      { pattern: /function\s+(\w+)/i, purpose: (m) => `Provides ${m[1]} functionality` }
-    ];
-  }
-
-  /**
-   * Generate widgets for all files missing them
-   */
-  async generateAll() {
-    console.log('[WIDGET-GENERATOR] Starting widget generation...');
-
-    // Build dependency graph if not provided
-    if (!this.dependencyGraph) {
-      this.dependencyGraph = new DependencyGraph({ rootPath: this.config.rootPath });
-      await this.dependencyGraph.build();
-    }
-
-    // Find files without widgets
-    const files = await this._discoverFiles(this.config.rootPath);
-    const results = {
-      total: files.length,
-      generated: 0,
-      skipped: 0,
-      alreadyHasWidget: 0,
-      widgets: []
-    };
-
-    for (const file of files) {
-      const content = fs.readFileSync(file, 'utf8');
-
-      // Skip if already has widget
-      if (this._hasWidget(content)) {
-        results.alreadyHasWidget++;
-        continue;
-      }
-
-      const widget = await this.generateWidget(file, content);
-      results.generated++;
-      results.widgets.push({
-        file,
-        relativePath: path.relative(this.config.rootPath, file),
-        widget
-      });
-
-      // Apply widget if not dry run
-      if (!this.config.dryRun) {
-        await this._applyWidget(file, content, widget);
-      }
-    }
-
-    console.log(`[WIDGET-GENERATOR] Generated ${results.generated} widgets (${results.alreadyHasWidget} already had widgets)`);
-    return results;
-  }
-
-  /**
-   * Generate widget for a single file
-   */
-  async generateWidget(filePath, content = null) {
-    if (!content) {
-      content = fs.readFileSync(filePath, 'utf8');
-    }
-
-    const relativePath = path.relative(this.config.rootPath, filePath);
-    const fileName = path.basename(filePath, path.extname(filePath));
-
-    // Analyze file
-    const analysis = {
-      purpose: this._detectPurpose(content, fileName, relativePath),
-      module: this._detectModule(relativePath),
-      layer: this._detectLayer(relativePath, content),
-      importsFrom: this._getImportsFrom(filePath),
-      exportsTo: this._getExportsTo(filePath),
-      sideEffects: this._detectSideEffects(content),
-      criticalFor: this._detectCriticalFor(filePath)
-    };
-
-    // Build widget string
-    const widget = this._buildWidgetString(analysis, fileName);
-
-    return {
-      analysis,
-      widgetString: widget,
-      fileName,
-      relativePath
-    };
-  }
-
-  /**
-   * Preview widgets for all files (dry run report)
-   */
-  async preview(limit = 20) {
-    const results = await this.generateAll();
-
-    console.log('\n' + '='.repeat(70));
-    console.log('WIDGET GENERATION PREVIEW');
-    console.log('='.repeat(70));
-    console.log(`Total files: ${results.total}`);
-    console.log(`Already have widgets: ${results.alreadyHasWidget}`);
-    console.log(`Will generate: ${results.generated}`);
-    console.log('');
-
-    for (const item of results.widgets.slice(0, limit)) {
-      console.log('-'.repeat(70));
-      console.log(`FILE: ${item.relativePath}`);
-      console.log('-'.repeat(70));
-      console.log(item.widget.widgetString);
-      console.log('');
-    }
-
-    if (results.widgets.length > limit) {
-      console.log(`... and ${results.widgets.length - limit} more files`);
-    }
-
-    return results;
-  }
-
-  /**
-   * Apply widgets to files (actually writes them)
-   */
-  async apply() {
-    this.config.dryRun = false;
-    const results = await this.generateAll();
-    console.log(`[WIDGET-GENERATOR] Applied ${results.generated} widgets to files`);
-    return results;
-  }
-
-  // Private methods
-
-  _hasWidget(content) {
-    // Check for existing widget with @purpose, @module, or @layer
-    const widgetPattern = /\/\*\*[\s\S]*?@(purpose|module|layer)[\s\S]*?\*\//;
-    return widgetPattern.test(content);
-  }
-
-  _detectPurpose(content, fileName, relativePath) {
-    // Try pattern matching first
-    for (const { pattern, purpose } of this.purposePatterns) {
-      const match = content.match(pattern);
-      if (match) {
-        return typeof purpose === 'function' ? purpose(match) : purpose;
-      }
-    }
-
-    // Fall back to file name analysis
-    const nameWords = fileName.replace(/[-_]/g, ' ').replace(/([A-Z])/g, ' $1').trim();
-
-    // Common suffixes
-    if (fileName.includes('route')) return `Route handlers for ${nameWords}`;
-    if (fileName.includes('api')) return `API endpoints for ${nameWords}`;
-    if (fileName.includes('service')) return `Service layer for ${nameWords}`;
-    if (fileName.includes('manager')) return `Manager for ${nameWords}`;
-    if (fileName.includes('store')) return `State store for ${nameWords}`;
-    if (fileName.includes('util')) return `Utility functions for ${nameWords}`;
-    if (fileName.includes('helper')) return `Helper functions for ${nameWords}`;
-    if (fileName.includes('test')) return `Tests for ${nameWords}`;
-    if (fileName.includes('config')) return `Configuration for ${nameWords}`;
-    if (fileName.includes('index')) return `Entry point for ${path.dirname(relativePath).split(path.sep).pop()}`;
-
-    return `Provides ${nameWords} functionality`;
-  }
-
-  _detectModule(relativePath) {
-    const normalized = relativePath.replace(/\\/g, '/');
-
-    for (const [module, pattern] of Object.entries(this.modulePatterns)) {
-      if (pattern.test(normalized)) {
-        return module;
-      }
-    }
-
-    // Use first directory as module
-    const parts = normalized.split('/');
-    return parts[0] || 'root';
-  }
-
-  _detectLayer(relativePath, content) {
-    // Check path patterns
-    for (const [layer, pattern] of Object.entries(this.layerPatterns)) {
-      if (pattern.test(relativePath)) {
-        return layer;
-      }
-    }
-
-    // Check content patterns
-    if (/router\.(get|post|put|delete)|app\.(get|post)/i.test(content)) {
-      return 'presentation';
-    }
-    if (/class.*Service|class.*Manager/i.test(content)) {
-      return 'application';
-    }
-    if (/class.*Model|schema|entity/i.test(content)) {
-      return 'domain';
-    }
-
-    return 'application'; // Default
-  }
-
-  _getImportsFrom(filePath) {
-    if (!this.dependencyGraph) return [];
-
-    const deps = this.dependencyGraph.getDependencies(filePath);
-    const imports = [];
-
-    for (const dep of deps.slice(0, 10)) { // Limit to 10
-      if (dep.resolved) {
-        const relPath = path.relative(this.config.rootPath, dep.resolved);
-        const moduleParts = relPath.split(path.sep);
-        const module = moduleParts[0];
-        const file = moduleParts[moduleParts.length - 1];
-        imports.push(`${module}/${file}`);
-      } else if (!dep.module.startsWith('.')) {
-        // External module
-        imports.push(dep.module);
-      }
-    }
-
-    return imports;
-  }
-
-  _getExportsTo(filePath) {
-    if (!this.dependencyGraph) return [];
-
-    const dependents = this.dependencyGraph.getDependents(filePath);
-    const exports = [];
-
-    for (const dep of dependents.slice(0, 10)) { // Limit to 10
-      const relPath = path.relative(this.config.rootPath, dep);
-      const moduleParts = relPath.split(path.sep);
-      const module = moduleParts[0];
-      exports.push(module);
-    }
-
-    // Deduplicate
-    return [...new Set(exports)];
-  }
-
-  _detectSideEffects(content) {
-    const effects = [];
-
-    for (const { pattern, effect } of this.sideEffectPatterns) {
-      if (pattern.test(content)) {
-        effects.push(effect);
-      }
-    }
-
-    return effects.length > 0 ? effects : ['None detected'];
-  }
-
-  _detectCriticalFor(filePath) {
-    if (!this.dependencyGraph) return [];
-
-    const impact = this.dependencyGraph.getImpactAnalysis(filePath);
-
-    if (impact.riskLevel === 'critical') {
-      return [`CRITICAL: ${impact.totalImpact} files depend on this`];
-    }
-    if (impact.riskLevel === 'high') {
-      return [`High impact: ${impact.totalImpact} files depend on this`];
-    }
-    if (impact.affectedModules.length > 0) {
-      return impact.affectedModules.slice(0, 5);
-    }
-
-    return [];
-  }
-
-  _buildWidgetString(analysis, fileName) {
-    const lines = [
-      '/**',
-      ` * ${this._toTitleCase(fileName)}`,
-      ' *',
-      ` * @purpose ${analysis.purpose}`,
-      ` * @module ${analysis.module}`,
-      ` * @layer ${analysis.layer}`
-    ];
-
-    if (analysis.importsFrom.length > 0) {
-      lines.push(` * @imports-from ${analysis.importsFrom.join(', ')}`);
-    }
-
-    if (analysis.exportsTo.length > 0) {
-      lines.push(` * @exports-to ${analysis.exportsTo.join(', ')}`);
-    }
-
-    lines.push(` * @side-effects ${analysis.sideEffects.join(', ')}`);
-
-    if (analysis.criticalFor.length > 0) {
-      lines.push(` * @critical-for ${analysis.criticalFor.join(', ')}`);
-    }
-
-    lines.push(' */');
-
-    return lines.join('\n');
-  }
-
-  _toTitleCase(str) {
-    return str
-      .replace(/[-_]/g, ' ')
-      .replace(/([A-Z])/g, ' $1')
-      .trim()
-      .split(' ')
-      .map(w => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
-      .join(' ');
-  }
-
-  async _applyWidget(filePath, content, widget) {
-    // Prepend widget to file content
-    const newContent = widget.widgetString + '\n\n' + content;
-
-    try {
-      fs.writeFileSync(filePath, newContent, 'utf8');
-      return true;
-    } catch (error) {
-      console.error(`[WIDGET-GENERATOR] Failed to write widget to ${filePath}:`, error.message);
-      return false;
-    }
-  }
-
-  async _discoverFiles(dir, files = []) {
-    const ignorePatterns = ['node_modules', '.git', 'dist', '.vite', '.orion'];
-
-    try {
-      const entries = fs.readdirSync(dir, { withFileTypes: true });
-
-      for (const entry of entries) {
-        if (ignorePatterns.some(p => entry.name === p || entry.name.startsWith(p))) {
-          continue;
-        }
-
-        const fullPath = path.join(dir, entry.name);
-
-        if (entry.isDirectory()) {
-          await this._discoverFiles(fullPath, files);
-        } else if (entry.isFile() && entry.name.endsWith('.js')) {
-          files.push(fullPath);
-        }
-      }
-    } catch (error) {
-      // Skip inaccessible directories
-    }
-
-    return files;
-  }
-}
-
-module.exports = WidgetGenerator;