Merge pull request #4121 from sdornan/claude/launchbox-n64-matching-b7ce16

fix(launchbox): match ROMs during a scan the way Match ROM does

Author: gantoine

backend/handler/metadata/launchbox_handler/handler.py

@@ -142,37 +142,42 @@ async def get_rom(
         if not remote_available:
             return fallback_rom
 
-        # `keep_tags` prevents stripping content that is considered a tag, e.g., anything between `()` or `[]`.
-        # By default, tags are still stripped to keep scan behavior consistent with previous versions.
-        # If `keep_tags` is True, the full `fs_name` is used for searching.
-        if not keep_tags:
-            search_term = fs_rom_handler.get_file_name_with_no_tags(fs_name)
-        else:
-            search_term = fs_name
-
-        # Resolve MAME arcade filename (e.g. wrlok_l3.zip) to its full title
-        # via LaunchBox's Mame.xml before name-based lookup.
-        if platform_slug == UPS.ARCADE:
-            mame_entry = await self._remote.get_mame_entry(fs_name)
-            if mame_entry:
-                name = (mame_entry.get("Name") or "").strip()
-                if name:
-                    search_term = name
-                    fallback_rom = LaunchboxRom(launchbox_id=None, name=name)
-
-        # We replace " - "/"- " with ": " to match Launchbox's naming convention
-        search_term = re.sub(DASH_COLON_REGEX, ": ", search_term).lower()
-
-        # Check if game is scummvm shortname
-        if platform_slug == UPS.SCUMMVM:
-            search_term = await self._scummvm_format(search_term)
-            fallback_rom = LaunchboxRom(launchbox_id=None, name=search_term)
-
-        index_entry = await self._remote.get_rom(
-            search_term,
-            platform_slug,
-            assume_cache_present=True,
-        )
+        # LaunchBox indexes the filenames its own dumps use, so try that before
+        # rewriting the name into something the title index might accept.
+        index_entry = await self._remote.get_rom_by_file_name(fs_name, platform_slug)
+
+        if index_entry is None:
+            # `keep_tags` prevents stripping content that is considered a tag, e.g., anything between `()` or `[]`.
+            # By default, tags are still stripped to keep scan behavior consistent with previous versions.
+            # If `keep_tags` is True, the full `fs_name` is used for searching.
+            if not keep_tags:
+                search_term = fs_rom_handler.get_file_name_with_no_tags(fs_name)
+            else:
+                search_term = fs_name
+
+            # Resolve MAME arcade filename (e.g. wrlok_l3.zip) to its full title
+            # via LaunchBox's Mame.xml before name-based lookup.
+            if platform_slug == UPS.ARCADE:
+                mame_entry = await self._remote.get_mame_entry(fs_name)
+                if mame_entry:
+                    name = (mame_entry.get("Name") or "").strip()
+                    if name:
+                        search_term = name
+                        fallback_rom = LaunchboxRom(launchbox_id=None, name=name)
+
+            # We replace " - "/"- " with ": " to match Launchbox's naming convention
+            search_term = re.sub(DASH_COLON_REGEX, ": ", search_term).lower()
+
+            # Check if game is scummvm shortname
+            if platform_slug == UPS.SCUMMVM:
+                search_term = await self._scummvm_format(search_term)
+                fallback_rom = LaunchboxRom(launchbox_id=None, name=search_term)
+
+            index_entry = await self._remote.get_rom(
+                search_term,
+                platform_slug,
+                assume_cache_present=True,
+            )
 
         if not index_entry:
             return fallback_rom

backend/handler/metadata/launchbox_handler/local_source.py

@@ -1,11 +1,12 @@
-from pathlib import Path, PureWindowsPath
+from pathlib import PureWindowsPath
 
 from defusedxml import ElementTree as ET
 
 from logger.logger import log
 
 from .platforms import get_platform
 from .types import LAUNCHBOX_PLATFORMS_DIR
+from .utils import file_name_forms
 
 
 class LocalSource:
@@ -46,6 +47,8 @@ async def get_rom(self, fs_name: str, platform_slug: str) -> dict[str, str] | No
                             app_base = PureWindowsPath(app_path).name.strip().lower()
                             if app_base:
                                 indexed_val.setdefault(app_base, entry)
+                                for stem in file_name_forms(app_base):
+                                    indexed_val.setdefault(f"stem:{stem}", entry)
 
                         title = (entry.get("Title") or "").strip().lower()
                         if title:
@@ -68,18 +71,17 @@ async def get_rom(self, fs_name: str, platform_slug: str) -> dict[str, str] | No
         if not fs_key:
             return None
 
-        direct = indexed_val.get(fs_key)
-        if direct is not None:
-            return direct
+        stems = file_name_forms(fs_name)
+        probes = [
+            fs_key,
+            *(f"stem:{stem}" for stem in stems),
+            *(f"title:{stem}" for stem in stems),
+            f"title:{fs_key}",
+        ]
 
-        try:
-            stem = Path(fs_name).stem.strip().lower()
-        except Exception:
-            stem = ""
+        for probe in dict.fromkeys(probes):
+            hit = indexed_val.get(probe)
+            if hit is not None:
+                return hit
 
-        if stem:
-            by_title = indexed_val.get(f"title:{stem}")
-            if by_title is not None:
-                return by_title
-
-        return indexed_val.get(f"title:{fs_key}")
+        return None

backend/handler/metadata/launchbox_handler/remote_source.py

@@ -5,12 +5,14 @@
 
 from .platforms import get_platform
 from .types import (
+    LAUNCHBOX_FILES_KEY,
     LAUNCHBOX_MAME_KEY,
     LAUNCHBOX_METADATA_ALTERNATE_NAME_KEY,
     LAUNCHBOX_METADATA_DATABASE_ID_KEY,
     LAUNCHBOX_METADATA_IMAGE_KEY,
     LAUNCHBOX_METADATA_NAME_KEY,
 )
+from .utils import deinvert_article, file_name_forms
 
 
 class RemoteSource:
@@ -49,6 +51,14 @@ async def get_rom(
         if lower != file_name_clean:
             candidates.append(lower)
 
+        # Dump filenames invert leading articles, so the inverted form is tried
+        # against both indexes before giving up.
+        for candidate in list(candidates):
+            deinverted = deinvert_article(candidate)
+            if deinverted:
+                candidates.append(deinverted)
+        candidates = list(dict.fromkeys(candidates))
+
         for candidate in candidates:
             metadata_name_index_entry = await async_cache.hget(
                 LAUNCHBOX_METADATA_NAME_KEY, f"{candidate}:{platform_name}"
@@ -81,6 +91,38 @@ async def get_rom(
 
         return None
 
+    async def get_rom_by_file_name(
+        self, file_name: str, platform_slug: str
+    ) -> dict | None:
+        """Resolve a ROM file name to its metadata entry via LaunchBox's Files.xml.
+
+        The dump ships a filename to title mapping, the only route to games whose
+        files are named nothing like them (MS-DOS, Amiga, Arcade). On sets where
+        the mapping is just the filename again it simply misses.
+        """
+        platform_name = get_platform(platform_slug).get("name")
+        if not platform_name:
+            return None
+
+        for candidate in file_name_forms(file_name):
+            entry = await async_cache.hget(
+                LAUNCHBOX_FILES_KEY, f"{candidate}:{platform_name}"
+            )
+            if not entry:
+                continue
+
+            game_name = (json.loads(entry).get("GameName") or "").strip()
+            if not game_name:
+                continue
+
+            index_entry = await self.get_rom(
+                game_name, platform_slug, assume_cache_present=True
+            )
+            if index_entry:
+                return index_entry
+
+        return None
+
     async def get_mame_entry(self, file_name: str) -> dict | None:
         """Resolve a MAME arcade filename to its LaunchBox MAME entry.
 

backend/handler/metadata/launchbox_handler/utils.py

@@ -3,6 +3,8 @@
 from pathlib import Path
 
 from handler.filesystem.base_handler import region_name_to_provider_shortcode
+from models.base import compute_file_name_no_ext, compute_file_name_no_tags
+from models.rom import ARTICLES
 
 from .types import LAUNCHBOX_LOCAL_DIR
 
@@ -15,6 +17,46 @@
     "the netherlands": "nl",
 }
 
+# Articles No-Intro moves to the end of a title ("Legend of Zelda, The"), which
+# LaunchBox keeps in front. The article has to sit at the end of the title or
+# right before a subtitle colon, so the group is anchored on both sides.
+_INVERTED_ARTICLE_REGEX = re.compile(
+    rf"^(?P<title>.+?), (?P<article>{'|'.join(ARTICLES)})(?P<subtitle>:.*)?$",
+    re.IGNORECASE,
+)
+
+
+def deinvert_article(term: str) -> str | None:
+    """Move a trailing article back to the front of a title.
+
+    "legend of zelda, the: ocarina of time" becomes
+    "the legend of zelda: ocarina of time". Returns None when the term isn't in
+    the inverted form.
+    """
+    match = _INVERTED_ARTICLE_REGEX.match(term.strip())
+    if not match:
+        return None
+
+    subtitle = match.group("subtitle") or ""
+    return f"{match.group('article')} {match.group('title')}{subtitle}"
+
+
+def file_name_forms(file_name: str) -> list[str]:
+    """Lowercased extension-less forms of a file name, most specific first.
+
+    Reduces both sides of a filename comparison to the same shapes: a library of
+    `.zip` archives has to reach a LaunchBox entry naming a `.z64`, and a
+    No-Intro stem still carries region tags a title never has.
+    """
+    forms = [
+        form.strip().lower()
+        for form in (
+            compute_file_name_no_ext(file_name),
+            compute_file_name_no_tags(file_name),
+        )
+    ]
+    return list(dict.fromkeys(form for form in forms if form))
+
 
 def launchbox_region_to_shortcode(region_name: str | None) -> str | None:
     """Map a LaunchBox image Region name to a provider shortcode (e.g. "us").

backend/handler/scan_handler.py

@@ -331,6 +331,61 @@ async def scan_firmware(
     return Firmware(**firmware_attrs)
 
 
+async def resolve_launchbox_rom(
+    *,
+    rom: Rom,
+    fs_name: str,
+    platform_slug: str,
+    scan_type: ScanType,
+    playmatch_rom: PlaymatchRomMatch,
+    remote_enabled: bool,
+) -> LaunchboxRom:
+    """Resolve a ROM's LaunchBox match, by ID where one is known, else by filename."""
+    # An ID already on the ROM is a decision (often a manual match), so it is
+    # never traded for a filename guess.
+    if (
+        remote_enabled
+        and rom.launchbox_id
+        and (
+            scan_type == ScanType.UPDATE
+            or (scan_type == ScanType.UNMATCHED and not rom.launchbox_metadata)
+        )
+    ):
+        return await meta_launchbox_handler.get_rom_by_id(
+            rom.launchbox_id,
+            remote_enabled=True,
+            fs_name=fs_name,
+            platform_slug=platform_slug,
+        )
+
+    launchbox_rom = LaunchboxRom(launchbox_id=None)
+
+    if playmatch_rom["launchbox_id"] is not None and remote_enabled:
+        log.debug(
+            f"{hl(fs_name)} identified by Playmatch as LaunchBox "
+            f"{hl(str(playmatch_rom['launchbox_id']), color=BLUE)} {emoji.EMOJI_ALIEN_MONSTER}",
+            extra=LOGGER_MODULE_NAME,
+        )
+        launchbox_rom = await meta_launchbox_handler.get_rom_by_id(
+            playmatch_rom["launchbox_id"],
+            remote_enabled=True,
+            fs_name=fs_name,
+            platform_slug=platform_slug,
+        )
+
+    # Playmatch suggests an ID the metadata store may not hold, and on some
+    # platforms it answers for nearly every ROM. Letting that miss stand would
+    # strand the whole platform unmatched, so the filename lookup still runs.
+    if not launchbox_rom.get("launchbox_id"):
+        launchbox_rom = await meta_launchbox_handler.get_rom(
+            fs_name,
+            platform_slug,
+            remote_enabled=remote_enabled,
+        )
+
+    return launchbox_rom
+
+
 async def scan_rom(
     scan_type: ScanType,
     platform: Platform,
@@ -726,48 +781,14 @@ async def fetch_launchbox_rom(
                 and rom.platform_slug in LAUNCHBOX_PLATFORM_LIST
             )
         ):
-            if (
-                scan_type == ScanType.UPDATE
-                and rom.launchbox_id
-                and launchbox_remote_enabled
-            ):
-                launchbox_rom = await meta_launchbox_handler.get_rom_by_id(
-                    rom.launchbox_id,
-                    remote_enabled=True,
-                    fs_name=rom_attrs["fs_name"],
-                    platform_slug=platform_slug,
-                )
-            elif (
-                scan_type == ScanType.UNMATCHED
-                and rom.launchbox_id
-                and not rom.launchbox_metadata
-                and launchbox_remote_enabled
-            ):
-                # ID was set manually but metadata was never fetched
-                launchbox_rom = await meta_launchbox_handler.get_rom_by_id(
-                    rom.launchbox_id,
-                    remote_enabled=True,
-                    fs_name=rom_attrs["fs_name"],
-                    platform_slug=platform_slug,
-                )
-            elif playmatch_rom["launchbox_id"] is not None and launchbox_remote_enabled:
-                log.debug(
-                    f"{hl(rom_attrs['fs_name'])} identified by Playmatch as LaunchBox "
-                    f"{hl(str(playmatch_rom['launchbox_id']), color=BLUE)} {emoji.EMOJI_ALIEN_MONSTER}",
-                    extra=LOGGER_MODULE_NAME,
-                )
-                launchbox_rom = await meta_launchbox_handler.get_rom_by_id(
-                    playmatch_rom["launchbox_id"],
-                    remote_enabled=True,
-                    fs_name=rom_attrs["fs_name"],
-                    platform_slug=platform_slug,
-                )
-            else:
-                launchbox_rom = await meta_launchbox_handler.get_rom(
-                    rom_attrs["fs_name"],
-                    platform_slug,
-                    remote_enabled=launchbox_remote_enabled,
-                )
+            launchbox_rom = await resolve_launchbox_rom(
+                rom=rom,
+                fs_name=str(rom_attrs["fs_name"]),
+                platform_slug=platform_slug,
+                scan_type=scan_type,
+                playmatch_rom=playmatch_rom,
+                remote_enabled=launchbox_remote_enabled,
+            )
 
             metadata = launchbox_rom.get("launchbox_metadata")
             if metadata: