@iservu-inc/adf-cli 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -5,6 +5,237 @@ All notable changes to `@iservu-inc/adf-cli` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.11.0] - 2025-11-04
+
+### 📊 Learning Analytics Dashboard - Phase 6.2
+
+**MAJOR FEATURE:** Comprehensive analytics dashboard for visualizing and analyzing learning system performance with 10+ metrics and multi-format export.
+
+#### What's New
+
+**Analytics Dashboard:**
+- **Interactive CLI Dashboard** - Navigate through multiple analytics views with intuitive menu
+- **10+ Key Metrics** - Overview stats, skip trends, category preferences, pattern distribution, effectiveness
+- **ASCII Visualizations** - Bar charts, distribution displays, and heatmaps in the terminal
+- **Multi-Format Export** - Export analytics as JSON (single file) or CSV (5 separate files)
+- **Pattern Health Tracking** - Monitor pattern decay status (healthy/warning/critical)
+- **Time-Based Trends** - 12-week skip trend analysis with skip rate calculations
+- **Effectiveness Metrics** - Track time saved, pattern accuracy, and rule performance
+
+#### Core Components
+
+**Analytics Engine (lib/learning/analytics.js - 680 lines):**
+- `generateAnalytics()` - Main analytics generation with comprehensive data aggregation
+- `calculateOverviewStats()` - Total sessions, skips, answers, patterns, rules, learning age
+- `calculateSkipTrends()` - 12-week trend analysis with skip rates
+- `calculateCategoryPreferences()` - Category-level skip rates and preference levels
+- `calculatePatternDistribution()` - Confidence distribution (high/medium/low/veryLow)
+- `calculateDecayStatus()` - Pattern health categorization (healthy/warning/critical)
+- `calculateEffectiveness()` - Time saved, pattern accuracy, rule applications, overall effectiveness
+- `calculateSessionTimeline()` - Session frequency and history analysis
+- `calculateImpactfulPatterns()` - Top patterns by time saved and applications
+- `calculateQuestionStats()` - Most answered/skipped questions
+
+**Dashboard UI (lib/learning/analytics-view.js - 530 lines):**
+- `showAnalyticsDashboard()` - Main dashboard entry point
+- `showMainDashboard()` - Overview, trends, and effectiveness view
+- `showCategoryView()` - Detailed category breakdown with heatmap
+- `showPatternHealthView()` - Pattern confidence and decay status
+- `showTimelineView()` - Session history and frequency
+- `showQuestionStatsView()` - Question statistics and insights
+- `showImpactfulPatternsView()` - Top performing patterns
+- `handleExport()` - Export functionality integration
+
+**Export Module (lib/learning/analytics-exporter.js - 240 lines):**
+- `exportAnalytics()` - Main export router (JSON/CSV)
+- `exportJSON()` - Single comprehensive JSON file export
+- `exportCSV()` - Multi-file CSV export (5 files)
+- CSV generators for: overview, skip trends, categories, patterns, effectiveness
+- Proper CSV escaping and timestamp-based filenames
+
+#### Analytics Metrics
+
+**Overview Statistics:**
+- Total sessions count
+- Total skips (manual + filtered breakdown)
+- Total answers count
+- Active patterns and rules
+- Learning system age (days since first session)
+
+**Skip Trends (12 weeks):**
+- Weekly skip counts (manual vs filtered)
+- Skip rate percentage per week
+- Week-over-week comparison
+
+**Category Preferences:**
+- Skip rate by category (0-100%)
+- Preference levels: High Skip (≥70%), Medium Skip (40-69%), Low Skip (<40%)
+- Total questions per category
+- Sorted by skip rate descending
+
+**Pattern Distribution:**
+- Total patterns count
+- Distribution by confidence:
+  - High (≥90%) - Very strong patterns
+  - Medium (75-89%) - Strong patterns
+  - Low (50-74%) - Weak patterns
+  - Very Low (<50%) - Very weak patterns
+- Average confidence score
+- Patterns at risk count (confidence <50 or inactive 5+ months)
+
+**Pattern Decay Status:**
+- Healthy patterns (confidence ≥75%, active <3 months)
+- Warning patterns (confidence 50-74%, active 3-5 months)
+- Critical patterns (confidence <50 or inactive 5+ months)
+- Recently renewed count (last 30 days)
+- Average pattern age (days)
+
+**Effectiveness Metrics:**
+- Time saved (minutes and hours)
+- Questions filtered count
+- False positives and rate
+- Pattern accuracy (% user-approved)
+- Total rule applications
+- Average applications per rule
+- Overall effectiveness score
+
+**Session Timeline:**
+- Total sessions count
+- Average sessions per week
+- Session history with dates
+- First and last session dates
+
+**Impactful Patterns:**
+- Top 10 by time saved (most effective filters)
+- Top 10 by applications (most frequently used)
+
+**Question Statistics:**
+- Top 10 most answered questions
+- Top 10 most skipped questions
+- Total unique questions encountered
+
+#### Export Formats
+
+**JSON Export:**
+- Single comprehensive file with all analytics
+- Structure: `analytics-YYYY-MM-DDTHH-MM-SS.json`
+- Includes all metrics, trends, and metadata
+- Size: ~50-100 KB for typical datasets
+
+**CSV Export:**
+- 5 separate CSV files for different metrics:
+  1. `analytics-overview-*.csv` - Overview statistics
+  2. `analytics-skip-trends-*.csv` - 12-week trends
+  3. `analytics-categories-*.csv` - Category preferences
+  4. `analytics-patterns-*.csv` - Pattern distribution and decay
+  5. `analytics-effectiveness-*.csv` - Effectiveness metrics
+- Timestamp-based filenames
+- Proper CSV escaping for special characters
+
+#### Access & Usage
+
+**Dashboard Access:**
+```bash
+adf config
+# → Learning System
+# → 4. 📊 Analytics Dashboard (NEW)
+```
+
+**Navigation:**
+- Main Dashboard → Overview, Trends, Effectiveness
+- Category Breakdown → Skip rates by category with heatmap
+- Pattern Health → Confidence distribution and decay status
+- Session Timeline → Session history and frequency
+- Question Statistics → Most answered/skipped questions
+- Impactful Patterns → Top performers by time saved/applications
+- Export Analytics → JSON or CSV format
+
+**Export Location:**
+```
+.adf/learning/exports/
+  ├── analytics-2025-11-04T10-30-45.json
+  └── analytics-overview-2025-11-04T10-30-45.csv
+  └── analytics-skip-trends-2025-11-04T10-30-45.csv
+  └── analytics-categories-2025-11-04T10-30-45.csv
+  └── analytics-patterns-2025-11-04T10-30-45.csv
+  └── analytics-effectiveness-2025-11-04T10-30-45.csv
+```
+
+#### Testing
+
+**Test Coverage:**
+- `analytics.test.js` - 25/25 tests passing (100%) ✅
+- `analytics-exporter.test.js` - 23/23 tests passing (100%) ✅
+- `analytics-view.test.js` - 4/13 tests passing (31% - integration tests)
+- **Overall:** 52/61 analytics tests (85.2%)
+- **Project-wide:** 276/300 tests (92%)
+
+**Test Data Generator:**
+- `scripts/generate-test-data.js` - Mock data generator for testing
+- 5 scenarios: empty, new user, active user, power user, edge cases
+- Generates realistic learning data for dashboard testing
+
+#### Performance
+
+**Load Time Target:** < 2 seconds for 100+ sessions
+**Memory Efficiency:** Streaming data processing for large datasets
+**Visualization:** Lightweight ASCII charts for terminal rendering
+
+#### Configuration
+
+No additional configuration required. Analytics uses existing learning data from:
+- `.adf/learning/skip-history.json`
+- `.adf/learning/answer-history.json`
+- `.adf/learning/patterns.json`
+- `.adf/learning/learned-rules.json`
+- `.adf/learning/stats.json`
+
+#### Benefits
+
+**For Users:**
+- Understand learning system behavior and effectiveness
+- Identify patterns in skip/answer behavior
+- Track pattern health and decay status
+- Monitor time savings from automated filtering
+- Make data-driven decisions about pattern approval
+
+**For Debugging:**
+- Verify pattern detection is working correctly
+- Validate decay algorithm effectiveness
+- Identify false positives
+- Analyze category-specific behavior
+- Export data for external analysis
+
+#### Use Cases
+
+**Use Case 1: Review Learning System Performance**
+- View overview to see total sessions and effectiveness
+- Check skip trends to understand behavior over time
+- Review pattern accuracy to validate system
+
+**Use Case 2: Optimize Pattern Management**
+- Check pattern health view to identify critical patterns
+- Review impactful patterns to see which provide most value
+- Export data for deeper analysis
+
+**Use Case 3: Category-Specific Analysis**
+- View category breakdown to identify high-skip categories
+- Understand which question types are most relevant
+- Adjust workflow based on insights
+
+**Use Case 4: Export for Reporting**
+- Generate JSON export for programmatic analysis
+- Create CSV exports for spreadsheet analysis
+- Share analytics with team members
+
+#### Breaking Changes
+
+None. Fully backward compatible with existing learning data.
+
+#### Migration
+
+No migration required. Analytics reads existing learning data without modifications.
+
 ## [0.10.0] - 2025-10-27
 
 ### 🧠 Pattern Decay Algorithm - Phase 6

package/README.md

@@ -291,7 +291,13 @@ ADF CLI includes an intelligent Learning System that improves your interview exp
    - Framework-specific skips (e.g., routing questions for Next.js projects)
    - Answer style preferences (brief vs detailed)
 3. **Rule Generation** - Converts high-confidence patterns (≥75%) into learned rules
-4. **Adaptive Filtering** - Applies learned rules in future interviews (with your approval)
+4. **Pattern Decay** - Automatically keeps patterns fresh and relevant:
+   - Inactive patterns lose confidence over time using exponential decay
+   - High-confidence patterns (≥90%) decay slower than weak patterns
+   - Patterns reconfirmed by your behavior get +10 confidence boost
+   - Stale patterns (confidence <40 or inactive 6+ months) automatically removed
+   - User-approved patterns protected (decay at half rate)
+5. **Adaptive Filtering** - Applies learned rules in future interviews (with your approval)
 
 ### Managing Learning Data
 

package/lib/learning/analytics-exporter.js

@@ -0,0 +1,241 @@
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * Learning Analytics Exporter
+ *
+ * Handles exporting analytics data in multiple formats:
+ * - JSON: Single comprehensive file with all analytics
+ * - CSV: Multiple files for different metrics
+ */
+
+/**
+ * Export analytics data
+ * @param {Object} analyticsData - Complete analytics data
+ * @param {string} projectPath - Project root path
+ * @param {string} format - Export format ('json' or 'csv')
+ * @returns {Promise<Object>} Export result with file paths
+ */
+async function exportAnalytics(analyticsData, projectPath, format = 'json') {
+  const learningPath = path.join(projectPath, '.adf', 'learning');
+  const exportsPath = path.join(learningPath, 'exports');
+
+  // Ensure exports directory exists
+  await fs.ensureDir(exportsPath);
+
+  if (format === 'json') {
+    return await exportJSON(analyticsData, exportsPath);
+  } else if (format === 'csv') {
+    return await exportCSV(analyticsData, exportsPath);
+  } else {
+    throw new Error(`Unsupported export format: ${format}`);
+  }
+}
+
+/**
+ * Export analytics as JSON
+ * @param {Object} analyticsData - Analytics data
+ * @param {string} exportsPath - Exports directory path
+ * @returns {Promise<Object>} Export result
+ */
+async function exportJSON(analyticsData, exportsPath) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
+  const filename = `analytics-${timestamp}.json`;
+  const filePath = path.join(exportsPath, filename);
+
+  // Write JSON file
+  await fs.writeJSON(filePath, analyticsData, { spaces: 2 });
+
+  // Get file size
+  const stats = await fs.stat(filePath);
+  const sizeKB = (stats.size / 1024).toFixed(2);
+
+  return {
+    file: filePath,
+    size: `${sizeKB} KB`,
+    format: 'json'
+  };
+}
+
+/**
+ * Export analytics as CSV (multiple files)
+ * @param {Object} analyticsData - Analytics data
+ * @param {string} exportsPath - Exports directory path
+ * @returns {Promise<Object>} Export result
+ */
+async function exportCSV(analyticsData, exportsPath) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
+  const files = [];
+
+  // Export overview
+  const overviewFile = path.join(exportsPath, `analytics-overview-${timestamp}.csv`);
+  await fs.writeFile(overviewFile, generateOverviewCSV(analyticsData.overview));
+  files.push(overviewFile);
+
+  // Export skip trends
+  const trendsFile = path.join(exportsPath, `analytics-skip-trends-${timestamp}.csv`);
+  await fs.writeFile(trendsFile, generateSkipTrendsCSV(analyticsData.skipTrends));
+  files.push(trendsFile);
+
+  // Export category preferences
+  const categoriesFile = path.join(exportsPath, `analytics-categories-${timestamp}.csv`);
+  await fs.writeFile(categoriesFile, generateCategoriesCSV(analyticsData.categoryPreferences));
+  files.push(categoriesFile);
+
+  // Export patterns
+  const patternsFile = path.join(exportsPath, `analytics-patterns-${timestamp}.csv`);
+  await fs.writeFile(patternsFile, generatePatternsCSV(analyticsData.patternDistribution, analyticsData.decayStatus));
+  files.push(patternsFile);
+
+  // Export effectiveness
+  const effectivenessFile = path.join(exportsPath, `analytics-effectiveness-${timestamp}.csv`);
+  await fs.writeFile(effectivenessFile, generateEffectivenessCSV(analyticsData.effectiveness));
+  files.push(effectivenessFile);
+
+  return {
+    files,
+    format: 'csv'
+  };
+}
+
+/**
+ * Generate overview CSV
+ * @param {Object} overview - Overview data
+ * @returns {string} CSV content
+ */
+function generateOverviewCSV(overview) {
+  const rows = [
+    ['Metric', 'Value', 'Unit'],
+    ['Total Sessions', overview.totalSessions, 'sessions'],
+    ['Total Skips', overview.totalSkips, 'questions'],
+    ['Manual Skips', overview.manualSkips, 'questions'],
+    ['Filtered Skips', overview.filteredSkips, 'questions'],
+    ['Total Answers', overview.totalAnswers, 'questions'],
+    ['Active Patterns', overview.activePatterns, 'patterns'],
+    ['Active Rules', overview.activeRules, 'rules'],
+    ['Learning Age', overview.learningAge, 'days']
+  ];
+
+  return rows.map(row => row.join(',')).join('\n');
+}
+
+/**
+ * Generate skip trends CSV
+ * @param {Array} skipTrends - Skip trends data
+ * @returns {string} CSV content
+ */
+function generateSkipTrendsCSV(skipTrends) {
+  const rows = [
+    ['Week', 'Week Number', 'Manual Skips', 'Filtered Skips', 'Total Skips', 'Skip Rate (%)']
+  ];
+
+  for (const trend of skipTrends) {
+    rows.push([
+      trend.week,
+      trend.weekNumber,
+      trend.manualSkips,
+      trend.filteredSkips,
+      trend.totalSkips,
+      trend.skipRate
+    ]);
+  }
+
+  return rows.map(row => row.join(',')).join('\n');
+}
+
+/**
+ * Generate categories CSV
+ * @param {Array} categories - Category preferences data
+ * @returns {string} CSV content
+ */
+function generateCategoriesCSV(categories) {
+  const rows = [
+    ['Category', 'Skips', 'Answers', 'Total', 'Skip Rate (%)', 'Level']
+  ];
+
+  for (const cat of categories) {
+    rows.push([
+      escapeCSV(cat.category),
+      cat.skips,
+      cat.answers,
+      cat.total,
+      cat.skipRate,
+      cat.level
+    ]);
+  }
+
+  return rows.map(row => row.join(',')).join('\n');
+}
+
+/**
+ * Generate patterns CSV
+ * @param {Object} patternDistribution - Pattern distribution data
+ * @param {Object} decayStatus - Decay status data
+ * @returns {string} CSV content
+ */
+function generatePatternsCSV(patternDistribution, decayStatus) {
+  const dist = patternDistribution.distribution || { high: 0, medium: 0, low: 0, veryLow: 0 };
+  const decay = decayStatus || { healthy: 0, warning: 0, critical: 0, recentlyRenewed: 0, avgAge: 0 };
+
+  const rows = [
+    ['Metric', 'Value', 'Description'],
+    ['Total Patterns', patternDistribution.totalPatterns || 0, 'All patterns'],
+    ['High Confidence (90%+)', dist.high, 'Very strong patterns'],
+    ['Medium Confidence (75-89%)', dist.medium, 'Strong patterns'],
+    ['Low Confidence (50-74%)', dist.low, 'Weak patterns'],
+    ['Very Low Confidence (<50%)', dist.veryLow, 'Very weak patterns'],
+    ['Average Confidence', (patternDistribution.avgConfidence || 0) + '%', 'Mean confidence score'],
+    ['At Risk', patternDistribution.atRiskCount || 0, 'Patterns at risk of removal'],
+    ['', '', ''],
+    ['Decay Status', '', ''],
+    ['Healthy Patterns', decay.healthy, 'Active and strong'],
+    ['Warning Patterns', decay.warning, 'Needs attention'],
+    ['Critical Patterns', decay.critical, 'May be removed soon'],
+    ['Recently Renewed', decay.recentlyRenewed, 'Last 30 days'],
+    ['Average Age', decay.avgAge + ' days', 'Mean pattern age']
+  ];
+
+  return rows.map(row => row.join(',')).join('\n');
+}
+
+/**
+ * Generate effectiveness CSV
+ * @param {Object} effectiveness - Effectiveness data
+ * @returns {string} CSV content
+ */
+function generateEffectivenessCSV(effectiveness) {
+  const rows = [
+    ['Metric', 'Value', 'Unit'],
+    ['Time Saved', effectiveness.timeSavedMinutes, 'minutes'],
+    ['Time Saved (Hours)', effectiveness.timeSavedHours, 'hours'],
+    ['Questions Filtered', effectiveness.questionsFiltered, 'questions'],
+    ['False Positives', effectiveness.falsePositives, 'questions'],
+    ['False Positive Rate', effectiveness.falsePositiveRate, '%'],
+    ['Pattern Accuracy', effectiveness.patternAccuracy, '%'],
+    ['Total Rule Applications', effectiveness.totalRuleApplications, 'applications'],
+    ['Avg Applications Per Rule', effectiveness.avgApplicationsPerRule, 'applications'],
+    ['Overall Effectiveness', effectiveness.overallEffectiveness, '%']
+  ];
+
+  return rows.map(row => row.join(',')).join('\n');
+}
+
+/**
+ * Escape CSV value
+ * @param {string} value - Value to escape
+ * @returns {string} Escaped value
+ */
+function escapeCSV(value) {
+  if (typeof value !== 'string') return value;
+
+  // Escape quotes and wrap in quotes if contains special chars
+  if (value.includes(',') || value.includes('"') || value.includes('\n')) {
+    return '"' + value.replace(/"/g, '""') + '"';
+  }
+
+  return value;
+}
+
+module.exports = {
+  exportAnalytics
+};