# Changelog

All notable changes to the Top Drives Records Analyzer project 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).

## [Unreleased]

### Added
- New `improve` command that generates `improve.csv` — owned cars not yet at a final tune build, sorted by track count
- `normalized_config` field on `BestCarRecord` — maps any tune config to its closest final build (323/233/332)
- `normalize_to_final_build()` function — normalizes tune configs by incrementing the smallest digit until sum reaches 8
- `owned_configs` field on `MyCarsData` — extracts actual player tune config (engineMajor/weightMajor/chassisMajor) from `my_cars.json`
- `owned_configs` field on `CarCounts` — passes player config data through to output functions
- `atomic_write()` helper — writes to a temporary file first, then renames on success (no partial CSV files)
- `empty_my_data()` test helper — creates an empty owned configs map for tests
- Version prefix stripping (`v2c_`/`v1c_`) for config keys at parse time
- `FinalBuild` column in `best.csv`, `very_best.csv`, `wishlist.csv`, `add.csv`, `remove.csv` output files
- Dedup check in `update_best_car` now considers `normalized_config` to prevent same car+config duplicates

### Changed
- `capture run` aborts with a clear error when the game package is missing on the device, before any proxy/CA state is set up — a missing package was the launch failure that previously triggered the proxy leak
- BlueStacks shutdown is now graceful: `adb reboot -p` first (clean ext4 unmount), with `taskkill /F` only as a 30 s fallback — force-killing the emulator corrupted `Data.vhdx` and BlueStacks' boot repair then discarded `packages.xml` and `accounts.db` as corrupt files, which took the installed game and the Google account with it (2026-10-02)
- `CarCounts.by_rid` key changed from `String` to `(String, String)` for per-config tracking
- `CarCounts.guid_to_rid` changed from `HashMap<String, String>` to `HashMap<String, HashSet<(String, String)>>`
- `compute_car_counts()` now accepts `owned_configs` parameter
- `compare_records()` now sorts by normalized config as secondary key (after RQ, before brand)
- `load_my_cars_data()` now extracts tune config data for locked cards
- CSV output files now include `FinalBuild` column showing the normalized config
- `update_best_car()` tie detection now checks both `car_rid` and `normalized_config`
- Applied `rustfmt` formatting across the entire codebase
- `capture run` now reverts the device to its pre-capture state before closing BlueStacks — clears the global proxy, removes the adb reverse rule, unmounts the tmpfs CA overlay, and deletes the CA staging files in `/data/local/tmp` (same revert as `capture clean`)

### Removed
- `plans/code-review-v2.md` (completed action items)

### Fixed
- `capture run` no longer leaves BlueStacks offline when a step fails after the device is set up: CA injection, proxy listener bind, proxy/reverse setup, and game launch errors — and Ctrl+C during setup — now run the same device revert as the happy path instead of skipping it (`revert_device_state` is now unconditional once the device is connected)
- `trash.csv` Config column now lists only the copies to delete: for cars where just one tune is useless (e.g. owned 332 + best-everywhere 323) only the dead tune is shown instead of all owned configs
- Cars the records site knows but has no times for (typically new prize cars, returned as `200` with an empty body) no longer abort `fetch` after 3 retries — they are skipped with an info log
- Empty timing files are now treated like missing files instead of producing `EOF while parsing a value` parse errors
- A crashed or killed capture no longer breaks BlueStacks networking: `capture run` clears a stale global `http_proxy` left behind by a previous run at startup (the setting persists VM reboots and black-holes all proxy-honoring traffic, e.g. Play Store and the browser)
- Missing `u8` type annotation on `parse()` in output tests that broke compilation of `cargo test` and `cargo clippy --all-targets` on current rustc

## [0.3.0] - 2026-05-07

### Added
- New `all` command that generates all output CSV files in a single parse pass
- New `wishlist` command with `--min-count` and `--max-wishlist` flags for wishlist management
- `--min-count` flag on `best` command to configure very_best threshold (default: 10)
- `--max-wishlist` flag on `wishlist` and `all` commands (default: 300)
- `CarCounts` struct and `compute_car_counts()` function for shared analysis computation
- CSV file output: `best.csv`, `very_best.csv`, `wishlist.csv`, `add.csv`, `remove.csv`
- All output files now include CSV headers

### Changed
- `best` command now writes to `best.csv` and `very_best.csv` instead of printing to stdout
- `trash` command now writes to `trash.csv` instead of printing to stdout
- All output files are sorted by car RQ (via `compare_cars()`)
- `wishlist` command now generates ideal wishlist, add/remove recommendations

### Removed
- `missing` command (functionality absorbed into `wishlist`/`add`/`remove`)
- `+` prefix from output (no longer needed with dedicated wishlist commands)
- `-` prefix from output (replaced by dedicated `remove.csv`)
- `print_best_cars()`, `print_wishlist_stale()`, `print_trash()` functions

## [0.2.0] - 2026-05-07

### Added
- Comprehensive documentation suite in `docs/` directory
- Detailed code comments for all public functions
- Architecture documentation explaining system design
- User guide with command examples and troubleshooting
- Data structures documentation for JSON formats
- Development setup guide with dependency explanations
- `track_names.json` — external config file mapping track codes to human-readable names (loaded at compile time via `include_str!`)
- `clap` dependency with derive feature for structured CLI argument parsing
- Daily workflow documentation with output file descriptions (`best.csv`, `details.csv`, `add.csv`, `remove.csv`, `trash.csv`, `sorted.csv`, `very_best.csv`, `wishlist.csv`)
- Test suite covering `update_best_car` logic, RQ range analysis, time validation, track name completeness, and condition completeness

### Changed
- `translate_track_name()` in `lib.rs` now loads track name mappings from `track_names.json` instead of a hardcoded match statement
- Magic number 115 replaced with `const MAX_RQ: u8 = 113` in `records.rs` for clarity and maintainability
- `parse_all_times()` now uses a semaphore (limit 20) for bounded concurrency instead of unbounded task spawning
- Replaced manual `env::args()` CLI parsing with `clap` derive for proper `--help`, `--version`, and argument validation
- `print_best_car()` signature changed from `(&String, &String, &String)` to `(&str, &str, u8)` for idiomatic Rust and compile-time RQ validation
- Empty test bodies removed from `records.rs`
- Better progress reporting during data fetching
- Improved CSV output formatting

### Removed
- **Club Module**: Removed `src/club.rs` binary (topdrives.club is no longer maintained)
- **scraper dependency**: Removed `scraper` crate from `Cargo.toml` (was only used by club module)
- **tracks.txt**: Removed track definitions file (only used by club binary)
- Club module `Car` struct (separate struct with `class`, `upgrade` fields)

## [0.2.0] - 2026-05-07

### Added
- **Track-Specific Analysis**: New `track` command for targeted recommendations
- **Enhanced Output**: CSV file generation for analysis results
- **Improved Concurrency**: Better handling of multiple simultaneous downloads
- **Rate Limiting**: Configurable download limits to respect server constraints

### Changed
- **Modular Architecture**: Split functionality into separate binary targets
- **Error Handling**: More graceful handling of network and parsing errors
- **Configuration**: Externalized track and car data sources
- **Performance**: Optimized memory usage for large datasets

### Fixed
- **Memory Leaks**: Fixed issues with async task cleanup
- **File Handle Management**: Proper cleanup of temporary files
- **Network Timeouts**: Better handling of slow or unreliable connections

## [0.1.0] - 2024-01-XX

### Added
- **Initial Release**: Core functionality for Top Drives car analysis
- **Best Cars Analysis**: Identify top performing cars in collection
- **Missing Cars Detection**: Find cars that would improve performance
- **Collection Optimization**: Identify cars safe to remove
- **Detailed Performance Data**: Comprehensive timing analysis
- **JSON Data Processing**: Parse community timing database
- **Concurrent Processing**: Multi-threaded analysis for performance

### Features
- **Multi-Platform Support**: Windows, macOS, and Linux compatibility
- **Comprehensive Track Support**: All tracks and surface conditions
- **RQ Range Analysis**: Performance analysis across rarity brackets
- **User Collection Integration**: Import and analyze personal car collection
- **Community Data Integration**: Leverage crowd-sourced timing data

## Technical Features by Version

### Data Processing
- **[0.1.0]** Basic JSON parsing and analysis
- **[0.2.0]** Enhanced error handling and data validation
- **[Unreleased]** Track name mappings externalized to `track_names.json`

### Performance
- **[0.1.0]** Single-threaded processing
- **[0.2.0]** Concurrent downloads with rate limiting
- **[Unreleased]** Bounded concurrency via semaphore (limit 20); `MAX_RQ` constant replaces magic number

### User Interface
- **[0.1.0]** Basic command-line interface
- **[0.2.0]** Enhanced output formatting and CSV export
- **[Unreleased]** `full_script` command for complete daily workflow

### Data Sources
- **[0.1.0]** JSON-based records from community repository
- **[0.2.0]** Added HTML scraping from topdrives.club
- **[Unreleased]** Removed club scraping (topdrives.club no longer maintained)

## Migration Guide

### Upgrading to Unreleased from 0.2.0

**Breaking Changes:**
1. **Club module removed**: `cargo run --bin club` is no longer available
2. **`scraper` dependency removed**: No longer needed without club module
3. **`tracks.txt` removed**: Track names now in `track_names.json`
4. **`translate_track_name()` changed**: Now loads from `track_names.json` instead of hardcoded match
5. **Magic number 115 → `MAX_RQ` (113)**: RQ range analysis now uses `MAX_RQ = 113` constant

**New Features Available:**
1. **`full_script` command**: Run fetch + all analysis in one command
2. **Additional output files**: `add.csv`, `remove.csv`, `sorted.csv`, `very_best.csv`, `wishlist.csv`
3. **External track name config**: `track_names.json` can be updated without code changes

### Upgrading from 0.1.0 to 0.2.0

**No breaking changes** - the upgrade is fully backwards compatible.

**New Features Available:**
1. **Track Command**: Specific track analysis with `cargo run --bin records -- track`
2. **CSV Output**: Automatic generation of analysis files

**Performance Improvements:**
- Faster data fetching with concurrent downloads
- Better memory usage for large datasets
- Improved error recovery

## Deprecation Notices

### Removed in Unreleased
- **Club Module**: `src/club.rs` and `cargo run --bin club` — topdrives.club is no longer maintained
- **`scraper` dependency**: Removed from `Cargo.toml`
- **`tracks.txt`**: Replaced by `track_names.json`

### Deprecated Features
- **None currently deprecated**

## Community Contributions

### Notable Contributions
- **Community Timing Data**: All performance data from Top Drives community
- **Track Definitions**: Comprehensive track database
- **Bug Reports**: User feedback for improvements

### Contribution Statistics
- **Timing Submissions**: 1000+ cars with community data
- **Track Coverage**: 200+ tracks across all conditions
- **Active Contributors**: Community-driven development

## Performance Benchmarks

### Data Processing Speed
- **Initial Load**: ~2-3 minutes (downloads 1000+ files)
- **Subsequent Runs**: <30 seconds (uses cached data)
- **Concurrent Operations**: 20 simultaneous downloads (semaphore bounded)

### Memory Usage
- **Base Application**: ~50MB
- **With Full Dataset**: ~200MB
- **Peak During Processing**: ~300MB

### Network Efficiency
- **Compression**: Efficient HTTP compression
- **Connection Reuse**: Persistent HTTP connections
- **Rate Limiting**: Semaphore-bounded concurrency (limit 20)

## Known Issues and Limitations

### Current Limitations
- **Data Freshness**: Requires manual refresh for latest community data
- **Network Dependency**: Requires internet for initial data download
- **Storage Requirements**: Large local dataset (~100MB)
- **Single User**: Designed for individual use, not multi-user

### Platform-Specific Issues
- **Windows**: Potential path length limitations with many files
- **macOS**: Gatekeeper may flag the binary (code-signed in releases)
- **Linux**: No known issues

## Future Roadmap

### Planned Features (Unreleased)
- **Historical Analysis**: Track performance changes over time
- **Advanced Analytics**: Statistical analysis and trend detection

### Potential Enhancements
- **Real-time Updates**: Live data synchronization
- **Customization**: User-defined analysis parameters
- **Export Options**: Multiple file formats (PDF, Excel)

## Support Information

### Getting Help
1. **Documentation**: Check `docs/` directory for comprehensive guides
2. **Issue Tracker**: Report bugs and request features
3. **Discussions**: Community forum for questions and tips

### Troubleshooting Resources
- **User Guide**: Step-by-step instructions and examples
- **Development Setup**: Technical installation guide
- **Data Structures**: Detailed format documentation
- **Architecture Guide**: System design and data flow

## Acknowledgments

### Contributors
- **Original Author**: Project creator and maintainer
- **Community Contributors**: Timing data providers and testers
- **Open Source Projects**: Rust ecosystem and tooling

### Data Sources
- **Top Drives Community**: Primary timing data source
- **GitHub Contributors**: Track and car database maintenance

---

**Changelog Format**: Follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format
**Versioning**: Follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) principles
**Last Updated**: 2026-05-07