feat: implement filename lookup in database (#3)

[danielsreichenbach]

This PR implements a SQLite database for persistent MPQ filename hash storage and resolution, as suggested in the feature request. The database enables filename lookups even when archives lack internal listfiles.

Summary

• Adds SQLite database backend to wow-mpq for storing filename-to-hash mappings
• Implements new mpq db subcommand with comprehensive database management features
• Enables automatic filename resolution during archive listing operations
• Supports both traditional MPQ hashes and HET (Hash Extended Table) formats

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation update
• 🔧 Refactoring (no functional changes)
• ⚡ Performance improvement
• 🧪 Test improvements
• 🏗️ Build system/dependency changes
• 🔒 Security fix

Changes Made

Core Database Module (file-formats/archives/wow-mpq/src/database/)

• connection.rs: Database connection management with automatic schema initialization
• schema.rs: SQLite schema for filenames, archives, and hash mappings
• models.rs: Data models for archive records, file records, and hash types
• import.rs: Import functionality supporting multiple sources (listfiles, archives, directories)
• lookup.rs: Hash lookup implementations for both traditional MPQ and HET formats

Archive Integration

• Added convenience methods to MutableArchive for database operations
• Implemented record_listfile_to_db() method for automatic listfile import
• Enhanced list() method with optional database lookups via --use-db flag

CLI Enhancements (warcraft-rs/src/commands/mpq.rs)

• New mpq db subcommand with operations:
  • status: Display database statistics and health
  • import: Import filenames from listfiles, archives, or directories
  • analyze: Scan MPQ archives and record their filenames
  • lookup: Calculate and display hash values for a filename
  • export: Export database contents to listfile format
  • list: Browse database entries with filtering
• Added --use-db and --record-to-db flags to mpq list command

Dependencies

• Added rusqlite (v0.32) for SQLite database support
• Added directories for platform-specific data directory resolution

Related Issues

Fixes #3

Testing

Test Cases Added/Modified

• Unit tests
• Integration tests
• Compliance tests (StormLib compatibility)
• Performance benchmarks
• Manual testing

Test Results

Manual testing performed with various MPQ archives:

• Successfully imported filenames from listfiles and archives
• Verified hash calculations match expected values
• Confirmed database lookups work correctly during archive listing
• Tested import from WoW installation directories

Tested On

• Linux
• macOS
• Windows
• Cross-compilation targets

WoW Versions Tested

• 1.12.1 (Vanilla)
• 2.4.3 (TBC)
• 3.3.5a (WotLK)
• 4.3.4 (Cataclysm)
• 5.4.8 (MoP)
• Other: _______________

Quality Assurance

Code Quality

• Code follows project style guidelines
• Self-review of code completed
• Code is properly documented
• No obvious performance regressions
• Error handling is appropriate

Required Checks

• cargo fmt --all - Code is formatted
• cargo clippy --all-targets --all-features - No clippy warnings
• cargo test --all-features - All tests pass
• cargo test --no-default-features - Tests pass without features
• cargo deny check - No security/license issues
• Documentation builds successfully

Compatibility

• No breaking changes to public API (or properly documented)
• Backward compatibility maintained where possible
• StormLib compatibility preserved (if applicable)
• Cross-platform compatibility verified

Documentation

• Updated relevant documentation in docs/
• Updated CHANGELOG.md
• Updated README.md (if applicable)
• Added/updated code examples
• Added/updated CLI help text
• API documentation updated (rustdoc)

Benchmarks

Performance Impact

• No performance impact
• Performance improvement (include metrics)
• Performance regression (justified and documented)

The database is optional and only used when explicitly requested, so there's no performance impact on existing operations.

Breaking Changes

None - all database functionality is additive and opt-in.

Security Considerations

• No security implications
• Security improvement
• Potential security impact (reviewed and justified)

The database is stored in the user's local data directory with appropriate permissions.

Additional Context

Dependencies

• rusqlite v0.32 - SQLite database support
• directories v5.0 - Platform-specific data directory resolution

Known Limitations

• Database tests are not yet implemented
• Cross-platform testing needed (only tested on Linux)
• Anonymous file recording (with generated names) not yet implemented

Usage Examples

# Import filenames from a listfile
warcraft-rs mpq db import /path/to/listfile.txt listfile

# Analyze an MPQ archive and record its filenames
warcraft-rs mpq db analyze /path/to/archive.mpq

# List archive contents using database for unknown files
warcraft-rs mpq list /path/to/archive.mpq --use-db

# Look up hash values for a filename
warcraft-rs mpq db lookup "Interface\\Icons\\INV_Misc_QuestionMark.blp"

# Export database to listfile
warcraft-rs mpq db export output.txt

---

Reviewer Notes

Areas of Focus

• Database schema design and efficiency
• Error handling in database operations
• Integration with existing MPQ functionality
• CLI user experience

Questions for Reviewers

• Should we add automatic database updates when extracting files?
• Would batch import operations benefit from progress indicators?
• Should we implement database migration support for future schema changes?

---

By submitting this PR, I confirm that:

• I have read and agree to the Contributing Guidelines
• This PR is ready for review (not a draft)
• I am willing to address feedback and make necessary changes
• I understand this may take time to review and merge

[codecov]

Codecov Report

❌ Patch coverage is 0% with 680 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
warcraft-rs/src/commands/mpq.rs	0.00%	200 Missing ⚠️
...le-formats/archives/wow-mpq/src/database/lookup.rs	0.00%	173 Missing ⚠️
...le-formats/archives/wow-mpq/src/database/import.rs	0.00%	126 Missing ⚠️
...le-formats/archives/wow-mpq/src/database/schema.rs	0.00%	100 Missing ⚠️
...ormats/archives/wow-mpq/src/database/connection.rs	0.00%	36 Missing ⚠️
file-formats/archives/wow-mpq/src/archive.rs	0.00%	32 Missing ⚠️
file-formats/archives/wow-mpq/src/database/mod.rs	0.00%	12 Missing ⚠️
warcraft-rs/src/commands/m2.rs	0.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!