@iservu-inc/adf-cli 0.9.1 → 0.11.0

package/lib/learning/analytics.js

@@ -0,0 +1,681 @@
+const storage = require('./storage');
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * Learning Analytics Module
+ *
+ * Provides comprehensive analytics for the learning system including:
+ * - Overview statistics
+ * - Skip trends over time
+ * - Category preferences
+ * - Pattern confidence distribution
+ * - Learning effectiveness metrics
+ * - Pattern decay status
+ * - Session timeline analysis
+ * - Most impactful patterns
+ * - Question statistics
+ */
+
+/**
+ * Generate complete analytics report
+ * @param {string} projectPath - Project root path
+ * @returns {Promise<Object>} Complete analytics data
+ */
+async function generateAnalytics(projectPath) {
+  try {
+    // Load all learning data
+    const skipHistory = await storage.getSkipHistory(projectPath) || { sessions: [] };
+    const answerHistory = await storage.getAnswerHistory(projectPath) || { sessions: [] };
+    const patterns = await storage.getPatterns(projectPath) || { patterns: [] };
+    const rules = await storage.getLearnedRules(projectPath) || { rules: [] };
+    const stats = await storage.getLearningStats(projectPath) || {};
+    const config = await storage.getLearningConfig(projectPath) || {};
+
+    // Calculate all metrics
+    const overview = calculateOverviewStats(stats, patterns, rules, skipHistory, answerHistory);
+    const skipTrends = calculateSkipTrends(skipHistory);
+    const categoryPreferences = calculateCategoryPreferences(skipHistory, answerHistory);
+    const patternDistribution = calculatePatternDistribution(patterns.patterns);
+    const effectiveness = calculateEffectiveness(skipHistory, patterns.patterns, rules.rules);
+    const decayStatus = calculateDecayStatus(patterns.patterns, config);
+    const sessionTimeline = calculateSessionTimeline(skipHistory, answerHistory);
+    const impactfulPatterns = calculateImpactfulPatterns(patterns.patterns, rules.rules, skipHistory);
+    const questionStats = calculateQuestionStats(skipHistory, answerHistory);
+
+    return {
+      version: '1.0',
+      exportedAt: new Date().toISOString(),
+      exportType: 'learning-analytics',
+      dataRange: {
+        firstSession: skipHistory.sessions.length > 0 ? skipHistory.sessions[0].timestamp : null,
+        lastSession: skipHistory.sessions.length > 0 ? skipHistory.sessions[skipHistory.sessions.length - 1].timestamp : null,
+        totalSessions: skipHistory.sessions.length,
+        daysSpanned: calculateDaysSpanned(skipHistory.sessions)
+      },
+      overview,
+      skipTrends,
+      categoryPreferences,
+      patternDistribution,
+      effectiveness,
+      decayStatus,
+      sessionTimeline,
+      impactfulPatterns,
+      questionStats
+    };
+  } catch (error) {
+    console.error('Error generating analytics:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Calculate overview statistics
+ * @param {Object} stats - Stats object
+ * @param {Object} patterns - Patterns object
+ * @param {Object} rules - Rules object
+ * @param {Object} skipHistory - Skip history
+ * @param {Object} answerHistory - Answer history
+ * @returns {Object} Overview statistics
+ */
+function calculateOverviewStats(stats, patterns, rules, skipHistory, answerHistory) {
+  // Count all patterns except those explicitly marked as removed
+  const activePatterns = patterns.patterns.filter(p => !p.status || p.status !== 'removed').length;
+  const activeRules = rules.rules.filter(r => r.enabled !== false).length;
+
+  // Calculate learning system age
+  const firstSession = skipHistory.sessions.length > 0 ? skipHistory.sessions[0] : null;
+  const learningAge = firstSession ? daysBetween(new Date(firstSession.timestamp), new Date()) : 0;
+
+  return {
+    totalSessions: stats.totalSessions || skipHistory.sessions.length,
+    totalSkips: stats.totalSkips || countTotalSkips(skipHistory),
+    manualSkips: countManualSkips(skipHistory),
+    filteredSkips: countFilteredSkips(skipHistory),
+    totalAnswers: stats.totalAnswers || countTotalAnswers(answerHistory),
+    activePatterns,
+    activeRules,
+    learningAge,
+    dataSizeMB: 0 // Will be calculated if needed
+  };
+}
+
+/**
+ * Calculate skip trends over last 12 weeks
+ * @param {Object} skipHistory - Skip history
+ * @returns {Array} Skip trends by week
+ */
+function calculateSkipTrends(skipHistory) {
+  const weeks = getLast12Weeks();
+  const trendData = weeks.map(week => {
+    const weekSessions = filterSessionsByWeek(skipHistory.sessions, week);
+    const manualSkips = countSkipsByReason(weekSessions, 'manual');
+    const filteredSkips = countSkipsByReason(weekSessions, 'filtered');
+    const totalAnswers = countAnswersInSessions(weekSessions);
+    const totalQuestions = manualSkips + filteredSkips + totalAnswers;
+    const skipRate = totalQuestions > 0 ? Math.round((manualSkips + filteredSkips) / totalQuestions * 100) : 0;
+
+    return {
+      week: week.label,
+      weekNumber: week.weekNumber,
+      manualSkips,
+      filteredSkips,
+      totalSkips: manualSkips + filteredSkips,
+      skipRate
+    };
+  });
+
+  return trendData;
+}
+
+/**
+ * Calculate category preferences (skip rates by category)
+ * @param {Object} skipHistory - Skip history
+ * @param {Object} answerHistory - Answer history
+ * @returns {Array} Category preferences sorted by skip rate
+ */
+function calculateCategoryPreferences(skipHistory, answerHistory) {
+  const categories = {};
+
+  // Count skips by category
+  for (const session of skipHistory.sessions) {
+    for (const skip of session.skips || []) {
+      if (!skip.category) continue;
+      if (!categories[skip.category]) {
+        categories[skip.category] = { skips: 0, answers: 0 };
+      }
+      categories[skip.category].skips++;
+    }
+  }
+
+  // Count answers by category
+  for (const session of answerHistory.sessions) {
+    for (const answer of session.answers || []) {
+      if (!answer.category) continue;
+      if (!categories[answer.category]) {
+        categories[answer.category] = { skips: 0, answers: 0 };
+      }
+      categories[answer.category].answers++;
+    }
+  }
+
+  // Calculate skip rates
+  const preferences = Object.entries(categories).map(([category, data]) => {
+    const total = data.skips + data.answers;
+    const skipRate = total > 0 ? Math.round((data.skips / total) * 100) : 0;
+
+    return {
+      category,
+      skips: data.skips,
+      answers: data.answers,
+      total,
+      skipRate,
+      level: getSkipLevel(skipRate)
+    };
+  });
+
+  // Sort by skip rate descending
+  return preferences.sort((a, b) => b.skipRate - a.skipRate);
+}
+
+/**
+ * Calculate pattern confidence distribution
+ * @param {Array} patterns - Array of patterns
+ * @returns {Object} Pattern distribution data
+ */
+function calculatePatternDistribution(patterns) {
+  const distribution = {
+    high: patterns.filter(p => p.confidence >= 90).length,
+    medium: patterns.filter(p => p.confidence >= 75 && p.confidence < 90).length,
+    low: patterns.filter(p => p.confidence >= 50 && p.confidence < 75).length,
+    veryLow: patterns.filter(p => p.confidence < 50).length
+  };
+
+  const avgConfidence = patterns.length > 0
+    ? Math.round(patterns.reduce((sum, p) => sum + p.confidence, 0) / patterns.length)
+    : 0;
+
+  const atRisk = patterns.filter(p => p.confidence < 50 || isInactive(p, 5));
+
+  return {
+    distribution,
+    avgConfidence,
+    totalPatterns: patterns.length,
+    atRiskCount: atRisk.length,
+    atRiskPatterns: atRisk.map(p => ({
+      id: p.id,
+      questionId: p.questionId,
+      confidence: p.confidence,
+      lastSeen: p.lastSeen
+    }))
+  };
+}
+
+/**
+ * Calculate learning effectiveness metrics
+ * @param {Object} skipHistory - Skip history
+ * @param {Array} patterns - Array of patterns
+ * @param {Array} rules - Array of rules
+ * @returns {Object} Effectiveness metrics
+ */
+function calculateEffectiveness(skipHistory, patterns, rules) {
+  // Time saved: filtered questions × avg time per question
+  const avgTimePerQuestion = 2.5; // minutes
+  const questionsFiltered = countFilteredQuestions(skipHistory);
+  const timeSavedMinutes = Math.round(questionsFiltered * avgTimePerQuestion);
+
+  // Pattern accuracy: user-approved patterns / total patterns
+  const approvedPatterns = patterns.filter(p => p.userApproved).length;
+  const patternAccuracy = patterns.length > 0
+    ? Math.round((approvedPatterns / patterns.length) * 100)
+    : 0;
+
+  // Rule application rate
+  const totalRuleApplications = rules.reduce((sum, r) => sum + (r.appliedCount || 0), 0);
+  const avgApplicationsPerRule = rules.length > 0
+    ? Math.round(totalRuleApplications / rules.length)
+    : 0;
+
+  // Overall effectiveness (simple: pattern accuracy)
+  const overallEffectiveness = patternAccuracy;
+
+  return {
+    timeSavedMinutes,
+    timeSavedHours: (timeSavedMinutes / 60).toFixed(1),
+    questionsFiltered,
+    falsePositives: 0, // TODO: Implement tracking
+    falsePositiveRate: 0,
+    patternAccuracy,
+    totalRuleApplications,
+    avgApplicationsPerRule,
+    overallEffectiveness
+  };
+}
+
+/**
+ * Calculate pattern decay status
+ * @param {Array} patterns - Array of patterns
+ * @param {Object} config - Learning config
+ * @returns {Object} Decay status data
+ */
+function calculateDecayStatus(patterns, config) {
+  const now = new Date();
+  const decayStatus = {
+    healthy: [],
+    warning: [],
+    critical: []
+  };
+
+  for (const pattern of patterns) {
+    const daysSinceLastSeen = pattern.lastSeen
+      ? daysBetween(new Date(pattern.lastSeen), now)
+      : 999;
+    const monthsInactive = daysSinceLastSeen / 30;
+
+    // Categorize by confidence and inactivity
+    if (pattern.confidence >= 75 && monthsInactive < 3) {
+      decayStatus.healthy.push(pattern);
+    } else if (pattern.confidence >= 50 && monthsInactive < 5) {
+      decayStatus.warning.push(pattern);
+    } else {
+      decayStatus.critical.push(pattern);
+    }
+  }
+
+  // Recently renewed patterns (last 30 days)
+  const recentlyRenewed = patterns.filter(p => {
+    if (!p.lastSeen) return false;
+    const daysSince = daysBetween(new Date(p.lastSeen), now);
+    return daysSince <= 30;
+  });
+
+  // Average pattern age
+  const avgAge = patterns.length > 0
+    ? Math.round(patterns.reduce((sum, p) => {
+        if (!p.createdAt) return sum;
+        return sum + daysBetween(new Date(p.createdAt), now);
+      }, 0) / patterns.length)
+    : 0;
+
+  return {
+    healthy: decayStatus.healthy.length,
+    warning: decayStatus.warning.length,
+    critical: decayStatus.critical.length,
+    recentlyRenewed: recentlyRenewed.length,
+    avgAge,
+    needsAttention: decayStatus.critical.map(p => ({
+      id: p.id,
+      questionId: p.questionId,
+      confidence: p.confidence,
+      lastSeen: p.lastSeen
+    }))
+  };
+}
+
+/**
+ * Calculate session timeline
+ * @param {Object} skipHistory - Skip history
+ * @param {Object} answerHistory - Answer history
+ * @returns {Object} Session timeline data
+ */
+function calculateSessionTimeline(skipHistory, answerHistory) {
+  const sessions = skipHistory.sessions;
+  const timeline = [];
+
+  for (const session of sessions) {
+    const skipCount = (session.skips || []).length;
+    const matchingAnswerSession = answerHistory.sessions.find(
+      s => s.sessionId === session.sessionId
+    );
+    const answerCount = matchingAnswerSession ? (matchingAnswerSession.answers || []).length : 0;
+
+    timeline.push({
+      sessionId: session.sessionId,
+      timestamp: session.timestamp,
+      projectType: session.projectType,
+      frameworks: session.frameworks,
+      skipCount,
+      answerCount,
+      totalQuestions: skipCount + answerCount
+    });
+  }
+
+  // Sort by timestamp descending (most recent first)
+  timeline.sort((a, b) => new Date(b.timestamp) - new Date(a.timestamp));
+
+  // Calculate frequency
+  let sessionsPerWeek = 0;
+  let firstSession = null;
+  let lastSession = null;
+
+  if (sessions.length > 0 && sessions[0].timestamp) {
+    firstSession = new Date(sessions[0].timestamp).toISOString().split('T')[0];
+
+    const lastSessionData = sessions[sessions.length - 1];
+    if (lastSessionData.timestamp) {
+      lastSession = new Date(lastSessionData.timestamp).toISOString().split('T')[0];
+    }
+
+    if (sessions[0].timestamp && lastSessionData.timestamp) {
+      const weeksBetween = Math.ceil(daysBetween(new Date(sessions[0].timestamp), new Date(lastSessionData.timestamp)) / 7);
+      sessionsPerWeek = weeksBetween > 0 ? (sessions.length / weeksBetween).toFixed(1) : sessions.length;
+    }
+  }
+
+  return {
+    timeline,
+    sessionsPerWeek,
+    totalSessions: sessions.length,
+    firstSession,
+    lastSession
+  };
+}
+
+/**
+ * Calculate most impactful patterns
+ * @param {Array} patterns - Array of patterns
+ * @param {Array} rules - Array of rules
+ * @param {Object} skipHistory - Skip history
+ * @returns {Object} Impactful patterns data
+ */
+function calculateImpactfulPatterns(patterns, rules, skipHistory) {
+  const impactData = [];
+
+  for (const pattern of patterns) {
+    const matchingRule = rules.find(r => r.patternId === pattern.id);
+    const appliedCount = matchingRule ? (matchingRule.appliedCount || 0) : 0;
+    const timeSaved = appliedCount * 2.5; // 2.5 min per question
+
+    impactData.push({
+      pattern: {
+        id: pattern.id,
+        questionId: pattern.questionId,
+        questionText: pattern.questionText,
+        confidence: pattern.confidence,
+        type: pattern.type
+      },
+      appliedCount,
+      timeSaved: Math.round(timeSaved),
+      impact: calculateImpact(appliedCount, pattern.confidence)
+    });
+  }
+
+  return {
+    topByTimeSaved: impactData
+      .sort((a, b) => b.timeSaved - a.timeSaved)
+      .slice(0, 5),
+    topByApplications: impactData
+      .sort((a, b) => b.appliedCount - a.appliedCount)
+      .slice(0, 5),
+    perfectConfidence: patterns.filter(p => p.confidence === 100),
+    newestHighConfidence: patterns
+      .filter(p => p.confidence >= 90)
+      .sort((a, b) => new Date(b.createdAt || 0) - new Date(a.createdAt || 0))
+      .slice(0, 5)
+  };
+}
+
+/**
+ * Calculate question statistics
+ * @param {Object} skipHistory - Skip history
+ * @param {Object} answerHistory - Answer history
+ * @returns {Object} Question statistics
+ */
+function calculateQuestionStats(skipHistory, answerHistory) {
+  const questionData = {};
+
+  // Aggregate skip data
+  for (const session of skipHistory.sessions) {
+    for (const skip of session.skips || []) {
+      if (!questionData[skip.questionId]) {
+        questionData[skip.questionId] = {
+          questionId: skip.questionId,
+          text: skip.text,
+          category: skip.category,
+          skips: 0,
+          answers: 0,
+          totalTimeSpent: 0
+        };
+      }
+      questionData[skip.questionId].skips++;
+    }
+  }
+
+  // Aggregate answer data
+  for (const session of answerHistory.sessions) {
+    for (const answer of session.answers || []) {
+      if (!questionData[answer.questionId]) {
+        questionData[answer.questionId] = {
+          questionId: answer.questionId,
+          text: answer.text,
+          category: answer.category,
+          skips: 0,
+          answers: 0,
+          totalTimeSpent: 0
+        };
+      }
+      questionData[answer.questionId].answers++;
+      questionData[answer.questionId].totalTimeSpent += answer.timeSpent || 0;
+    }
+  }
+
+  // Calculate rates and averages
+  const stats = Object.values(questionData).map(q => {
+    const total = q.skips + q.answers;
+    q.skipRate = total > 0 ? Math.round((q.skips / total) * 100) : 0;
+    q.avgTimeSpent = q.answers > 0 ? Math.round(q.totalTimeSpent / q.answers) : 0;
+    return q;
+  });
+
+  return {
+    mostAnswered: stats
+      .sort((a, b) => b.answers - a.answers)
+      .slice(0, 10),
+    mostSkipped: stats
+      .sort((a, b) => b.skips - a.skips)
+      .slice(0, 10),
+    lowestSkipRate: stats
+      .filter(q => q.skips + q.answers > 0)
+      .sort((a, b) => a.skipRate - b.skipRate)
+      .slice(0, 10)
+  };
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Calculate days between two dates
+ * @param {Date} date1 - Start date
+ * @param {Date} date2 - End date
+ * @returns {number} Days between dates
+ */
+function daysBetween(date1, date2) {
+  return Math.floor((date2 - date1) / (1000 * 60 * 60 * 24));
+}
+
+/**
+ * Get last 12 weeks
+ * @returns {Array} Array of week objects
+ */
+function getLast12Weeks() {
+  const weeks = [];
+  const now = new Date();
+
+  for (let i = 11; i >= 0; i--) {
+    const weekStart = new Date(now);
+    weekStart.setDate(now.getDate() - (i * 7));
+    const weekEnd = new Date(weekStart);
+    weekEnd.setDate(weekStart.getDate() + 6);
+
+    weeks.push({
+      label: `Week ${getWeekNumber(weekStart)}`,
+      weekNumber: getWeekNumber(weekStart),
+      start: weekStart,
+      end: weekEnd
+    });
+  }
+
+  return weeks;
+}
+
+/**
+ * Get week number for a date
+ * @param {Date} date - Date
+ * @returns {number} Week number
+ */
+function getWeekNumber(date) {
+  const firstDayOfYear = new Date(date.getFullYear(), 0, 1);
+  const pastDaysOfYear = (date - firstDayOfYear) / 86400000;
+  return Math.ceil((pastDaysOfYear + firstDayOfYear.getDay() + 1) / 7);
+}
+
+/**
+ * Filter sessions by week
+ * @param {Array} sessions - Array of sessions
+ * @param {Object} week - Week object
+ * @returns {Array} Filtered sessions
+ */
+function filterSessionsByWeek(sessions, week) {
+  return sessions.filter(session => {
+    const sessionDate = new Date(session.timestamp);
+    return sessionDate >= week.start && sessionDate <= week.end;
+  });
+}
+
+/**
+ * Count skips by reason in sessions
+ * @param {Array} sessions - Array of sessions
+ * @param {string} reason - Reason ('manual' or 'filtered')
+ * @returns {number} Skip count
+ */
+function countSkipsByReason(sessions, reason) {
+  return sessions.reduce((count, session) => {
+    return count + (session.skips || []).filter(s => s.reason === reason).length;
+  }, 0);
+}
+
+/**
+ * Count answers in sessions
+ * @param {Array} sessions - Array of sessions
+ * @returns {number} Answer count
+ */
+function countAnswersInSessions(sessions) {
+  return sessions.reduce((count, session) => {
+    return count + (session.answers || []).length;
+  }, 0);
+}
+
+/**
+ * Get skip level from skip rate
+ * @param {number} skipRate - Skip rate percentage
+ * @returns {string} Level ('high', 'medium', 'low')
+ */
+function getSkipLevel(skipRate) {
+  if (skipRate >= 70) return 'high';
+  if (skipRate >= 40) return 'medium';
+  return 'low';
+}
+
+/**
+ * Check if pattern is inactive
+ * @param {Object} pattern - Pattern object
+ * @param {number} months - Months threshold
+ * @returns {boolean} True if inactive
+ */
+function isInactive(pattern, months) {
+  if (!pattern.lastSeen) return true;
+  const now = new Date();
+  const lastSeen = new Date(pattern.lastSeen);
+  const monthsInactive = (now - lastSeen) / (1000 * 60 * 60 * 24 * 30);
+  return monthsInactive >= months;
+}
+
+/**
+ * Calculate impact score
+ * @param {number} applications - Number of applications
+ * @param {number} confidence - Confidence score
+ * @returns {number} Impact score
+ */
+function calculateImpact(applications, confidence) {
+  return Math.round(applications * confidence * 0.01);
+}
+
+/**
+ * Count total skips
+ * @param {Object} skipHistory - Skip history
+ * @returns {number} Total skips
+ */
+function countTotalSkips(skipHistory) {
+  return skipHistory.sessions.reduce((count, session) => {
+    return count + (session.skips || []).length;
+  }, 0);
+}
+
+/**
+ * Count manual skips
+ * @param {Object} skipHistory - Skip history
+ * @returns {number} Manual skip count
+ */
+function countManualSkips(skipHistory) {
+  return skipHistory.sessions.reduce((count, session) => {
+    return count + (session.skips || []).filter(s => s.reason === 'manual').length;
+  }, 0);
+}
+
+/**
+ * Count filtered skips
+ * @param {Object} skipHistory - Skip history
+ * @returns {number} Filtered skip count
+ */
+function countFilteredSkips(skipHistory) {
+  return skipHistory.sessions.reduce((count, session) => {
+    return count + (session.skips || []).filter(s => s.reason === 'filtered').length;
+  }, 0);
+}
+
+/**
+ * Count total answers
+ * @param {Object} answerHistory - Answer history
+ * @returns {number} Total answers
+ */
+function countTotalAnswers(answerHistory) {
+  return answerHistory.sessions.reduce((count, session) => {
+    return count + (session.answers || []).length;
+  }, 0);
+}
+
+/**
+ * Count filtered questions
+ * @param {Object} skipHistory - Skip history
+ * @returns {number} Filtered question count
+ */
+function countFilteredQuestions(skipHistory) {
+  return countFilteredSkips(skipHistory);
+}
+
+/**
+ * Calculate days spanned by sessions
+ * @param {Array} sessions - Array of sessions
+ * @returns {number} Days spanned
+ */
+function calculateDaysSpanned(sessions) {
+  if (sessions.length === 0) return 0;
+  const first = new Date(sessions[0].timestamp);
+  const last = new Date(sessions[sessions.length - 1].timestamp);
+  return daysBetween(first, last);
+}
+
+module.exports = {
+  generateAnalytics,
+  calculateOverviewStats,
+  calculateSkipTrends,
+  calculateCategoryPreferences,
+  calculatePatternDistribution,
+  calculateEffectiveness,
+  calculateDecayStatus,
+  calculateSessionTimeline,
+  calculateImpactfulPatterns,
+  calculateQuestionStats
+};