"""Utilities for detecting sidecar thumbnail image files next to a video."""

import os


def detect_sidecar_image(video_path: str) -> str | None:
    """Return the path to a sidecar image file if one exists next to the video.

    Looks for files with the same stem as the video but with image extensions
    (.jpg, .jpeg, .png, .tiff, .tif). Returns the first match found, or None.

    Priority order: .jpg, .jpeg, .png, .tiff, .tif
    """
    video_dir = os.path.dirname(os.path.abspath(video_path))
    video_stem = os.path.splitext(os.path.basename(video_path))[0]

    for ext in [".jpg", ".jpeg", ".png", ".tiff", ".tif"]:
        candidate = os.path.join(video_dir, f"{video_stem}{ext}")
        if os.path.isfile(candidate):
            return candidate
    return None
