memorylink 1.0.0

package/src/commands/stats.ts

@@ -0,0 +1,591 @@
+/**
+ * MemoryLink - Stats Command (v1.5 Phase 2)
+ * Enhanced observability: statistics and analytics from observability.log
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import {
+  findRoot,
+  isInitialized,
+  getFilePath,
+  success,
+  error,
+  warn,
+  info,
+  log,
+  readJsonlEntries,
+} from '../utils.js';
+import { MEMORYLINK_DIR } from '../types.js';
+import type { GlobalOptions } from '../types.js';
+
+export interface StatsOptions extends GlobalOptions {
+  since?: string;       // Duration like "7d", "2w", "1m"
+  format?: 'default' | 'json' | 'csv' | 'markdown';
+  noRecommendations?: boolean;  // v1.5.1: Skip recommendations in output
+}
+
+interface ObservabilityEntry {
+  timestamp: string;
+  runType: 'preflight' | 'postflight';
+  status: 'GREEN' | 'YELLOW' | 'RED';
+  recordsUsed?: number;
+  trust?: {
+    high?: number;
+    medium?: number;
+    low?: number;
+  };
+  issues?: Array<{
+    type: string;
+    severity: string;
+  }>;
+  durationMs?: number;
+  override?: boolean;
+}
+
+interface StatsSummary {
+  totalRuns: number;
+  preflightRuns: number;
+  postflightRuns: number;
+  statusCounts: {
+    GREEN: number;
+    YELLOW: number;
+    RED: number;
+  };
+  averageRecords: number;
+  averageDuration: number;
+  trustLevels: {
+    high: number;
+    medium: number;
+    low: number;
+  };
+  issueTypes: Record<string, number>;
+  overrideCount: number;
+  timeRange: {
+    start: string;
+    end: string;
+  };
+  // v1.5 Priority 2: Schema versioning
+  schemaVersion?: string;
+  period?: {
+    start: string;
+    end: string;
+  };
+}
+
+/**
+ * Parse duration string to milliseconds
+ */
+function parseDuration(duration: string): number {
+  const match = duration.match(/^(\d+)([dwmyh])$/);
+  if (!match) return 0;
+  
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+  
+  const multipliers: Record<string, number> = {
+    h: 60 * 60 * 1000,
+    d: 24 * 60 * 60 * 1000,
+    w: 7 * 24 * 60 * 60 * 1000,
+    m: 30 * 24 * 60 * 60 * 1000,
+    y: 365 * 24 * 60 * 60 * 1000,
+  };
+  
+  return value * (multipliers[unit] || 0);
+}
+
+/**
+ * Filter entries by time
+ */
+function filterBySince(entries: ObservabilityEntry[], since: string): ObservabilityEntry[] {
+  const cutoff = Date.now() - parseDuration(since);
+  return entries.filter(e => new Date(e.timestamp).getTime() >= cutoff);
+}
+
+/**
+ * Calculate statistics
+ */
+function calculateStats(entries: ObservabilityEntry[]): StatsSummary {
+  if (entries.length === 0) {
+    return {
+      totalRuns: 0,
+      preflightRuns: 0,
+      postflightRuns: 0,
+      statusCounts: { GREEN: 0, YELLOW: 0, RED: 0 },
+      averageRecords: 0,
+      averageDuration: 0,
+      trustLevels: { high: 0, medium: 0, low: 0 },
+      issueTypes: {},
+      overrideCount: 0,
+      timeRange: { start: '', end: '' },
+    };
+  }
+
+  const timestamps = entries.map(e => new Date(e.timestamp).getTime()).sort((a, b) => a - b);
+  
+  const preflightRuns = entries.filter(e => e.runType === 'preflight').length;
+  const postflightRuns = entries.filter(e => e.runType === 'postflight').length;
+  
+  const statusCounts = {
+    GREEN: entries.filter(e => e.status === 'GREEN').length,
+    YELLOW: entries.filter(e => e.status === 'YELLOW').length,
+    RED: entries.filter(e => e.status === 'RED').length,
+  };
+
+  const records = entries.filter(e => e.recordsUsed !== undefined).map(e => e.recordsUsed!);
+  const averageRecords = records.length > 0 
+    ? Math.round(records.reduce((a, b) => a + b, 0) / records.length)
+    : 0;
+
+  const durations = entries.filter(e => e.durationMs !== undefined).map(e => e.durationMs!);
+  const averageDuration = durations.length > 0
+    ? Math.round(durations.reduce((a, b) => a + b, 0) / durations.length)
+    : 0;
+
+  const trustLevels = {
+    high: entries.reduce((sum, e) => sum + (e.trust?.high || 0), 0),
+    medium: entries.reduce((sum, e) => sum + (e.trust?.medium || 0), 0),
+    low: entries.reduce((sum, e) => sum + (e.trust?.low || 0), 0),
+  };
+
+  const issueTypes: Record<string, number> = {};
+  entries.forEach(e => {
+    if (e.issues) {
+      e.issues.forEach(issue => {
+        issueTypes[issue.type] = (issueTypes[issue.type] || 0) + 1;
+      });
+    }
+  });
+
+  const overrideCount = entries.filter(e => e.override === true).length;
+
+  return {
+    totalRuns: entries.length,
+    preflightRuns,
+    postflightRuns,
+    statusCounts,
+    averageRecords,
+    averageDuration,
+    trustLevels,
+    issueTypes,
+    overrideCount,
+    timeRange: {
+      start: new Date(timestamps[0]).toISOString(),
+      end: new Date(timestamps[timestamps.length - 1]).toISOString(),
+    },
+    // v1.5 Priority 2: Schema versioning
+    schemaVersion: '1.5.0',
+    period: {
+      start: new Date(timestamps[0]).toISOString(),
+      end: new Date(timestamps[timestamps.length - 1]).toISOString(),
+    },
+  };
+}
+
+/**
+ * Generate recommendations based on stats (v1.5 Priority 2)
+ */
+function generateRecommendations(stats: StatsSummary): string[] {
+  const recommendations: string[] = [];
+  
+  // Short-circuit if no data to avoid divide-by-zero
+  if (stats.totalRuns === 0) {
+    return recommendations;
+  }
+  
+  const redPercentage = (stats.statusCounts.RED / stats.totalRuns) * 100;
+  const yellowPercentage = (stats.statusCounts.YELLOW / stats.totalRuns) * 100;
+  const overridePercentage = (stats.overrideCount / stats.totalRuns) * 100;
+  
+  // High RED rate
+  if (redPercentage > 10) {
+    recommendations.push(`High RED rate (${redPercentage.toFixed(1)}%): Consider tightening secret policies or training agents on best practices.`);
+  }
+  
+  // High override rate
+  if (overridePercentage > 20) {
+    recommendations.push(`High override rate (${overridePercentage.toFixed(1)}%): Review Buddy-Check thresholds - they may be too strict for your workflow.`);
+  }
+  
+  // High YELLOW rate
+  if (yellowPercentage > 30) {
+    recommendations.push(`High YELLOW rate (${yellowPercentage.toFixed(1)}%): Many warnings detected - consider addressing common issues proactively.`);
+  }
+  
+  // Low trust levels
+  const totalTrust = stats.trustLevels.high + stats.trustLevels.medium + stats.trustLevels.low;
+  if (totalTrust > 0) {
+    const lowTrustPercentage = (stats.trustLevels.low / totalTrust) * 100;
+    if (lowTrustPercentage > 50) {
+      recommendations.push(`High proportion of low-trust records (${lowTrustPercentage.toFixed(1)}%): Review and verify memory entries to improve trust levels.`);
+    }
+  }
+  
+  // Most common issue
+  if (Object.keys(stats.issueTypes).length > 0) {
+    const topIssue = Object.entries(stats.issueTypes)
+      .sort((a, b) => b[1] - a[1])[0];
+    if (topIssue[1] > stats.totalRuns * 0.3) {
+      recommendations.push(`Frequent issue: "${topIssue[0]}" appears in ${((topIssue[1] / stats.totalRuns) * 100).toFixed(1)}% of runs - consider addressing this systematically.`);
+    }
+  }
+  
+  return recommendations;
+}
+
+/**
+ * Format stats as default (human-readable)
+ */
+function formatStatsDefault(stats: StatsSummary, noRecommendations: boolean = false): string {
+  let output = '';
+  
+  output += '\n';
+  output += '═══════════════════════════════════════════════════════════════\n';
+  output += '                    MEMORYLINK STATISTICS\n';
+  output += '═══════════════════════════════════════════════════════════════\n';
+  output += '\n';
+  
+  if (stats.totalRuns === 0) {
+    output += 'No observability data found.\n';
+    output += 'Run Buddy-Check commands (preflight/postflight) to generate data.\n';
+    output += '\n';
+    return output;
+  }
+  
+  output += `📊 Overview:\n`;
+  output += `   Total Runs: ${stats.totalRuns}\n`;
+  output += `   Preflight: ${stats.preflightRuns}\n`;
+  output += `   Postflight: ${stats.postflightRuns}\n`;
+  output += '\n';
+  
+  output += `🎯 Status Distribution:\n`;
+  output += `   GREEN:  ${stats.statusCounts.GREEN} (${Math.round(stats.statusCounts.GREEN / stats.totalRuns * 100)}%)\n`;
+  output += `   YELLOW: ${stats.statusCounts.YELLOW} (${Math.round(stats.statusCounts.YELLOW / stats.totalRuns * 100)}%)\n`;
+  output += `   RED:    ${stats.statusCounts.RED} (${Math.round(stats.statusCounts.RED / stats.totalRuns * 100)}%)\n`;
+  output += '\n';
+  
+  if (stats.averageRecords > 0) {
+    output += `📈 Performance:\n`;
+    output += `   Average Records: ${stats.averageRecords}\n`;
+    output += `   Average Duration: ${stats.averageDuration}ms\n`;
+    output += '\n';
+  }
+  
+  output += `🔒 Trust Levels:\n`;
+  output += `   High:   ${stats.trustLevels.high}\n`;
+  output += `   Medium: ${stats.trustLevels.medium}\n`;
+  output += `   Low:    ${stats.trustLevels.low}\n`;
+  output += '\n';
+  
+  if (Object.keys(stats.issueTypes).length > 0) {
+    output += `⚠️  Issue Types:\n`;
+    const sortedIssues = Object.entries(stats.issueTypes)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 10);
+    for (const [type, count] of sortedIssues) {
+      output += `   ${type}: ${count}\n`;
+    }
+    output += '\n';
+  }
+  
+  if (stats.overrideCount > 0) {
+    output += `🔓 Overrides: ${stats.overrideCount}\n`;
+    output += '\n';
+  }
+  
+  output += `📅 Time Range:\n`;
+  output += `   Start: ${new Date(stats.timeRange.start).toLocaleString()}\n`;
+  output += `   End:   ${new Date(stats.timeRange.end).toLocaleString()}\n`;
+  output += '\n';
+  
+  // v1.5 Priority 2: Recommendations (unless disabled)
+  if (!noRecommendations) {
+    const recommendations = generateRecommendations(stats);
+    if (recommendations.length > 0) {
+      output += `💡 Recommendations:\n`;
+      for (const rec of recommendations) {
+        output += `   • ${rec}\n`;
+      }
+      output += '\n';
+    }
+  }
+  
+  return output;
+}
+
+/**
+ * Format stats as JSON
+ */
+function formatStatsJSON(stats: StatsSummary, noRecommendations: boolean = false): string {
+  // v1.5 Priority 2: Include recommendations in JSON (unless disabled)
+  const output: any = { ...stats };
+  if (!noRecommendations) {
+    const recommendations = generateRecommendations(stats);
+    if (recommendations.length > 0) {
+      output.recommendations = recommendations;
+    }
+  }
+  return JSON.stringify(output, null, 2);
+}
+
+/**
+ * Format stats as CSV
+ */
+function formatStatsCSV(stats: StatsSummary): string {
+  let csv = 'Metric,Value\n';
+  csv += `Total Runs,${stats.totalRuns}\n`;
+  csv += `Preflight Runs,${stats.preflightRuns}\n`;
+  csv += `Postflight Runs,${stats.postflightRuns}\n`;
+  csv += `GREEN Status,${stats.statusCounts.GREEN}\n`;
+  csv += `YELLOW Status,${stats.statusCounts.YELLOW}\n`;
+  csv += `RED Status,${stats.statusCounts.RED}\n`;
+  csv += `Average Records,${stats.averageRecords}\n`;
+  csv += `Average Duration (ms),${stats.averageDuration}\n`;
+  csv += `High Trust,${stats.trustLevels.high}\n`;
+  csv += `Medium Trust,${stats.trustLevels.medium}\n`;
+  csv += `Low Trust,${stats.trustLevels.low}\n`;
+  csv += `Overrides,${stats.overrideCount}\n`;
+  
+  for (const [type, count] of Object.entries(stats.issueTypes)) {
+    csv += `Issue: ${type},${count}\n`;
+  }
+  
+  return csv;
+}
+
+/**
+ * Format stats as Markdown
+ */
+function formatStatsMarkdown(stats: StatsSummary): string {
+  let md = '# MemoryLink Statistics\n\n';
+  
+  if (stats.totalRuns === 0) {
+    md += 'No observability data found.\n';
+    return md;
+  }
+  
+  md += '## Overview\n\n';
+  md += `- **Total Runs**: ${stats.totalRuns}\n`;
+  md += `- **Preflight**: ${stats.preflightRuns}\n`;
+  md += `- **Postflight**: ${stats.postflightRuns}\n\n`;
+  
+  md += '## Status Distribution\n\n';
+  md += '| Status | Count | Percentage |\n';
+  md += '|--------|-------|------------|\n';
+  md += `| GREEN | ${stats.statusCounts.GREEN} | ${Math.round(stats.statusCounts.GREEN / stats.totalRuns * 100)}% |\n`;
+  md += `| YELLOW | ${stats.statusCounts.YELLOW} | ${Math.round(stats.statusCounts.YELLOW / stats.totalRuns * 100)}% |\n`;
+  md += `| RED | ${stats.statusCounts.RED} | ${Math.round(stats.statusCounts.RED / stats.totalRuns * 100)}% |\n\n`;
+  
+  if (stats.averageRecords > 0) {
+    md += '## Performance\n\n';
+    md += `- **Average Records**: ${stats.averageRecords}\n`;
+    md += `- **Average Duration**: ${stats.averageDuration}ms\n\n`;
+  }
+  
+  md += '## Trust Levels\n\n';
+  md += `- **High**: ${stats.trustLevels.high}\n`;
+  md += `- **Medium**: ${stats.trustLevels.medium}\n`;
+  md += `- **Low**: ${stats.trustLevels.low}\n\n`;
+  
+  if (Object.keys(stats.issueTypes).length > 0) {
+    md += '## Issue Types\n\n';
+    md += '| Type | Count |\n';
+    md += '|------|-------|\n';
+    const sortedIssues = Object.entries(stats.issueTypes)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 10);
+    for (const [type, count] of sortedIssues) {
+      md += `| ${type} | ${count} |\n`;
+    }
+    md += '\n';
+  }
+  
+  if (stats.overrideCount > 0) {
+    md += `## Overrides\n\n`;
+    md += `Total overrides: ${stats.overrideCount}\n\n`;
+  }
+  
+  md += '## Time Range\n\n';
+  md += `- **Start**: ${new Date(stats.timeRange.start).toLocaleString()}\n`;
+  md += `- **End**: ${new Date(stats.timeRange.end).toLocaleString()}\n\n`;
+  
+  // v1.5 Priority 2: Recommendations (unless disabled)
+  // Note: Markdown formatter doesn't receive noRecommendations flag,
+  // but we'll handle it in the command function
+  return md;
+}
+
+/**
+ * Stats command
+ */
+export async function statsCommand(
+  options: StatsOptions = {}
+): Promise<void> {
+  const { verbose, since, format = 'default', noRecommendations = false } = options;
+
+  // v1.6: Record telemetry event (command start) - OPTIONAL TEST PATH
+  // Only records if telemetry is enabled in config
+  // This is a test integration - can be expanded to other commands later
+  let telemetryRecorded = false;
+  try {
+    const { recordEvent, checkIsGitRepo, checkHasConfig, isTelemetryEnabled } = await import('../telemetry.js');
+    if (isTelemetryEnabled()) {
+      const flags: Record<string, boolean | string | number> = { format, noRecommendations };
+      if (since) {
+        flags.since = since;
+      }
+      await recordEvent({
+        command: 'stats',
+        result: 'success', // Will be updated to 'error' if command fails
+        flags,
+        isGitRepo: checkIsGitRepo(),
+        hasConfig: checkHasConfig(),
+      });
+      telemetryRecorded = true;
+    }
+  } catch {
+    // Silently fail - telemetry must never break the CLI
+  }
+
+  log('Generating statistics', verbose);
+
+  const root = findRoot();
+  if (!root || !isInitialized(root)) {
+    // v1.6: Record telemetry event (command error) - if telemetry was enabled
+    if (telemetryRecorded) {
+      try {
+        const { recordEvent, checkIsGitRepo, checkHasConfig } = await import('../telemetry.js');
+        await recordEvent({
+          command: 'stats',
+          result: 'error',
+          exitCode: 1,
+          errorKind: 'NOT_INITIALIZED',
+          isGitRepo: checkIsGitRepo(),
+          hasConfig: checkHasConfig(),
+        });
+      } catch {
+        // Silently fail - telemetry must never break the CLI
+      }
+    }
+    error('MemoryLink is not initialized. Run: memorylink init');
+    process.exit(1);
+  }
+
+  const observabilityPath = path.join(root, MEMORYLINK_DIR, 'observability.log');
+
+  if (!fs.existsSync(observabilityPath)) {
+    warn('Observability log not found. Run Buddy-Check commands to generate data.');
+    if (format === 'json') {
+      console.log(JSON.stringify({ totalRuns: 0, message: 'No data available' }, null, 2));
+    } else {
+      console.log('\nNo observability data found.');
+      console.log('Run Buddy-Check commands (preflight/postflight) to generate data.\n');
+    }
+    return;
+  }
+
+  // Read observability entries
+  let entries: ObservabilityEntry[];
+  try {
+    entries = readJsonlEntries<ObservabilityEntry>(observabilityPath);
+  } catch (err) {
+    // v1.6: Record telemetry event (command error) - if telemetry was enabled
+    if (telemetryRecorded) {
+      try {
+        const { recordEvent, checkIsGitRepo, checkHasConfig, getErrorKind } = await import('../telemetry.js');
+        const flags: Record<string, boolean | string | number> = { format, noRecommendations };
+        if (since) {
+          flags.since = since;
+        }
+        await recordEvent({
+          command: 'stats',
+          result: 'error',
+          exitCode: 1,
+          errorKind: getErrorKind(err),
+          flags,
+          isGitRepo: checkIsGitRepo(),
+          hasConfig: checkHasConfig(),
+        });
+      } catch {
+        // Silently fail - telemetry must never break the CLI
+      }
+    }
+    error(`Failed to read observability log: ${err instanceof Error ? err.message : 'Unknown error'}`);
+    process.exit(1);
+  }
+
+  // Filter by time if specified
+  let effectiveStart: string | undefined;
+  if (since) {
+    const cutoff = Date.now() - parseDuration(since);
+    effectiveStart = new Date(cutoff).toISOString();
+    entries = filterBySince(entries, since);
+    if (verbose) {
+      info(`Filtered to entries since ${since}`);
+    }
+  }
+
+  // Calculate statistics
+  const stats = calculateStats(entries);
+  
+  // v1.5 Priority 2: If --since was used, update period.start to reflect effective filter
+  if (since && effectiveStart && stats.period) {
+    stats.period.start = effectiveStart;
+  }
+
+  // Format and output
+  let output: string;
+  switch (format) {
+    case 'json':
+      output = formatStatsJSON(stats, noRecommendations);
+      break;
+    case 'csv':
+      output = formatStatsCSV(stats);
+      break;
+    case 'markdown':
+      let md = formatStatsMarkdown(stats);
+      // Add recommendations to markdown if not disabled
+      if (!noRecommendations) {
+        const recommendations = generateRecommendations(stats);
+        if (recommendations.length > 0) {
+          md += '## Recommendations\n\n';
+          for (const rec of recommendations) {
+            md += `- ${rec}\n`;
+          }
+          md += '\n';
+        }
+      }
+      output = md;
+      break;
+    default:
+      output = formatStatsDefault(stats, noRecommendations);
+  }
+
+  console.log(output);
+
+  if (format === 'default' && stats.totalRuns > 0) {
+    success(`Statistics generated for ${stats.totalRuns} runs`);
+  }
+
+  // v1.6: Record telemetry event (command success) - if telemetry was enabled
+  if (telemetryRecorded) {
+    try {
+      const { recordEvent, checkIsGitRepo, checkHasConfig } = await import('../telemetry.js');
+      const flags: Record<string, boolean | string | number> = { format, noRecommendations };
+      if (since) {
+        flags.since = since;
+      }
+      await recordEvent({
+        command: 'stats',
+        result: 'success',
+        exitCode: 0,
+        flags,
+        isGitRepo: checkIsGitRepo(),
+        hasConfig: checkHasConfig(),
+      });
+    } catch {
+      // Silently fail - telemetry must never break the CLI
+    }
+  }
+}
+