top_drives/CHANGELOG.md

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, and this project adheres to Semantic Versioning.

[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

• 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 format Versioning: Follows Semantic Versioning principles Last Updated: 2026-05-07