Add fork statistics visualizer tool with graphs and detailed reports

Co-authored-by: DedeHai <6280424+DedeHai@users.noreply.github.com>

Author: Copilot

tools/README_fork_stats.md

@@ -101,6 +101,20 @@ Detailed machine-readable output including:
 - Full statistical breakdown
 - Intermediate results are automatically saved to `tempresults.json` every 10 forks to prevent data loss on interruption
 
+### Visualization
+
+For advanced visualization and analysis of the JSON results, use the companion visualizer tool:
+
+```bash
+# Generate visualizations from collected data
+python3 tools/fork_stats_visualizer.py results.json --save-plots
+
+# Text-only statistics (no graphs)
+python3 tools/fork_stats_visualizer.py results.json --no-graphs
+```
+
+See [README_fork_stats_visualizer.md](README_fork_stats_visualizer.md) for complete documentation.
+
 ## Performance Considerations
 
 ### Execution Speed

tools/README_fork_stats_visualizer.md

@@ -0,0 +1,240 @@
+# Fork Statistics Visualizer
+
+A Python script that loads JSON data generated by `fork_stats.py` and displays detailed statistics both as formatted text lists and visual graphs.
+
+## Features
+
+- **Text-based Statistics**: Formatted tables with visual bars showing percentages
+- **Interactive Graphs**: Pie charts, bar charts, histograms, and combined dashboards
+- **Top Forks Lists**: Shows top forks by unique branches, owner commits, and activity
+- **Export Capabilities**: Save all visualizations as high-quality PNG images
+- **Works Without Graphics**: Can run in text-only mode without matplotlib
+
+## Installation
+
+### Basic Installation (Text-only)
+The visualizer works without additional dependencies for text-based output:
+```bash
+python3 tools/fork_stats_visualizer.py results.json --no-graphs
+```
+
+### Full Installation (With Graphics)
+For graphical visualizations, install matplotlib:
+```bash
+pip install -r tools/fork_stats_visualizer_requirements.txt
+```
+
+## Usage
+
+### Basic Usage
+Display text statistics and interactive graphs:
+```bash
+python3 tools/fork_stats_visualizer.py results.json
+```
+
+### Text-Only Mode
+Skip graphs and only show text statistics:
+```bash
+python3 tools/fork_stats_visualizer.py results.json --no-graphs
+```
+
+### Save Plots to Files
+Save all plots as PNG files instead of displaying them:
+```bash
+python3 tools/fork_stats_visualizer.py results.json --save-plots
+```
+
+### Custom Output Directory
+Specify where to save the plots:
+```bash
+python3 tools/fork_stats_visualizer.py results.json --save-plots --output-dir ./my_plots
+```
+
+### Show Top N Forks
+Display top 30 forks instead of default 20:
+```bash
+python3 tools/fork_stats_visualizer.py results.json --top-n 30
+```
+
+## Output
+
+### Text Statistics
+
+The script displays:
+
+1. **Repository Information**
+   - Repository name, total forks, stars, watchers
+   - Number of forks analyzed
+   - Analysis timestamp
+
+2. **Fork Age Distribution**
+   - Breakdown by age categories (≤1 month, ≤3 months, ≤6 months, ≤1 year, ≤2 years, >5 years)
+   - Count and percentage for each category
+   - Visual bars showing proportions
+
+3. **Fork Activity Analysis**
+   - Forks with unique branches
+   - Forks with recent main branch
+   - Forks that contributed PRs
+   - Active forks without PR contributions
+   - Visual bars for each metric
+
+4. **Owner Commit Analysis**
+   - Number of forks with owner commits
+   - Total commits by all fork owners
+   - Average commits per fork
+
+5. **Top Forks Lists**
+   - Top N forks by unique branches
+   - Top N forks by owner commits  
+   - Active forks without PR contributions
+
+### Visual Graphs
+
+When matplotlib is available, the script generates:
+
+1. **Age Distribution Pie Chart**
+   - Shows the distribution of fork ages
+   - Color-coded by recency (green for recent, red for old)
+
+2. **Activity Metrics Bar Chart**
+   - Compares different activity metrics side-by-side
+   - Shows percentages for each metric
+
+3. **Owner Commits Distribution Histogram**
+   - Shows the distribution of owner commits across forks
+   - Includes mean and max statistics
+
+4. **Combined Dashboard**
+   - All-in-one view with multiple charts
+   - Summary statistics panel
+   - Perfect for presentations and reports
+
+## Example Output
+
+### Text Output
+```
+================================================================================
+  REPOSITORY INFORMATION
+================================================================================
+
+Repository: wled/WLED
+Total Forks: 1,243
+Stars: 15,500
+Watchers: 326
+
+Analyzed Forks: 100
+
+================================================================================
+  FORK AGE DISTRIBUTION
+================================================================================
+
+Age Category                    Count    Percentage
+------------------------------------------------------------
+Last updated ≤ 1 month             8      8.0%  ████
+Last updated ≤ 3 months           12     12.0%  ██████
+Last updated ≤ 6 months           15     15.0%  ███████
+Last updated ≤ 1 year             23     23.0%  ███████████
+Last updated ≤ 2 years            25     25.0%  ████████████
+Last updated > 5 years            17     17.0%  ████████
+```
+
+### Saved Files
+When using `--save-plots`, the following files are created:
+- `age_distribution.png` - Pie chart of fork ages
+- `activity_metrics.png` - Bar chart of activity metrics
+- `owner_commits_distribution.png` - Histogram of owner commits
+- `dashboard.png` - Combined dashboard view
+
+## Integration with fork_stats.py
+
+### Complete Workflow
+
+1. **Collect Statistics**
+   ```bash
+   python3 tools/fork_stats.py --output results.json --max-forks 100
+   ```
+
+2. **Visualize Results**
+   ```bash
+   python3 tools/fork_stats_visualizer.py results.json --save-plots
+   ```
+
+3. **View Dashboard**
+   Open `fork_plots/dashboard.png` for a complete overview
+
+### Automated Analysis
+
+Create a bash script to run both tools:
+```bash
+#!/bin/bash
+# analyze_forks.sh
+
+# Set your GitHub token
+export GITHUB_TOKEN="your_token_here"
+
+# Collect statistics
+python3 tools/fork_stats.py \
+    --repo wled/WLED \
+    --max-forks 200 \
+    --fast \
+    --output fork_analysis.json
+
+# Generate visualizations
+python3 tools/fork_stats_visualizer.py \
+    fork_analysis.json \
+    --save-plots \
+    --output-dir ./fork_analysis_plots \
+    --top-n 25
+
+echo "Analysis complete! Check fork_analysis_plots/ for visualizations."
+```
+
+## Troubleshooting
+
+### "matplotlib not installed" Warning
+This is normal if you haven't installed matplotlib. The script will still work in text-only mode. To enable graphs:
+```bash
+pip install -r tools/fork_stats_visualizer_requirements.txt
+```
+
+### "No detailed fork data available"
+The JSON file doesn't contain individual fork details. This happens when:
+- Using demo mode in fork_stats.py
+- The analysis was interrupted before collecting fork data
+- The JSON file is incomplete
+
+The visualizer will still show aggregate statistics from the statistics section.
+
+### Plots Not Saving
+Ensure the output directory is writable:
+```bash
+mkdir -p ./fork_plots
+chmod 755 ./fork_plots
+python3 tools/fork_stats_visualizer.py results.json --save-plots --output-dir ./fork_plots
+```
+
+## Command-Line Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `json_file` | Path to JSON file with fork statistics | Required |
+| `--save-plots` | Save plots to files instead of displaying | False |
+| `--output-dir DIR` | Directory to save plots | `./fork_plots` |
+| `--top-n N` | Number of top forks to display | 20 |
+| `--no-graphs` | Skip graph generation, text only | False |
+
+## Dependencies
+
+### Required
+- Python 3.7+
+- json (built-in)
+- argparse (built-in)
+
+### Optional (for graphs)
+- matplotlib >= 3.5.0
+
+Install optional dependencies:
+```bash
+pip install -r tools/fork_stats_visualizer_requirements.txt
+```