"""Small shared helpers used across scripts."""

from __future__ import annotations

from pathlib import Path
from typing import Sequence


def resolve_path(base: Path, maybe_relative: str) -> Path:
    """Return *maybe_relative* as an absolute path, resolved against *base*."""
    path = Path(maybe_relative).expanduser()
    if path.is_absolute():
        return path
    return (base / path).resolve()


def build_identifier(
    record_path: str | None,
    fallback_paths: Sequence[str],
    sample_idx: int,
) -> str:
    """Build a filesystem-safe identifier from a metadata record."""
    source = record_path or (fallback_paths[0] if fallback_paths else f"sample_{sample_idx}")
    candidate = Path(source)
    tail_parts = [part.replace(".", "-") for part in candidate.parts[-4:]]
    slug = "_".join(tail_parts) if tail_parts else candidate.stem
    return f"{sample_idx:03d}_{slug}"