@girardmedia/bootspring 1.2.0 → 2.0.3

package/cli/metrics.js

@@ -0,0 +1,480 @@
+/**
+ * Bootspring Metrics Command
+ * Collect and display project metrics
+ *
+ * @package bootspring
+ * @command metrics
+ */
+
+const config = require('../core/config');
+const utils = require('../core/utils');
+const metricsEngine = require('../core/metrics-engine');
+const projectState = require('../core/project-state');
+
+// ============================================================================
+// Display Functions
+// ============================================================================
+
+/**
+ * Create a visual bar
+ */
+function createBar(value, max = 100, width = 20) {
+  const filled = Math.round((value / max) * width);
+  const empty = width - filled;
+  const bar = '█'.repeat(filled) + '░'.repeat(empty);
+  return bar;
+}
+
+/**
+ * Get color based on score
+ */
+function getScoreColor(score) {
+  if (score >= 80) return utils.COLORS.green;
+  if (score >= 60) return utils.COLORS.yellow;
+  if (score >= 40) return utils.COLORS.magenta;
+  return utils.COLORS.red;
+}
+
+/**
+ * Display metrics overview
+ */
+function displayMetrics(results, options = {}) {
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}📊 Project Metrics${utils.COLORS.reset}
+${utils.COLORS.dim}Collected: ${new Date(results.timestamp).toLocaleString()}${utils.COLORS.reset}
+`);
+
+  // Overall score
+  const scoreColor = getScoreColor(results.overallScore);
+  console.log(`${utils.COLORS.bold}Overall Score${utils.COLORS.reset}`);
+  console.log(`  ${scoreColor}${utils.COLORS.bold}${results.overallScore}%${utils.COLORS.reset} ${createBar(results.overallScore)}`);
+  console.log();
+
+  // Category breakdown
+  console.log(`${utils.COLORS.bold}Categories${utils.COLORS.reset}`);
+  for (const [category, data] of Object.entries(results.categories)) {
+    const catColor = getScoreColor(data.average);
+    const catLabel = category.charAt(0).toUpperCase() + category.slice(1);
+    console.log(`  ${catLabel.padEnd(12)} ${catColor}${createBar(data.average, 100, 15)}${utils.COLORS.reset} ${data.average}%`);
+  }
+  console.log();
+
+  // Individual metrics
+  if (!options.compact) {
+    console.log(`${utils.COLORS.bold}Metrics${utils.COLORS.reset}`);
+
+    for (const [category, data] of Object.entries(results.categories)) {
+      console.log(`\n  ${utils.COLORS.cyan}${category.toUpperCase()}${utils.COLORS.reset}`);
+
+      for (const metric of data.metrics) {
+        const color = getScoreColor(metric.score);
+        const bar = createBar(metric.score, 100, 10);
+        const icon = metric.icon || '•';
+        console.log(`    ${icon} ${metric.label.padEnd(20)} ${color}${bar}${utils.COLORS.reset} ${metric.score}%`);
+      }
+    }
+  }
+}
+
+/**
+ * Display metrics dashboard (compact view)
+ */
+function displayDashboard(projectRoot) {
+  const state = projectState.loadState(projectRoot);
+
+  if (!state?.metrics) {
+    console.log(`${utils.COLORS.dim}No metrics collected yet. Run 'bootspring metrics collect' first.${utils.COLORS.reset}`);
+    return;
+  }
+
+  const m = state.metrics;
+  const color = getScoreColor(m.overallScore);
+
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}📊 Metrics Dashboard${utils.COLORS.reset}
+
+${utils.COLORS.bold}Score${utils.COLORS.reset} ${color}${m.overallScore}%${utils.COLORS.reset}
+${utils.COLORS.dim}Last updated: ${new Date(m.lastCollected).toLocaleString()}${utils.COLORS.reset}
+`);
+
+  // Categories
+  for (const [cat, data] of Object.entries(m.categories)) {
+    const catColor = getScoreColor(data.score);
+    const catLabel = cat.charAt(0).toUpperCase() + cat.slice(1);
+    console.log(`${catLabel.padEnd(12)} ${catColor}${data.score}%${utils.COLORS.reset}`);
+  }
+
+  // Trend
+  if (m.history && m.history.length > 1) {
+    const trend = m.history[0].score - m.history[1].score;
+    const trendIcon = trend > 0 ? '↑' : trend < 0 ? '↓' : '→';
+    const trendColor = trend > 0 ? utils.COLORS.green : trend < 0 ? utils.COLORS.red : utils.COLORS.dim;
+    console.log(`\n${utils.COLORS.bold}Trend${utils.COLORS.reset} ${trendColor}${trendIcon} ${Math.abs(trend)}%${utils.COLORS.reset}`);
+  }
+}
+
+/**
+ * Display metrics comparison with previous
+ */
+function displayComparison(current, previous) {
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}📊 Metrics Comparison${utils.COLORS.reset}
+`);
+
+  console.log(`${utils.COLORS.bold}Overall${utils.COLORS.reset}`);
+  const diff = current.overallScore - previous.overallScore;
+  const diffColor = diff > 0 ? utils.COLORS.green : diff < 0 ? utils.COLORS.red : utils.COLORS.dim;
+  const diffIcon = diff > 0 ? '↑' : diff < 0 ? '↓' : '→';
+  console.log(`  ${previous.overallScore}% → ${current.overallScore}% ${diffColor}(${diffIcon}${Math.abs(diff)})${utils.COLORS.reset}`);
+  console.log();
+
+  console.log(`${utils.COLORS.bold}By Metric${utils.COLORS.reset}`);
+  for (const [metricId, currentMetric] of Object.entries(current.metrics)) {
+    const prevMetric = previous.metrics[metricId];
+    if (!prevMetric) continue;
+
+    const metricDef = metricsEngine.METRICS[metricId];
+    const label = metricDef?.label || metricId;
+    const metricDiff = currentMetric.score - prevMetric.score;
+
+    if (Math.abs(metricDiff) >= 5) {
+      const mDiffColor = metricDiff > 0 ? utils.COLORS.green : utils.COLORS.red;
+      const mDiffIcon = metricDiff > 0 ? '↑' : '↓';
+      console.log(`  ${label.padEnd(20)} ${mDiffColor}${mDiffIcon}${Math.abs(metricDiff)}%${utils.COLORS.reset}`);
+    }
+  }
+}
+
+/**
+ * Generate badges markdown
+ */
+function generateBadges(metrics) {
+  const badges = [];
+
+  // Overall score badge
+  const score = metrics.overallScore;
+  const color = score >= 80 ? 'brightgreen' : score >= 60 ? 'yellow' : score >= 40 ? 'orange' : 'red';
+  badges.push(`![Metrics](https://img.shields.io/badge/metrics-${score}%25-${color})`);
+
+  // Category badges
+  for (const [cat, data] of Object.entries(metrics.categories)) {
+    const catColor = data.average >= 80 ? 'brightgreen' : data.average >= 60 ? 'yellow' : 'orange';
+    badges.push(`![${cat}](https://img.shields.io/badge/${cat}-${data.average}%25-${catColor})`);
+  }
+
+  return badges.join(' ');
+}
+
+/**
+ * Sync metrics to remote dashboard
+ * Sends raw metric values - server applies weights and calculates scores
+ */
+async function syncToRemote(projectRoot, metrics) {
+  const cfg = config.load();
+  const auth = require('../core/auth');
+  const session = require('../core/session');
+
+  // Get API base URL
+  const apiBase = cfg.apiBase || cfg.api?.baseUrl || 'https://bootspring.com';
+
+  // Get project ID from session
+  const currentProject = session.getCurrentProject();
+  const projectId = currentProject?.id || cfg.projectId || cfg.project?.id;
+  if (!projectId) {
+    console.log(`${utils.COLORS.dim}No project selected. Run 'bootspring switch <project>' first.${utils.COLORS.reset}`);
+    return;
+  }
+
+  // Get auth
+  const apiKey = auth.getApiKey() || cfg.api?.token;
+  if (!apiKey) {
+    console.log(`${utils.COLORS.dim}Not authenticated. Run 'bootspring auth login' first.${utils.COLORS.reset}`);
+    return;
+  }
+
+  const spinner = utils.createSpinner('Syncing to dashboard...').start();
+
+  try {
+    // Extract raw metric values only - no weights or calculations
+    // Server will apply the scoring algorithms
+    const rawMetrics = {
+      quality: {
+        test_coverage: metrics.metrics?.test_coverage?.score,
+        lint_score: metrics.metrics?.lint_score?.score,
+        type_coverage: metrics.metrics?.type_coverage?.score
+      },
+      security: {
+        dependency_audit: metrics.metrics?.dependency_audit?.score,
+        secrets_scan: metrics.metrics?.secrets_scan?.score,
+        gitignore_coverage: metrics.metrics?.gitignore_coverage?.score,
+        env_security: metrics.metrics?.env_security?.score
+      },
+      documentation: {
+        readme_quality: metrics.metrics?.readme_quality?.score,
+        api_docs: metrics.metrics?.api_docs?.score,
+        inline_comments: metrics.metrics?.inline_comments?.score
+      },
+      performance: {
+        bundle_size: metrics.metrics?.bundle_size?.score,
+        load_time: metrics.metrics?.load_time?.score
+      },
+      progress: {
+        todo_completion: metrics.metrics?.todo_completion?.score,
+        checkpoint_progress: metrics.metrics?.checkpoint_progress?.score,
+        commit_frequency: metrics.metrics?.commit_frequency?.score
+      }
+    };
+
+    // Send raw data to server for evaluation
+    const response = await fetch(`${apiBase}/api/projects/${projectId}/metrics/evaluate`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': apiKey
+      },
+      body: JSON.stringify({ rawMetrics }),
+      redirect: 'follow'
+    });
+
+    if (response.ok) {
+      const result = await response.json();
+      spinner.succeed('Metrics synced to dashboard');
+
+      // Display server-calculated results
+      console.log(`
+${utils.COLORS.bold}Server Evaluation:${utils.COLORS.reset}
+  Overall Score: ${result.overallScore}% (${result.overallGrade?.grade || 'N/A'})
+  Last Sync: ${result.lastSyncAt ? new Date(result.lastSyncAt).toLocaleString() : 'Now'}
+`);
+
+      // Show category breakdown
+      if (result.categories) {
+        console.log(`${utils.COLORS.bold}Category Scores:${utils.COLORS.reset}`);
+        for (const [catId, catData] of Object.entries(result.categories)) {
+          const cat = catData;
+          const label = catId.charAt(0).toUpperCase() + catId.slice(1);
+          console.log(`  ${label}: ${cat.score}% (${cat.grade?.grade || 'N/A'})`);
+        }
+        console.log();
+      }
+    } else {
+      const error = await response.json().catch(() => ({}));
+      spinner.fail(`Sync failed: ${error.error || response.status}`);
+    }
+  } catch (error) {
+    spinner.fail(`Sync error: ${error.message}`);
+  }
+}
+
+// ============================================================================
+// Commands
+// ============================================================================
+
+/**
+ * Collect all metrics
+ */
+async function collectMetrics(options = {}) {
+  const cfg = config.load();
+  const projectRoot = cfg._projectRoot;
+
+  const spinner = utils.createSpinner('Collecting metrics...').start();
+
+  try {
+    const results = await metricsEngine.collectAllMetrics(projectRoot, options);
+    spinner.stop();
+
+    // Store metrics
+    metricsEngine.storeMetrics(projectRoot, results);
+
+    // Display
+    displayMetrics(results, options);
+
+    // Sync if requested
+    if (options.sync) {
+      await syncToRemote(projectRoot, results);
+    }
+
+    // Generate badges if requested
+    if (options.badges) {
+      console.log(`\n${utils.COLORS.bold}Badges${utils.COLORS.reset}`);
+      console.log(generateBadges(results));
+    }
+
+    return results;
+  } catch (error) {
+    spinner.fail(`Collection failed: ${error.message}`);
+    throw error;
+  }
+}
+
+/**
+ * Show specific metric details
+ */
+async function showMetricDetail(metricId, projectRoot) {
+  const results = await metricsEngine.collectAllMetrics(projectRoot);
+  const metric = results.metrics[metricId];
+
+  if (!metric) {
+    console.log(`${utils.COLORS.red}Unknown metric: ${metricId}${utils.COLORS.reset}`);
+    console.log(`${utils.COLORS.dim}Available: ${Object.keys(results.metrics).join(', ')}${utils.COLORS.reset}`);
+    return;
+  }
+
+  const definition = metricsEngine.METRICS[metricId];
+  const color = getScoreColor(metric.score);
+
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}${definition?.icon || '📊'} ${definition?.label || metricId}${utils.COLORS.reset}
+
+${utils.COLORS.bold}Score${utils.COLORS.reset}
+  ${color}${metric.score}%${utils.COLORS.reset} ${createBar(metric.score)}
+
+${utils.COLORS.bold}Category${utils.COLORS.reset}
+  ${definition?.category || 'unknown'}
+
+${utils.COLORS.bold}Data${utils.COLORS.reset}
+${JSON.stringify(metric.data, null, 2).split('\n').map(l => '  ' + l).join('\n')}
+`);
+
+  if (metric.source) {
+    console.log(`${utils.COLORS.dim}Source: ${metric.source}${utils.COLORS.reset}`);
+  }
+}
+
+/**
+ * Export metrics as JSON
+ */
+async function exportMetrics(format, projectRoot) {
+  const results = await metricsEngine.collectAllMetrics(projectRoot);
+
+  if (format === 'json') {
+    console.log(JSON.stringify(results, null, 2));
+  } else if (format === 'csv') {
+    console.log('metric,score,category');
+    for (const [id, metric] of Object.entries(results.metrics)) {
+      const def = metricsEngine.METRICS[id];
+      console.log(`${id},${metric.score},${def?.category || ''}`);
+    }
+  } else if (format === 'markdown') {
+    console.log('# Project Metrics\n');
+    console.log(`**Overall Score:** ${results.overallScore}%\n`);
+    console.log('| Metric | Score | Category |');
+    console.log('|--------|-------|----------|');
+    for (const [id, metric] of Object.entries(results.metrics)) {
+      const def = metricsEngine.METRICS[id];
+      console.log(`| ${def?.label || id} | ${metric.score}% | ${def?.category || ''} |`);
+    }
+    console.log(`\n${generateBadges(results)}`);
+  }
+}
+
+/**
+ * Show help
+ */
+function showHelp() {
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}📊 Bootspring Metrics${utils.COLORS.reset}
+${utils.COLORS.dim}Collect and track project metrics${utils.COLORS.reset}
+
+${utils.COLORS.bold}Usage:${utils.COLORS.reset}
+  bootspring metrics <command> [options]
+
+${utils.COLORS.bold}Commands:${utils.COLORS.reset}
+  ${utils.COLORS.cyan}collect${utils.COLORS.reset}        Collect all metrics and store results
+  ${utils.COLORS.cyan}status${utils.COLORS.reset}         Show current metrics dashboard
+  ${utils.COLORS.cyan}show <metric>${utils.COLORS.reset}  Show details for specific metric
+  ${utils.COLORS.cyan}export${utils.COLORS.reset}         Export metrics (json, csv, markdown)
+  ${utils.COLORS.cyan}badges${utils.COLORS.reset}         Generate shields.io badge markdown
+  ${utils.COLORS.cyan}sync${utils.COLORS.reset}           Sync metrics to remote dashboard
+
+${utils.COLORS.bold}Options:${utils.COLORS.reset}
+  --compact      Show compact output
+  --sync         Sync to dashboard after collecting
+  --badges       Generate badges with output
+  --format <f>   Export format (json, csv, markdown)
+
+${utils.COLORS.bold}Available Metrics:${utils.COLORS.reset}
+${Object.entries(metricsEngine.METRICS).map(([id, m]) =>
+    `  ${m.icon} ${id.padEnd(18)} ${utils.COLORS.dim}${m.label}${utils.COLORS.reset}`
+  ).join('\n')}
+
+${utils.COLORS.bold}Examples:${utils.COLORS.reset}
+  bootspring metrics collect
+  bootspring metrics collect --sync
+  bootspring metrics status
+  bootspring metrics show testCoverage
+  bootspring metrics export --format markdown
+  bootspring metrics badges
+`);
+}
+
+/**
+ * Main run function
+ */
+async function run(args) {
+  const parsedArgs = utils.parseArgs(args);
+  const subcommand = parsedArgs._[0];
+  const cfg = config.load();
+  const projectRoot = cfg._projectRoot;
+
+  switch (subcommand) {
+    case 'collect':
+    case 'run':
+      await collectMetrics({
+        sync: parsedArgs.sync,
+        badges: parsedArgs.badges,
+        compact: parsedArgs.compact
+      });
+      break;
+
+    case 'status':
+    case 'dashboard':
+      displayDashboard(projectRoot);
+      break;
+
+    case 'show':
+    case 'detail': {
+      const metricId = parsedArgs._[1];
+      if (!metricId) {
+        console.log(`${utils.COLORS.red}Please specify a metric ID${utils.COLORS.reset}`);
+        console.log(`${utils.COLORS.dim}Example: bootspring metrics show testCoverage${utils.COLORS.reset}`);
+        return;
+      }
+      await showMetricDetail(metricId, projectRoot);
+      break;
+    }
+
+    case 'export':
+      await exportMetrics(parsedArgs.format || 'json', projectRoot);
+      break;
+
+    case 'badges': {
+      const results = await metricsEngine.collectAllMetrics(projectRoot);
+      console.log(generateBadges(results));
+      break;
+    }
+
+    case 'sync': {
+      const metrics = await metricsEngine.collectAllMetrics(projectRoot);
+      await syncToRemote(projectRoot, metrics);
+      break;
+    }
+
+    case 'help':
+    case '-h':
+    case '--help':
+      showHelp();
+      break;
+
+    default:
+      if (!subcommand) {
+        // Default to status
+        displayDashboard(projectRoot);
+      } else {
+        utils.print.error(`Unknown command: ${subcommand}`);
+        showHelp();
+      }
+  }
+}
+
+module.exports = { run, collectMetrics, displayMetrics, generateBadges };