"""Filesystem path helpers — destination derivation, hash-suffixed names."""

from pathlib import Path


def derive_subdir(source_path: Path, import_root: Path) -> str:
    """Returns the relative subdirectory of source_path under import_root.

    The top-level folder name is treated as the 'artist' bucket. Nested
    paths preserve hierarchy.

        import_root=/import
        source_path=/import/Alice/sub/x.png -> "Alice/sub"
        source_path=/import/Alice/x.png      -> "Alice"
        source_path=/import/x.png             -> ""
    """
    try:
        rel = source_path.parent.relative_to(import_root)
    except ValueError:
        return ""
    return str(rel) if str(rel) != "." else ""


def hash_suffixed_name(stem: str, sha256_hex: str, ext: str) -> str:
    """Builds 'stem__<first10ofhash><ext>'.

    Examples:
        hash_suffixed_name("photo", "abcdef1234567890...", ".png")
            -> "photo__abcdef1234.png"
    """
    return f"{stem}__{sha256_hex[:10]}{ext}"


def derive_top_level_artist(source_path: Path, import_root: Path) -> str | None:
    """Returns the top-level folder name under import_root, or None if the
    file is directly in import_root.
    """
    subdir = derive_subdir(source_path, import_root)
    if not subdir:
        return None
    return subdir.split("/", 1)[0]