@arela/uploader 0.2.13 → 1.0.0

package/src/services/ReportingService.js

@@ -0,0 +1,511 @@
+/**
+ * ReportingService.js
+ * Phase 7 - Task 2: Reporting & Analytics
+ *
+ * Provides comprehensive reporting and analytics including:
+ * - Session reports
+ * - Batch reports
+ * - Error analysis reports
+ * - Export functionality (JSON, CSV, PDF-ready)
+ * - Statistics aggregation
+ */
+import fs from 'fs/promises';
+import path from 'path';
+
+class ReportingService {
+  constructor(logger) {
+    this.logger = logger;
+    this.reports = {};
+    this.sessions = [];
+
+    this.reportConfig = {
+      includeTimestamps: true,
+      includeMetrics: true,
+      includeErrors: true,
+      includeSummary: true,
+    };
+  }
+
+  /**
+   * Generate session report
+   */
+  generateSessionReport(session) {
+    const report = {
+      type: 'session_report',
+      timestamp: new Date().toISOString(),
+      sessionId: session.sessionId,
+      duration: session.endTime
+        ? session.endTime - session.startTime
+        : Date.now() - session.startTime,
+      startTime: new Date(session.startTime).toISOString(),
+      endTime: session.endTime ? new Date(session.endTime).toISOString() : null,
+
+      summary: {
+        totalFiles: session.fileCount || 0,
+        processedFiles: session.processedCount || 0,
+        successCount: session.successCount || 0,
+        errorCount: session.errorCount || 0,
+        skippedCount: session.skippedCount || 0,
+        successRate: this._calculateSuccessRate(session),
+      },
+
+      metrics: {
+        averageProcessingTime: this._calculateAvgTime(session),
+        filesPerSecond: this._calculateFilesPerSecond(session),
+        successRate: this._calculateSuccessRate(session),
+        errorRate: this._calculateErrorRate(session),
+      },
+
+      details: {
+        uploadedFiles: session.uploadedFiles || [],
+        failedFiles: session.failedFiles || [],
+        skippedFiles: session.skippedFiles || [],
+      },
+
+      errors: this._extractErrors(session),
+
+      tags: session.tags || [],
+      notes: session.notes || '',
+    };
+
+    this.reports[session.sessionId] = report;
+    this.sessions.push(report);
+
+    return report;
+  }
+
+  /**
+   * Generate batch report
+   */
+  generateBatchReport(sessions) {
+    const report = {
+      type: 'batch_report',
+      timestamp: new Date().toISOString(),
+      batchId: `batch_${Date.now()}`,
+
+      summary: {
+        totalSessions: sessions.length,
+        totalFiles: 0,
+        totalProcessed: 0,
+        totalSuccess: 0,
+        totalErrors: 0,
+        totalSkipped: 0,
+      },
+
+      sessionMetrics: [],
+      aggregatedMetrics: {},
+      timelineData: [],
+      errorSummary: {},
+    };
+
+    // Aggregate data from all sessions
+    for (const session of sessions) {
+      const sessionReport = this.generateSessionReport(session);
+
+      report.summary.totalFiles += sessionReport.summary.totalFiles;
+      report.summary.totalProcessed += sessionReport.summary.processedFiles;
+      report.summary.totalSuccess += sessionReport.summary.successCount;
+      report.summary.totalErrors += sessionReport.summary.errorCount;
+      report.summary.totalSkipped += sessionReport.summary.skippedCount;
+
+      report.sessionMetrics.push({
+        sessionId: session.sessionId,
+        duration: sessionReport.duration,
+        fileCount: sessionReport.summary.totalFiles,
+        successRate: sessionReport.metrics.successRate,
+      });
+
+      report.timelineData.push({
+        timestamp: sessionReport.startTime,
+        filesProcessed: sessionReport.summary.processedFiles,
+        duration: sessionReport.duration,
+      });
+
+      // Aggregate errors by type
+      for (const error of sessionReport.errors) {
+        const errorType = error.type || 'unknown';
+        if (!report.errorSummary[errorType]) {
+          report.errorSummary[errorType] = { count: 0, examples: [] };
+        }
+        report.errorSummary[errorType].count++;
+        if (report.errorSummary[errorType].examples.length < 3) {
+          report.errorSummary[errorType].examples.push(error.message);
+        }
+      }
+    }
+
+    // Calculate aggregated metrics
+    report.aggregatedMetrics = {
+      totalDuration: report.sessionMetrics.reduce(
+        (sum, s) => sum + s.duration,
+        0,
+      ),
+      averageSessionDuration:
+        report.sessionMetrics.length > 0
+          ? report.sessionMetrics.reduce((sum, s) => sum + s.duration, 0) /
+            report.sessionMetrics.length
+          : 0,
+      overallSuccessRate:
+        report.summary.totalProcessed > 0
+          ? (
+              (report.summary.totalSuccess / report.summary.totalProcessed) *
+              100
+            ).toFixed(2) + '%'
+          : 'N/A',
+      overallErrorRate:
+        report.summary.totalProcessed > 0
+          ? (
+              (report.summary.totalErrors / report.summary.totalProcessed) *
+              100
+            ).toFixed(2) + '%'
+          : 'N/A',
+      averageFilesPerSession:
+        report.summary.totalFiles / Math.max(report.summary.totalSessions, 1),
+    };
+
+    return report;
+  }
+
+  /**
+   * Generate error analysis report
+   */
+  generateErrorAnalysisReport(sessions) {
+    const report = {
+      type: 'error_analysis_report',
+      timestamp: new Date().toISOString(),
+
+      summary: {
+        totalErrors: 0,
+        uniqueErrorTypes: new Set(),
+        affectedSessions: new Set(),
+      },
+
+      errorBreakdown: {},
+      errorPatterns: [],
+      recommendations: [],
+    };
+
+    for (const session of sessions) {
+      const sessionReport = this.generateSessionReport(session);
+
+      for (const error of sessionReport.errors) {
+        report.summary.totalErrors++;
+        report.summary.uniqueErrorTypes.add(error.type);
+        report.summary.affectedSessions.add(session.sessionId);
+
+        // Breakdown by type
+        const errorType = error.type || 'unknown';
+        if (!report.errorBreakdown[errorType]) {
+          report.errorBreakdown[errorType] = {
+            count: 0,
+            severity: error.severity || 'unknown',
+            examples: [],
+          };
+        }
+        report.errorBreakdown[errorType].count++;
+
+        if (report.errorBreakdown[errorType].examples.length < 5) {
+          report.errorBreakdown[errorType].examples.push({
+            message: error.message,
+            file: error.file,
+            timestamp: error.timestamp,
+          });
+        }
+      }
+    }
+
+    // Convert sets to arrays for JSON serialization
+    report.summary.uniqueErrorTypes = Array.from(
+      report.summary.uniqueErrorTypes,
+    );
+    report.summary.affectedSessions = Array.from(
+      report.summary.affectedSessions,
+    );
+
+    // Identify patterns
+    const errorTypes = Object.keys(report.errorBreakdown);
+    if (errorTypes.length > 0) {
+      const topErrors = errorTypes
+        .sort(
+          (a, b) =>
+            report.errorBreakdown[b].count - report.errorBreakdown[a].count,
+        )
+        .slice(0, 3);
+
+      for (const errorType of topErrors) {
+        report.errorPatterns.push({
+          type: errorType,
+          frequency: report.errorBreakdown[errorType].count,
+          severity: report.errorBreakdown[errorType].severity,
+          occurrenceRate:
+            (
+              (report.errorBreakdown[errorType].count /
+                report.summary.totalErrors) *
+              100
+            ).toFixed(2) + '%',
+        });
+      }
+    }
+
+    // Generate recommendations
+    if (report.summary.totalErrors > 0) {
+      for (const pattern of report.errorPatterns) {
+        report.recommendations.push(
+          `${pattern.type}: Occurs in ${pattern.occurrenceRate} of errors. ` +
+            `Consider implementing retry logic or improving validation.`,
+        );
+      }
+    }
+
+    return report;
+  }
+
+  /**
+   * Export report to JSON
+   */
+  async exportReportJson(report, outputPath) {
+    try {
+      const jsonContent = JSON.stringify(report, null, 2);
+      await fs.writeFile(outputPath, jsonContent, 'utf-8');
+
+      this.logger.info(`Report exported to JSON: ${outputPath}`);
+      return { success: true, path: outputPath };
+    } catch (error) {
+      this.logger.error(`Failed to export report to JSON:`, error);
+      return { success: false, error: error.message };
+    }
+  }
+
+  /**
+   * Export report to CSV
+   */
+  async exportReportCsv(report, outputPath) {
+    try {
+      let csvContent = '';
+
+      if (report.type === 'session_report') {
+        csvContent = this._generateSessionCsv(report);
+      } else if (report.type === 'batch_report') {
+        csvContent = this._generateBatchCsv(report);
+      } else if (report.type === 'error_analysis_report') {
+        csvContent = this._generateErrorAnalysisCsv(report);
+      }
+
+      await fs.writeFile(outputPath, csvContent, 'utf-8');
+
+      this.logger.info(`Report exported to CSV: ${outputPath}`);
+      return { success: true, path: outputPath };
+    } catch (error) {
+      this.logger.error(`Failed to export report to CSV:`, error);
+      return { success: false, error: error.message };
+    }
+  }
+
+  /**
+   * Generate summary statistics
+   */
+  generateSummaryStatistics(sessions) {
+    const stats = {
+      timestamp: new Date().toISOString(),
+      periodAnalyzed: {
+        start: sessions.length > 0 ? sessions[0].startTime : null,
+        end: sessions.length > 0 ? sessions[sessions.length - 1].endTime : null,
+      },
+
+      totals: {
+        sessions: sessions.length,
+        files: 0,
+        processed: 0,
+        successful: 0,
+        failed: 0,
+        skipped: 0,
+      },
+
+      rates: {},
+      performance: {},
+      trending: {},
+    };
+
+    for (const session of sessions) {
+      stats.totals.files += session.fileCount || 0;
+      stats.totals.processed += session.processedCount || 0;
+      stats.totals.successful += session.successCount || 0;
+      stats.totals.failed += session.errorCount || 0;
+      stats.totals.skipped += session.skippedCount || 0;
+    }
+
+    // Calculate rates
+    if (stats.totals.processed > 0) {
+      stats.rates.successRate =
+        ((stats.totals.successful / stats.totals.processed) * 100).toFixed(2) +
+        '%';
+      stats.rates.failureRate =
+        ((stats.totals.failed / stats.totals.processed) * 100).toFixed(2) + '%';
+      stats.rates.skipRate =
+        ((stats.totals.skipped / stats.totals.processed) * 100).toFixed(2) +
+        '%';
+    }
+
+    // Performance metrics
+    if (sessions.length > 0) {
+      const totalDuration = sessions.reduce(
+        (sum, s) => sum + ((s.endTime || Date.now()) - s.startTime),
+        0,
+      );
+      stats.performance.averageSessionDuration =
+        (totalDuration / sessions.length).toFixed(0) + 'ms';
+      stats.performance.totalDuration = totalDuration + 'ms';
+      stats.performance.filesPerSecond = (
+        stats.totals.processed /
+        (totalDuration / 1000)
+      ).toFixed(2);
+    }
+
+    return stats;
+  }
+
+  /**
+   * Get report history
+   */
+  getReportHistory(limit = 10) {
+    return this.sessions
+      .slice(-limit)
+      .reverse()
+      .map((report) => ({
+        reportId: report.sessionId,
+        type: report.type,
+        timestamp: report.timestamp,
+        summary: report.summary,
+        successRate: report.metrics?.successRate,
+      }));
+  }
+
+  /**
+   * Clear old reports
+   */
+  clearOldReports(daysOld = 30) {
+    const cutoffTime = Date.now() - daysOld * 24 * 60 * 60 * 1000;
+    const beforeCount = this.sessions.length;
+
+    this.sessions = this.sessions.filter(
+      (report) => new Date(report.timestamp).getTime() > cutoffTime,
+    );
+
+    const removed = beforeCount - this.sessions.length;
+    this.logger.info(`Cleared ${removed} reports older than ${daysOld} days`);
+
+    return { removed, remaining: this.sessions.length };
+  }
+
+  /**
+   * Private helper methods
+   */
+
+  _calculateSuccessRate(session) {
+    if (!session.processedCount || session.processedCount === 0) return '0%';
+    return (
+      (((session.successCount || 0) / session.processedCount) * 100).toFixed(
+        2,
+      ) + '%'
+    );
+  }
+
+  _calculateErrorRate(session) {
+    if (!session.processedCount || session.processedCount === 0) return '0%';
+    return (
+      (((session.errorCount || 0) / session.processedCount) * 100).toFixed(2) +
+      '%'
+    );
+  }
+
+  _calculateAvgTime(session) {
+    if (!session.processedCount || session.processedCount === 0) return 0;
+    const duration = session.endTime
+      ? session.endTime - session.startTime
+      : Date.now() - session.startTime;
+    return Math.round(duration / session.processedCount) + 'ms';
+  }
+
+  _calculateFilesPerSecond(session) {
+    if (!session.processedCount) return 0;
+    const duration = session.endTime
+      ? session.endTime - session.startTime
+      : Date.now() - session.startTime;
+    return (session.processedCount / (duration / 1000)).toFixed(2);
+  }
+
+  _extractErrors(session) {
+    return (session.errors || []).map((error) => ({
+      type: error.type || 'unknown',
+      message: error.message,
+      file: error.file,
+      severity: error.severity || 'error',
+      timestamp: error.timestamp || new Date().toISOString(),
+      context: error.context,
+    }));
+  }
+
+  _generateSessionCsv(report) {
+    const lines = [
+      'Session Report',
+      `Generated: ${report.timestamp}`,
+      `Session ID: ${report.sessionId}`,
+      '',
+      'Summary',
+      'Total Files,Processed,Success,Errors,Skipped',
+      `${report.summary.totalFiles},${report.summary.processedFiles},${report.summary.successCount},${report.summary.errorCount},${report.summary.skippedCount}`,
+      '',
+      'Metrics',
+      'Metric,Value',
+      `Success Rate,${report.metrics.successRate}`,
+      `Error Rate,${report.metrics.errorRate}`,
+      `Files Per Second,${report.metrics.filesPerSecond}`,
+      `Avg Processing Time,${report.metrics.averageProcessingTime}`,
+    ];
+
+    return lines.join('\n');
+  }
+
+  _generateBatchCsv(report) {
+    const lines = [
+      'Batch Report',
+      `Generated: ${report.timestamp}`,
+      '',
+      'Session Metrics',
+      'Session ID,Duration (ms),File Count,Success Rate',
+    ];
+
+    for (const metric of report.sessionMetrics) {
+      lines.push(
+        `${metric.sessionId},${metric.duration},${metric.fileCount},${metric.successRate}`,
+      );
+    }
+
+    lines.push('', 'Summary', 'Metric,Value');
+    for (const [key, value] of Object.entries(report.aggregatedMetrics)) {
+      lines.push(`${key},${value}`);
+    }
+
+    return lines.join('\n');
+  }
+
+  _generateErrorAnalysisCsv(report) {
+    const lines = [
+      'Error Analysis Report',
+      `Generated: ${report.timestamp}`,
+      '',
+      'Error Summary',
+      'Error Type,Count,Severity,Occurrence Rate',
+    ];
+
+    for (const pattern of report.errorPatterns) {
+      lines.push(
+        `${pattern.type},${pattern.frequency},${pattern.severity},${pattern.occurrenceRate}`,
+      );
+    }
+
+    return lines.join('\n');
+  }
+}
+
+export default ReportingService;