Add utility scripts for statistics generation - Add stats_generator.go to create detailed movie collection analytics - Add letterboxd_stats_poster.go to share statistics on Letterboxd - Create comprehensive documentation in English

Author: JohanDevl

scripts/utils/README.md

@@ -0,0 +1,169 @@
+# Utilities for Export Trakt for Letterboxd
+
+This directory contains utility tools to work with the exports generated by the application.
+
+## Statistics Generator
+
+The `stats_generator.go` script analyzes your CSV export files and generates a detailed statistical report about your movie collection.
+
+### Features
+
+- Basic statistics (total number of movies, watched, rated, etc.)
+- Rating distribution
+- Movies by decade
+- Popular genres
+- Favorite directors
+- Frequent actors
+- Monthly watching activity
+- Interesting facts (oldest movie, longest movie, etc.)
+
+### Installation
+
+Compile the script with Go:
+
+```bash
+cd scripts/utils
+go build -o stats_generator stats_generator.go
+```
+
+### Usage
+
+```bash
+# Basic usage with specific files
+./stats_generator \
+  --watched "/path/to/watched_movies.csv" \
+  --ratings "/path/to/ratings.csv" \
+  --watchlist "/path/to/watchlist.csv" \
+  --output "my_stats.md"
+
+# Or simply point to the exports directory
+./stats_generator --dir "/path/to/exports" --output "my_stats.md"
+```
+
+### Options
+
+- `--watched`: Path to the watched movies CSV file
+- `--ratings`: Path to the ratings CSV file
+- `--watchlist`: Path to the watchlist CSV file
+- `--dir`: Path to the directory containing export files (alternative to specifying individual files)
+- `--output`: Path to the output report file (default: "movie_stats.md")
+
+### Sample Report
+
+The generated report is in Markdown format and looks like this:
+
+```markdown
+# Movie Collection Statistics
+
+_Generated on January 31, 2025_
+
+## Overview
+
+Total unique movies: **1,253**
+
+- Watched movies: **873**
+- Rated movies: **724**
+- Watchlisted movies: **412**
+
+Average rating: **7.4/10**
+
+## Interesting Facts
+
+- Oldest movie: **The Birth of a Nation (1915)**
+- Newest movie: **Dune: Part Two (2024)**
+- Longest movie: **The Lord of the Rings: The Return of the King (201 minutes)**
+- Shortest movie: **World of Tomorrow (16 minutes)**
+
+## Rating Distribution
+
+| Rating | Count | Percentage |
+| ------ | ----- | ---------- |
+| 1/10   | 5     | 0.7%       |
+| 2/10   | 12    | 1.7%       |
+| 3/10   | 24    | 3.3%       |
+| 4/10   | 37    | 5.1%       |
+| 5/10   | 79    | 10.9%      |
+| 6/10   | 108   | 14.9%      |
+| 7/10   | 207   | 28.6%      |
+| 8/10   | 164   | 22.7%      |
+| 9/10   | 76    | 10.5%      |
+| 10/10  | 12    | 1.7%       |
+
+[... and more sections ...]
+```
+
+### Limitations
+
+- The script expects CSV files in the format generated by Export Trakt for Letterboxd
+- The following columns are used if available: "Name", "Year", "WatchedDate", "Runtime", "Genres", "Directors", "Cast", "Rating"
+
+## Letterboxd Stats Poster
+
+The `letterboxd_stats_poster.go` script automatically posts your statistics to Letterboxd as a review.
+
+### Features
+
+- Automatic login to Letterboxd
+- Converts your statistics into a nicely formatted review
+- Supports custom titles and tags
+- Configurable privacy settings (public, friends, private)
+
+### Installation
+
+Compile the script with Go:
+
+```bash
+cd scripts/utils
+go build -o letterboxd_poster letterboxd_stats_poster.go
+```
+
+You'll need to install the required dependency:
+
+```bash
+go get golang.org/x/net/publicsuffix
+```
+
+### Usage
+
+```bash
+# Basic usage with command line arguments
+./letterboxd_poster \
+  --username "your_letterboxd_username" \
+  --password "your_letterboxd_password" \
+  --stats "path/to/your/stats.md" \
+  --title "My Movie Collection Statistics" \
+  --tags "statistics,trakt,export" \
+  --visibility "public"
+
+# Or using a configuration file
+./letterboxd_poster --config "path/to/config.json"
+```
+
+### Options
+
+- `--username`: Your Letterboxd username
+- `--password`: Your Letterboxd password
+- `--stats`: Path to the generated statistics Markdown file
+- `--title`: Title for the review (default: "My Movie Collection Statistics")
+- `--tags`: Comma-separated list of tags (default: "statistics,trakt,export")
+- `--visibility`: Visibility setting ("public", "friends", or "private") (default: "public")
+- `--config`: Path to a JSON configuration file (alternative to command line args)
+
+### Configuration File Format
+
+```json
+{
+  "Username": "your_letterboxd_username",
+  "Password": "your_letterboxd_password",
+  "StatsFile": "path/to/stats.md",
+  "Title": "My Yearly Movie Stats",
+  "Tags": ["statistics", "trakt", "export", "year-in-review"],
+  "Visibility": "public"
+}
+```
+
+### Notes
+
+- The script will post your statistics as a review of "The General" (1926), a classic film that's often used as a placeholder
+- The review is dated with the current date
+- Markdown formatting is preserved in the Letterboxd review