@girardmedia/bootspring 2.0.21 → 2.0.23

package/src/core/metrics-engine.ts

@@ -0,0 +1,886 @@
+/**
+ * Bootspring Metrics Engine
+ * Comprehensive project metrics tracking and scoring
+ *
+ * @package bootspring
+ * @module core/metrics-engine
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import * as projectState from './project-state';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type MetricCategory = 'progress' | 'quality' | 'docs' | 'performance' | 'activity';
+export type ComplexityLevel = 'low' | 'medium' | 'high';
+export type TrendDirection = 'up' | 'down' | 'stable';
+
+export interface MetricDefinition {
+  label: string;
+  category: MetricCategory;
+  weight: number;
+  icon: string;
+  invert?: boolean | undefined; // Lower is better
+}
+
+export interface MetricResult {
+  score: number;
+  data?: unknown | undefined;
+  source?: string | null | undefined;
+  error?: string | undefined;
+}
+
+export interface CoverageData {
+  lines?: number | undefined;
+  statements?: number | undefined;
+  functions?: number | undefined;
+  branches?: number | undefined;
+}
+
+export interface BundleSizeData {
+  totalKB: number;
+  pageCount: number;
+}
+
+export interface DocsCoverageData {
+  files: number;
+  documented: number;
+  coverage: number;
+  details?: Record<string, string> | undefined;
+  docFiles?: number | undefined;
+  planningFiles?: number | undefined;
+}
+
+export interface CodeComplexityData {
+  totalFiles: number;
+  totalLines: number;
+  avgLinesPerFile: number;
+  complexity: ComplexityLevel;
+}
+
+export interface TodoCompletionData {
+  total: number;
+  completed: number;
+  pending: number;
+  todoComments?: number | undefined;
+}
+
+export interface DebtIndicator {
+  type: string;
+  count: number;
+  severity: 'low' | 'medium' | 'high';
+}
+
+export interface TechnicalDebtData {
+  indicators: DebtIndicator[];
+  totalIssues: number;
+}
+
+export interface CommitFrequencyData {
+  last30Days: number;
+  avgPerDay: number;
+  error?: string | undefined;
+}
+
+export interface ReadmeScoreData {
+  exists: boolean;
+  lines?: number | undefined;
+  words?: number | undefined;
+  sections?: Record<string, boolean> | undefined;
+  path?: string | undefined;
+}
+
+export interface CategoryData {
+  total: number;
+  count: number;
+  average?: number | undefined;
+  metrics: CategoryMetricSummary[];
+}
+
+export interface CategoryMetricSummary {
+  id: string;
+  label: string;
+  score: number;
+  icon: string;
+}
+
+export interface MetricsResults {
+  timestamp: string;
+  metrics: Record<string, MetricResult>;
+  categories: Record<string, CategoryData>;
+  overallScore: number;
+}
+
+export interface StoredMetrics {
+  lastCollected: string;
+  overallScore: number;
+  categories: Record<string, { score: number; count: number }>;
+  scores: Record<string, number>;
+  history: Array<{ score: number; date: string }>;
+}
+
+export interface CollectOptions {
+  skip?: string[] | undefined;
+}
+
+// ============================================================================
+// Metric Definitions
+// ============================================================================
+
+export const METRICS: Record<string, MetricDefinition> = {
+  // 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: '💳'
+  }
+};
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+function getFilesRecursive(dir: string, extensions?: string[], depth: number = 0): string[] {
+  if (depth > 5) return [];
+  const files: string[] = [];
+
+  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: string): number {
+  const pattern = /\b(TODO|FIXME|HACK|XXX|BUG)\b/gi;
+  return countPattern(projectRoot, pattern);
+}
+
+function countPattern(projectRoot: string, pattern: RegExp, extensions: string[] = ['.js', '.ts', '.jsx', '.tsx']): number {
+  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;
+}
+
+// ============================================================================
+// Metric Collectors
+// ============================================================================
+
+/**
+ * Collect test coverage metrics
+ */
+export async function collectTestCoverage(projectRoot: string): Promise<MetricResult> {
+  const result: MetricResult = { 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')) as {
+            total?: {
+              lines?: { pct?: number };
+              statements?: { pct?: number };
+              functions?: { pct?: number };
+              branches?: { pct?: number };
+            }
+          };
+          if (coverage.total) {
+            const { lines, statements, functions, branches } = coverage.total;
+            const data: CoverageData = {
+              lines: lines?.pct || 0,
+              statements: statements?.pct || 0,
+              functions: functions?.pct || 0,
+              branches: branches?.pct || 0
+            };
+            result.data = data;
+            result.score = Math.round(
+              ((data.lines ?? 0) + (data.statements ?? 0) +
+               (data.functions ?? 0) + (data.branches ?? 0)) / 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 && match[1]) {
+            result.score = Math.round(parseFloat(match[1]));
+            result.data = { lines: result.score };
+          }
+        } catch {
+          // Parse error
+        }
+      }
+      break;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Collect bundle size metrics
+ */
+export async function collectBundleSize(projectRoot: string): Promise<MetricResult> {
+  const result: MetricResult = { score: 100, data: null, source: null };
+
+  // Check for Next.js build output
+  const nextBuildManifest = path.join(projectRoot, '.next/build-manifest.json');
+
+  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;
+        }
+
+        const data: BundleSizeData = {
+          totalKB: Math.round(totalSize / 1024),
+          pageCount: files.length
+        };
+        result.data = data;
+
+        // Score based on bundle size (smaller is better)
+        // Target: < 200KB = 100, > 1MB = 0
+        const sizeKB = 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
+ */
+export async function collectDocsCoverage(projectRoot: string): Promise<MetricResult> {
+  const data: DocsCoverageData = { files: 0, documented: 0, coverage: 0 };
+  const result: MetricResult = { score: 0, data, source: 'file-scan' };
+
+  // Check for documentation files
+  const docIndicators: Record<string, string[]> = {
+    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: Record<string, string> = {};
+
+  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'));
+    data.docFiles = docFiles.length;
+    if (docFiles.length > 5) found += 0.5;
+  }
+
+  // Check for planning folder
+  const planningDir = path.join(projectRoot, 'planning');
+  if (fs.existsSync(planningDir)) {
+    const planningFiles = fs.readdirSync(planningDir).filter(f => f.endsWith('.md'));
+    data.planningFiles = planningFiles.length;
+    if (planningFiles.length > 0) found += 0.5;
+  }
+
+  data.files = total;
+  data.documented = found;
+  data.coverage = Math.round((found / total) * 100);
+  data.details = details;
+  result.score = data.coverage;
+
+  return result;
+}
+
+/**
+ * Collect code complexity metrics
+ */
+export async function collectCodeComplexity(projectRoot: string): Promise<MetricResult> {
+  const result: MetricResult = { 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;
+
+  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) {
+    const avgLinesPerFile = Math.round(totalLines / totalFiles);
+
+    const data: CodeComplexityData = {
+      totalFiles,
+      totalLines,
+      avgLinesPerFile,
+      // Estimate complexity based on average file size
+      complexity: avgLinesPerFile > 300 ? 'high' :
+        avgLinesPerFile > 150 ? 'medium' : 'low'
+    };
+    result.data = data;
+
+    // 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
+ */
+export async function collectTodoCompletion(projectRoot: string): Promise<MetricResult> {
+  const result: MetricResult = { 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')) as Array<{ done: boolean }>;
+      const total = todos.length;
+      const completed = todos.filter(t => t.done).length;
+
+      const data: TodoCompletionData = { total, completed, pending: total - completed };
+      result.data = data;
+      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) {
+    const data = (result.data || {}) as TodoCompletionData;
+    data.todoComments = todoCount;
+    result.data = data;
+    // Penalize for many TODO comments
+    result.score = Math.max(0, result.score - Math.min(todoCount * 2, 30));
+  }
+
+  return result;
+}
+
+/**
+ * Collect technical debt metrics
+ */
+export async function collectTechnicalDebt(projectRoot: string): Promise<MetricResult> {
+  const data: TechnicalDebtData = { indicators: [], totalIssues: 0 };
+  const result: MetricResult = { score: 100, data, source: 'code-analysis' };
+
+  const debtIndicators: DebtIndicator[] = [];
+
+  // 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);
+  }
+
+  data.indicators = debtIndicators;
+  data.totalIssues = debtIndicators.reduce((sum, i) => sum + i.count, 0);
+  result.score = Math.max(0, result.score);
+
+  return result;
+}
+
+/**
+ * Collect commit frequency metrics
+ */
+export async function collectCommitFrequency(projectRoot: string): Promise<MetricResult> {
+  const result: MetricResult = { 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;
+    const data: CommitFrequencyData = {
+      last30Days: commits,
+      avgPerDay: Math.round(commits / 30 * 10) / 10
+    };
+    result.data = data;
+
+    // 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
+ */
+export async function collectReadmeScore(projectRoot: string): Promise<MetricResult> {
+  const result: MetricResult = { score: 0, data: null, source: null };
+
+  const readmePaths = ['README.md', 'readme.md', 'Readme.md'];
+  let readmePath: string | null = 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: Record<string, RegExp> = {
+    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: Record<string, boolean> = {};
+  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);
+  const data: ReadmeScoreData = {
+    exists: true,
+    lines,
+    words,
+    sections: found,
+    path: readmePath
+  };
+  result.data = data;
+  result.source = readmePath;
+
+  return result;
+}
+
+// ============================================================================
+// Main Functions
+// ============================================================================
+
+/**
+ * Collect all metrics for a project
+ */
+export async function collectAllMetrics(projectRoot: string, options: CollectOptions = {}): Promise<MetricsResults> {
+  const results: MetricsResults = {
+    timestamp: new Date().toISOString(),
+    metrics: {},
+    categories: {},
+    overallScore: 0
+  };
+
+  const collectors: Record<string, (root: string) => Promise<MetricResult>> = {
+    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) {
+      const err = error as Error;
+      results.metrics[metricId] = { score: 0, error: err.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
+    const securityState = state as { security?: { score?: number; summary?: unknown } };
+    if (securityState.security?.score !== undefined) {
+      results.metrics['security'] = {
+        score: securityState.security.score,
+        data: securityState.security.summary
+      };
+    }
+  }
+
+  // Calculate category scores
+  const categories: Record<string, CategoryData> = {};
+  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: [] };
+    }
+
+    const categoryData = categories[category];
+    if (categoryData) {
+      categoryData.total += metric.score;
+      categoryData.count++;
+      categoryData.metrics.push({
+        id: metricId,
+        label: definition.label,
+        score: metric.score,
+        icon: definition.icon
+      });
+    }
+  }
+
+  // Calculate category averages
+  for (const [, 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
+ */
+export function storeMetrics(projectRoot: string, metrics: MetricsResults): StoredMetrics {
+  const state = projectState.getOrCreateState(projectRoot);
+
+  const storedMetrics: StoredMetrics = {
+    lastCollected: metrics.timestamp,
+    overallScore: metrics.overallScore,
+    categories: Object.fromEntries(
+      Object.entries(metrics.categories).map(([cat, data]) => [
+        cat,
+        { score: data.average ?? 0, count: data.count }
+      ])
+    ),
+    scores: Object.fromEntries(
+      Object.entries(metrics.metrics).map(([id, m]) => [id, m.score])
+    ),
+    history: [
+      { score: metrics.overallScore, date: metrics.timestamp },
+      ...((state as { metrics?: { history?: Array<{ score: number; date: string }> } }).metrics?.history || []).slice(0, 29) // Keep last 30
+    ]
+  };
+
+  // Update state with metrics
+  (state as { metrics?: StoredMetrics }).metrics = storedMetrics;
+  projectState.saveState(projectRoot, state);
+
+  return storedMetrics;
+}
+
+/**
+ * Get metric trend
+ */
+export function getMetricTrend(projectRoot: string, _metricId: string): TrendDirection | null {
+  const state = projectState.loadState(projectRoot);
+  const stateWithMetrics = state as { metrics?: { history?: Array<{ score: number; date: string }> } } | null;
+  if (!stateWithMetrics?.metrics?.history) return null;
+
+  const history = stateWithMetrics.metrics.history;
+  if (history.length < 2) return 'stable';
+
+  const current = history[0]?.score ?? 0;
+  const previous = history[1]?.score ?? 0;
+  const diff = current - previous;
+
+  if (diff > 5) return 'up';
+  if (diff < -5) return 'down';
+  return 'stable';
+}