steam-backlog-enforcer/steam_backlog_enforcer/_scanning_candidates.py

"""Candidate selection helpers for ``scan`` and ``pick_next_game``.

Split out of :mod:`steam_backlog_enforcer.scanning` to keep both files under
the 250-line cap. Leaf helpers: nothing here calls back into ``scanning``.
"""

from __future__ import annotations

import logging
from typing import TYPE_CHECKING

from steam_backlog_enforcer._scanning_confidence import (
    _candidate_passes_hltb_confidence,
)
from steam_backlog_enforcer.game_install import _echo
from steam_backlog_enforcer.protondb import (
    ProtonDBRating,
    fetch_protondb_ratings,
)

if TYPE_CHECKING:
    from steam_backlog_enforcer.steam_api import GameInfo

logger = logging.getLogger(__name__)

_PROTONDB_BATCH_SIZE = 20

_PICK_LIST_SIZE = 10


def _sort_key(g: GameInfo) -> tuple[int, float]:
    """Sort by known HLTB time (shortest first), then unknown games."""
    if g.completionist_hours > 0:
        return (0, g.completionist_hours)
    return (1, hash(g.name.lower().encode().hex()))


def _pick_playable_candidate(
    candidates: list[GameInfo],
) -> GameInfo | None:
    """Return the first candidate with an acceptable ProtonDB rating.

    Checks candidates in batches (sorted by HLTB hours, shortest first).
    Games rated silver-or-worse, or gold-trending-down, are skipped.
    """
    offset = 0
    while offset < len(candidates):
        batch = candidates[offset : offset + _PROTONDB_BATCH_SIZE]
        app_ids = [g.app_id for g in batch]
        ratings = fetch_protondb_ratings(app_ids)

        for game in batch:
            rating = ratings.get(game.app_id, ProtonDBRating(app_id=game.app_id))
            if rating.is_playable:
                if offset > 0 or game is not batch[0]:
                    _echo(
                        f"  Skipped {offset + batch.index(game)} game(s) "
                        f"with poor Linux compatibility"
                    )
                return game
            logger.info(
                "Skipping %s (AppID=%d): ProtonDB %s (trending %s)",
                game.name,
                game.app_id,
                rating.tier,
                rating.trending_tier,
            )

        offset += _PROTONDB_BATCH_SIZE

    return None


def _collect_qualified_candidates(
    candidates: list[GameInfo],
) -> tuple[list[GameInfo], int, int]:
    """Collect up to _PICK_LIST_SIZE playable, HLTB-confident candidates."""
    qualified: list[GameInfo] = []
    confidence_skipped = 0
    linux_skipped = 0
    for game in candidates:
        if len(qualified) >= _PICK_LIST_SIZE:
            break
        if not _candidate_passes_hltb_confidence(game):
            confidence_skipped += 1
            continue
        playable = _pick_playable_candidate([game])
        if playable is not None:
            qualified.append(playable)
        else:
            linux_skipped += 1
    return qualified, confidence_skipped, linux_skipped


def _pick_next_shortest_candidate(
    candidates: list[GameInfo],
) -> tuple[GameInfo | None, int, int]:
    """Pick next game by checking confidence one candidate at a time.

    The list must be pre-sorted by desired priority (shortest first).
    """
    confidence_skipped = 0
    linux_skipped = 0
    for game in candidates:
        if not _candidate_passes_hltb_confidence(game):
            confidence_skipped += 1
            continue

        # Reuse existing ProtonDB compatibility gate for one candidate.
        playable = _pick_playable_candidate([game])
        if playable is not None:
            if linux_skipped > 0:
                _echo(
                    f"  Skipped {linux_skipped} game(s) with poor Linux compatibility"
                )
            return playable, confidence_skipped, linux_skipped
        linux_skipped += 1

    if linux_skipped > 0:
        _echo(f"  Skipped {linux_skipped} game(s) with poor Linux compatibility")
    return None, confidence_skipped, linux_skipped


def _collect_top_candidates(
    candidates: list[GameInfo],
    n: int = 3,
) -> tuple[list[GameInfo], int, int]:
    """Collect up to n candidates that pass the Linux compatibility gate.

    Args:
        candidates: Pre-sorted list of candidate games.
        n: Maximum number of qualified games to collect.

    Returns:
        Tuple of (qualified_list, conf_skipped, linux_skipped).
    """
    qualified: list[GameInfo] = []
    linux_skipped = 0
    for game in candidates:
        if len(qualified) >= n:
            break
        playable = _pick_playable_candidate([game])
        if playable is not None:
            qualified.append(playable)
        else:
            linux_skipped += 1
    if linux_skipped > 0:
        _echo(f"  Skipped {linux_skipped} game(s) with poor Linux compatibility")
    return qualified, 0, linux_skipped