Match IGDB regional-twin platforms in scans (#3462)

[Spinnich]

Description

IGDB catalogues a console and its regional twin as two separate platforms — e.g. SNES (19) vs. Super Famicom (58), and NES (18) vs. Famicom (99). A region-exclusive title is filed under only one of the pair, so a scan that locks the IGDB where clause to a single platform id silently misses those titles: a Japan-only Super Famicom game never matches from an snes library, and a Western-only SNES game never matches from sfam. Same for NES/Famicom.

This maps each regional-twin platform to its counterpart and broadens the IGDB platform filter to include both, so region-exclusive games on either twin match from either library. Fixes #3462.

The change is confined to the IGDB metadata handler's query construction — matching logic, scan orchestration, and every other provider are untouched. Behaviour for all non-twin platforms is byte-for-byte identical (the filter keeps the original platforms=[id] shape).

What changed

• Added an IGDB_REGIONAL_TWIN_PLATFORMS map (SNES↔Super Famicom, NES↔Famicom), backed by named Final platform-id constants.
• Added two private helpers in igdb_handler.py:
  • _platform_igdb_ids_with_twin(id) → [id], or [id, twin] when a twin exists.
  • _build_platforms_where(id, field="platforms") → a single platforms=[id] clause for non-twin platforms, or a parenthesized (platforms=[a] | platforms=[b]) OR-group for twins, so it composes correctly with trailing & … filters.
• Routed every existing platforms=[…] / game.platforms=[…] filter in _search_rom and get_matched_roms_by_name through the helper. The ScummVM keywords=[…] special case is intentionally left as-is (it has no twin).

Files modified

• backend/handler/metadata/igdb_handler.py — new twin map + the two helpers; the four platform where fragments now build through _build_platforms_where.
• backend/tests/handler/metadata/test_igdb_handler.py — added TestRegionalTwinPlatformHelpers (unit tests: bidirectional pairs, non-twin passthrough, single-clause vs. OR-group output) and TestSearchRomRegionalTwinPlatforms (search picks up a Super-Famicom-only game from an snes scan, a Famicom-only game from nes, an SNES-only game from sfam, and a non-twin platform keeps a single-clause filter with no OR group).

Reviewer notes

• Query operator choice: twins use (platforms=[a] | platforms=[b]) (OR of two exact clauses) rather than IGDB's platforms=(a,b) contains-any form, to preserve the exact per-clause semantics the existing single-platform queries rely on.
• Slightly wider candidate pool: including the twin enlarges the result set for affected platforms; final selection still goes through the existing Jaro-Winkler name match, so wrong-region same-console collisions remain unlikely. This is the intended tradeoff.
• Known minor gap (not addressed here): derive_player_count filters multiplayer modes by the original platform_igdb_id, so a game matched via its twin may drop twin-tagged multiplayer modes when deriving player count. Low impact; flagging for awareness.

AI assistance disclosure: the implementation and unit tests were authored on-branch with the help of Claude Code (code generation), and this PR description was drafted by Claude Code. All changes were reviewed by me before submitting.

Checklist

• I've tested the changes locally
• I've updated relevant comments
• I've assigned reviewers for this PR
• I've added unit tests that cover the changes

Screenshots (if applicable)

N/A — backend metadata-matching change, no UI surface.