@girardmedia/bootspring 1.2.0 → 2.0.3

package/core/metrics-engine.js

@@ -0,0 +1,768 @@
+/**
+ * Bootspring Metrics Engine
+ * Comprehensive project metrics tracking and scoring
+ *
+ * @package bootspring
+ * @module core/metrics-engine
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const projectState = require('./project-state');
+
+// ============================================================================
+// Metric Definitions
+// ============================================================================
+
+const METRICS = {
+  // Health & Progress
+  health: {
+    label: 'Health Score',
+    category: 'progress',
+    weight: 1.0,
+    icon: '💚'
+  },
+  checkpoints: {
+    label: 'Checkpoint Progress',
+    category: 'progress',
+    weight: 0.2,
+    icon: '✅'
+  },
+  security: {
+    label: 'Security Score',
+    category: 'quality',
+    weight: 0.25,
+    icon: '🔒'
+  },
+
+  // Code Quality
+  testCoverage: {
+    label: 'Test Coverage',
+    category: 'quality',
+    weight: 0.2,
+    icon: '🧪'
+  },
+  codeComplexity: {
+    label: 'Code Complexity',
+    category: 'quality',
+    weight: 0.1,
+    invert: true, // Lower is better
+    icon: '🔄'
+  },
+  lintScore: {
+    label: 'Lint Score',
+    category: 'quality',
+    weight: 0.1,
+    icon: '✨'
+  },
+  typeScore: {
+    label: 'TypeScript Coverage',
+    category: 'quality',
+    weight: 0.1,
+    icon: '📘'
+  },
+
+  // Documentation
+  docsCoverage: {
+    label: 'Documentation',
+    category: 'docs',
+    weight: 0.15,
+    icon: '📚'
+  },
+  readmeScore: {
+    label: 'README Quality',
+    category: 'docs',
+    weight: 0.05,
+    icon: '📖'
+  },
+  apiDocs: {
+    label: 'API Documentation',
+    category: 'docs',
+    weight: 0.1,
+    icon: '🔌'
+  },
+
+  // Performance
+  bundleSize: {
+    label: 'Bundle Size',
+    category: 'performance',
+    weight: 0.1,
+    invert: true,
+    icon: '📦'
+  },
+  buildTime: {
+    label: 'Build Time',
+    category: 'performance',
+    weight: 0.05,
+    invert: true,
+    icon: '⏱️'
+  },
+  lighthouseScore: {
+    label: 'Lighthouse Score',
+    category: 'performance',
+    weight: 0.15,
+    icon: '🚀'
+  },
+
+  // Activity
+  commitFrequency: {
+    label: 'Commit Frequency',
+    category: 'activity',
+    weight: 0.1,
+    icon: '📊'
+  },
+  prVelocity: {
+    label: 'PR Velocity',
+    category: 'activity',
+    weight: 0.05,
+    icon: '🔀'
+  },
+  issueResolution: {
+    label: 'Issue Resolution',
+    category: 'activity',
+    weight: 0.05,
+    icon: '🎯'
+  },
+
+  // Todos & Tasks
+  todoCompletion: {
+    label: 'Todo Completion',
+    category: 'progress',
+    weight: 0.1,
+    icon: '☑️'
+  },
+  technicalDebt: {
+    label: 'Technical Debt',
+    category: 'quality',
+    weight: 0.1,
+    invert: true,
+    icon: '💳'
+  }
+};
+
+// ============================================================================
+// Metric Collectors
+// ============================================================================
+
+/**
+ * Collect test coverage metrics
+ */
+async function collectTestCoverage(projectRoot) {
+  const result = { score: 0, data: null, source: null };
+
+  // Check for coverage reports
+  const coveragePaths = [
+    'coverage/coverage-summary.json',
+    'coverage/lcov-report/index.html',
+    '.nyc_output/coverage-summary.json'
+  ];
+
+  for (const coveragePath of coveragePaths) {
+    const fullPath = path.join(projectRoot, coveragePath);
+    if (fs.existsSync(fullPath)) {
+      result.source = coveragePath;
+
+      if (coveragePath.endsWith('.json')) {
+        try {
+          const coverage = JSON.parse(fs.readFileSync(fullPath, 'utf-8'));
+          if (coverage.total) {
+            const { lines, statements, functions, branches } = coverage.total;
+            result.data = {
+              lines: lines?.pct || 0,
+              statements: statements?.pct || 0,
+              functions: functions?.pct || 0,
+              branches: branches?.pct || 0
+            };
+            result.score = Math.round(
+              (result.data.lines + result.data.statements +
+               result.data.functions + result.data.branches) / 4
+            );
+          }
+        } catch {
+          // Invalid JSON
+        }
+      } else if (coveragePath.includes('lcov')) {
+        // Parse coverage from HTML (basic extraction)
+        try {
+          const html = fs.readFileSync(fullPath, 'utf-8');
+          const match = html.match(/(\d+\.?\d*)%\s*(?:statements|lines)/i);
+          if (match) {
+            result.score = Math.round(parseFloat(match[1]));
+            result.data = { lines: result.score };
+          }
+        } catch {
+          // Parse error
+        }
+      }
+      break;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Collect bundle size metrics
+ */
+async function collectBundleSize(projectRoot) {
+  const result = { score: 100, data: null, source: null };
+
+  // Check for Next.js build output
+  const nextBuildManifest = path.join(projectRoot, '.next/build-manifest.json');
+  const bundleAnalyzer = path.join(projectRoot, '.next/analyze/client.html');
+
+  if (fs.existsSync(nextBuildManifest)) {
+    result.source = 'next-build';
+
+    try {
+      // Get total size of pages
+      const pagesDir = path.join(projectRoot, '.next/static/chunks/pages');
+      if (fs.existsSync(pagesDir)) {
+        let totalSize = 0;
+        const files = fs.readdirSync(pagesDir);
+        for (const file of files) {
+          const stat = fs.statSync(path.join(pagesDir, file));
+          totalSize += stat.size;
+        }
+
+        result.data = {
+          totalKB: Math.round(totalSize / 1024),
+          pageCount: files.length
+        };
+
+        // Score based on bundle size (smaller is better)
+        // Target: < 200KB = 100, > 1MB = 0
+        const sizeKB = result.data.totalKB;
+        if (sizeKB < 200) result.score = 100;
+        else if (sizeKB < 500) result.score = 80;
+        else if (sizeKB < 1000) result.score = 60;
+        else if (sizeKB < 2000) result.score = 40;
+        else result.score = 20;
+      }
+    } catch {
+      // Build not available
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Collect documentation coverage
+ */
+async function collectDocsCoverage(projectRoot) {
+  const result = { score: 0, data: { files: 0, documented: 0, coverage: 0 }, source: 'file-scan' };
+
+  // Check for documentation files
+  const docIndicators = {
+    readme: ['README.md', 'README.txt', 'readme.md'],
+    contributing: ['CONTRIBUTING.md', 'contributing.md'],
+    changelog: ['CHANGELOG.md', 'HISTORY.md'],
+    license: ['LICENSE', 'LICENSE.md'],
+    codeOfConduct: ['CODE_OF_CONDUCT.md'],
+    security: ['SECURITY.md'],
+    api: ['API.md', 'docs/api.md', 'docs/API.md']
+  };
+
+  let found = 0;
+  const total = Object.keys(docIndicators).length;
+  const details = {};
+
+  for (const [type, files] of Object.entries(docIndicators)) {
+    for (const file of files) {
+      if (fs.existsSync(path.join(projectRoot, file))) {
+        found++;
+        details[type] = file;
+        break;
+      }
+    }
+  }
+
+  // Check for docs folder
+  const docsDir = path.join(projectRoot, 'docs');
+  if (fs.existsSync(docsDir) && fs.statSync(docsDir).isDirectory()) {
+    const docFiles = fs.readdirSync(docsDir).filter(f => f.endsWith('.md'));
+    result.data.docFiles = docFiles.length;
+    if (docFiles.length > 5) found += 0.5;
+  }
+
+  // Check for JSDoc/TSDoc comments in code
+  const planningDir = path.join(projectRoot, 'planning');
+  if (fs.existsSync(planningDir)) {
+    const planningFiles = fs.readdirSync(planningDir).filter(f => f.endsWith('.md'));
+    result.data.planningFiles = planningFiles.length;
+    if (planningFiles.length > 0) found += 0.5;
+  }
+
+  result.data.files = total;
+  result.data.documented = found;
+  result.data.coverage = Math.round((found / total) * 100);
+  result.data.details = details;
+  result.score = result.data.coverage;
+
+  return result;
+}
+
+/**
+ * Collect code complexity metrics
+ */
+async function collectCodeComplexity(projectRoot) {
+  const result = { score: 100, data: null, source: 'file-analysis' };
+
+  // Simple complexity analysis based on file structure
+  const srcDirs = ['src', 'app', 'lib', 'components', 'pages'];
+  let totalFiles = 0;
+  let totalLines = 0;
+  let avgLinesPerFile = 0;
+
+  for (const dir of srcDirs) {
+    const dirPath = path.join(projectRoot, dir);
+    if (fs.existsSync(dirPath)) {
+      const files = getFilesRecursive(dirPath, ['.js', '.ts', '.jsx', '.tsx']);
+      totalFiles += files.length;
+
+      for (const file of files) {
+        try {
+          const content = fs.readFileSync(file, 'utf-8');
+          totalLines += content.split('\n').length;
+        } catch {
+          // Skip unreadable files
+        }
+      }
+    }
+  }
+
+  if (totalFiles > 0) {
+    avgLinesPerFile = Math.round(totalLines / totalFiles);
+
+    result.data = {
+      totalFiles,
+      totalLines,
+      avgLinesPerFile,
+      // Estimate complexity based on average file size
+      complexity: avgLinesPerFile > 300 ? 'high' :
+        avgLinesPerFile > 150 ? 'medium' : 'low'
+    };
+
+    // Score: smaller files = better
+    if (avgLinesPerFile < 100) result.score = 100;
+    else if (avgLinesPerFile < 200) result.score = 80;
+    else if (avgLinesPerFile < 300) result.score = 60;
+    else if (avgLinesPerFile < 500) result.score = 40;
+    else result.score = 20;
+  }
+
+  return result;
+}
+
+/**
+ * Collect todo completion metrics
+ */
+async function collectTodoCompletion(projectRoot) {
+  const result = { score: 0, data: null, source: null };
+
+  // Check for bootspring todos
+  const todosFile = path.join(projectRoot, '.bootspring', 'todos.json');
+  if (fs.existsSync(todosFile)) {
+    try {
+      const todos = JSON.parse(fs.readFileSync(todosFile, 'utf-8'));
+      const total = todos.length;
+      const completed = todos.filter(t => t.done).length;
+
+      result.data = { total, completed, pending: total - completed };
+      result.score = total > 0 ? Math.round((completed / total) * 100) : 100;
+      result.source = 'bootspring-todos';
+    } catch {
+      // Invalid JSON
+    }
+  }
+
+  // Also check for TODO comments in code
+  const todoCount = countTodoComments(projectRoot);
+  if (todoCount > 0) {
+    result.data = result.data || {};
+    result.data.todoComments = todoCount;
+    // Penalize for many TODO comments
+    result.score = Math.max(0, result.score - Math.min(todoCount * 2, 30));
+  }
+
+  return result;
+}
+
+/**
+ * Collect technical debt metrics
+ */
+async function collectTechnicalDebt(projectRoot) {
+  const result = { score: 100, data: { indicators: [] }, source: 'code-analysis' };
+
+  const debtIndicators = [];
+
+  // Check for TODO/FIXME/HACK comments
+  const todoCount = countTodoComments(projectRoot);
+  if (todoCount > 10) {
+    debtIndicators.push({ type: 'todo-comments', count: todoCount, severity: 'low' });
+    result.score -= Math.min(todoCount, 20);
+  }
+
+  // Check for @ts-ignore or @ts-expect-error
+  const tsIgnoreCount = countPattern(projectRoot, /@ts-(ignore|expect-error)/g);
+  if (tsIgnoreCount > 0) {
+    debtIndicators.push({ type: 'ts-ignores', count: tsIgnoreCount, severity: 'medium' });
+    result.score -= tsIgnoreCount * 3;
+  }
+
+  // Check for eslint-disable comments
+  const eslintDisableCount = countPattern(projectRoot, /eslint-disable/g);
+  if (eslintDisableCount > 5) {
+    debtIndicators.push({ type: 'eslint-disables', count: eslintDisableCount, severity: 'medium' });
+    result.score -= Math.min(eslintDisableCount * 2, 20);
+  }
+
+  // Check for console.log statements (should be removed in production)
+  const consoleCount = countPattern(projectRoot, /console\.(log|debug|info)\(/g);
+  if (consoleCount > 10) {
+    debtIndicators.push({ type: 'console-logs', count: consoleCount, severity: 'low' });
+    result.score -= Math.min(consoleCount, 15);
+  }
+
+  // Check for 'any' type usage in TypeScript
+  const anyCount = countPattern(projectRoot, /:\s*any\b/g, ['.ts', '.tsx']);
+  if (anyCount > 5) {
+    debtIndicators.push({ type: 'any-types', count: anyCount, severity: 'medium' });
+    result.score -= Math.min(anyCount * 2, 25);
+  }
+
+  result.data.indicators = debtIndicators;
+  result.data.totalIssues = debtIndicators.reduce((sum, i) => sum + i.count, 0);
+  result.score = Math.max(0, result.score);
+
+  return result;
+}
+
+/**
+ * Collect commit frequency metrics
+ */
+async function collectCommitFrequency(projectRoot) {
+  const result = { score: 0, data: null, source: 'git' };
+
+  try {
+    // Get commits from last 30 days
+    const output = execSync(
+      'git log --since="30 days ago" --oneline 2>/dev/null | wc -l',
+      { cwd: projectRoot, encoding: 'utf-8' }
+    ).trim();
+
+    const commits = parseInt(output, 10) || 0;
+    result.data = {
+      last30Days: commits,
+      avgPerDay: Math.round(commits / 30 * 10) / 10
+    };
+
+    // Score: active development = good
+    if (commits >= 60) result.score = 100; // 2+ per day
+    else if (commits >= 30) result.score = 80; // 1 per day
+    else if (commits >= 15) result.score = 60; // every 2 days
+    else if (commits >= 5) result.score = 40;
+    else result.score = 20;
+  } catch {
+    // Not a git repo
+    result.data = { error: 'Not a git repository' };
+  }
+
+  return result;
+}
+
+/**
+ * Collect README quality score
+ */
+async function collectReadmeScore(projectRoot) {
+  const result = { score: 0, data: null, source: null };
+
+  const readmePaths = ['README.md', 'readme.md', 'Readme.md'];
+  let readmePath = null;
+
+  for (const p of readmePaths) {
+    if (fs.existsSync(path.join(projectRoot, p))) {
+      readmePath = path.join(projectRoot, p);
+      break;
+    }
+  }
+
+  if (!readmePath) {
+    return { score: 0, data: { exists: false }, source: null };
+  }
+
+  const content = fs.readFileSync(readmePath, 'utf-8');
+  const lines = content.split('\n').length;
+  const words = content.split(/\s+/).length;
+
+  // Check for common README sections
+  const sections = {
+    installation: /#+\s*(install|getting started|setup)/i,
+    usage: /#+\s*(usage|how to use|examples)/i,
+    api: /#+\s*(api|reference|documentation)/i,
+    contributing: /#+\s*(contribut)/i,
+    license: /#+\s*(license)/i,
+    badges: /\[!\[/g, // Badge markdown
+    codeBlocks: /```/g
+  };
+
+  const found = {};
+  let sectionScore = 0;
+
+  for (const [section, pattern] of Object.entries(sections)) {
+    if (pattern.test(content)) {
+      found[section] = true;
+      sectionScore += 15;
+    }
+  }
+
+  // Base score on length
+  let lengthScore = 0;
+  if (words > 500) lengthScore = 20;
+  else if (words > 200) lengthScore = 15;
+  else if (words > 100) lengthScore = 10;
+  else lengthScore = 5;
+
+  result.score = Math.min(100, sectionScore + lengthScore);
+  result.data = {
+    exists: true,
+    lines,
+    words,
+    sections: found,
+    path: readmePath
+  };
+  result.source = readmePath;
+
+  return result;
+}
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+function getFilesRecursive(dir, extensions, depth = 0) {
+  if (depth > 5) return [];
+  const files = [];
+
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        files.push(...getFilesRecursive(fullPath, extensions, depth + 1));
+      } else if (entry.isFile()) {
+        const ext = path.extname(entry.name);
+        if (!extensions || extensions.includes(ext)) {
+          files.push(fullPath);
+        }
+      }
+    }
+  } catch {
+    // Permission denied
+  }
+
+  return files;
+}
+
+function countTodoComments(projectRoot) {
+  const pattern = /\b(TODO|FIXME|HACK|XXX|BUG)\b/gi;
+  return countPattern(projectRoot, pattern);
+}
+
+function countPattern(projectRoot, pattern, extensions = ['.js', '.ts', '.jsx', '.tsx']) {
+  let count = 0;
+  const srcDirs = ['src', 'app', 'lib', 'components', 'pages', 'core', 'cli'];
+
+  for (const dir of srcDirs) {
+    const dirPath = path.join(projectRoot, dir);
+    if (!fs.existsSync(dirPath)) continue;
+
+    const files = getFilesRecursive(dirPath, extensions);
+    for (const file of files) {
+      try {
+        const content = fs.readFileSync(file, 'utf-8');
+        const matches = content.match(pattern);
+        if (matches) count += matches.length;
+      } catch {
+        // Skip
+      }
+    }
+  }
+
+  return count;
+}
+
+// ============================================================================
+// Main Functions
+// ============================================================================
+
+/**
+ * Collect all metrics for a project
+ */
+async function collectAllMetrics(projectRoot, options = {}) {
+  const results = {
+    timestamp: new Date().toISOString(),
+    metrics: {},
+    categories: {},
+    overallScore: 0
+  };
+
+  const collectors = {
+    testCoverage: collectTestCoverage,
+    bundleSize: collectBundleSize,
+    docsCoverage: collectDocsCoverage,
+    codeComplexity: collectCodeComplexity,
+    todoCompletion: collectTodoCompletion,
+    technicalDebt: collectTechnicalDebt,
+    commitFrequency: collectCommitFrequency,
+    readmeScore: collectReadmeScore
+  };
+
+  // Run collectors
+  for (const [metricId, collector] of Object.entries(collectors)) {
+    if (options.skip && options.skip.includes(metricId)) continue;
+
+    try {
+      results.metrics[metricId] = await collector(projectRoot);
+    } catch (error) {
+      results.metrics[metricId] = { score: 0, error: error.message };
+    }
+  }
+
+  // Add checkpoint progress from project state
+  const state = projectState.loadState(projectRoot);
+  if (state) {
+    const progress = projectState.getCheckpointProgress(projectRoot);
+    results.metrics.checkpoints = {
+      score: progress.percentage,
+      data: progress
+    };
+
+    // Add security if available
+    if (state.security?.score !== undefined) {
+      results.metrics.security = {
+        score: state.security.score,
+        data: state.security.summary
+      };
+    }
+  }
+
+  // Calculate category scores
+  const categories = {};
+  for (const [metricId, metric] of Object.entries(results.metrics)) {
+    const definition = METRICS[metricId];
+    if (!definition) continue;
+
+    const category = definition.category;
+    if (!categories[category]) {
+      categories[category] = { total: 0, count: 0, metrics: [] };
+    }
+
+    categories[category].total += metric.score;
+    categories[category].count++;
+    categories[category].metrics.push({
+      id: metricId,
+      label: definition.label,
+      score: metric.score,
+      icon: definition.icon
+    });
+  }
+
+  // Calculate category averages
+  for (const [category, data] of Object.entries(categories)) {
+    data.average = data.count > 0 ? Math.round(data.total / data.count) : 0;
+  }
+  results.categories = categories;
+
+  // Calculate overall score (weighted average)
+  let totalWeight = 0;
+  let weightedScore = 0;
+
+  for (const [metricId, metric] of Object.entries(results.metrics)) {
+    const definition = METRICS[metricId];
+    if (!definition) continue;
+
+    totalWeight += definition.weight;
+    weightedScore += metric.score * definition.weight;
+  }
+
+  results.overallScore = totalWeight > 0
+    ? Math.round(weightedScore / totalWeight)
+    : 0;
+
+  return results;
+}
+
+/**
+ * Store metrics in project state
+ */
+function storeMetrics(projectRoot, metrics) {
+  const state = projectState.getOrCreateState(projectRoot);
+
+  state.metrics = {
+    lastCollected: metrics.timestamp,
+    overallScore: metrics.overallScore,
+    categories: Object.fromEntries(
+      Object.entries(metrics.categories).map(([cat, data]) => [
+        cat,
+        { score: data.average, count: data.count }
+      ])
+    ),
+    scores: Object.fromEntries(
+      Object.entries(metrics.metrics).map(([id, m]) => [id, m.score])
+    ),
+    history: [
+      { score: metrics.overallScore, date: metrics.timestamp },
+      ...(state.metrics?.history || []).slice(0, 29) // Keep last 30
+    ]
+  };
+
+  projectState.saveState(projectRoot, state);
+
+  return state.metrics;
+}
+
+/**
+ * Get metric trend
+ */
+function getMetricTrend(projectRoot, metricId) {
+  const state = projectState.loadState(projectRoot);
+  if (!state?.metrics?.history) return null;
+
+  const history = state.metrics.history;
+  if (history.length < 2) return 'stable';
+
+  const current = history[0].score;
+  const previous = history[1].score;
+  const diff = current - previous;
+
+  if (diff > 5) return 'up';
+  if (diff < -5) return 'down';
+  return 'stable';
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+module.exports = {
+  METRICS,
+  collectAllMetrics,
+  storeMetrics,
+  getMetricTrend,
+  // Individual collectors
+  collectTestCoverage,
+  collectBundleSize,
+  collectDocsCoverage,
+  collectCodeComplexity,
+  collectTodoCompletion,
+  collectTechnicalDebt,
+  collectCommitFrequency,
+  collectReadmeScore
+};