config.py

from __future__ import annotations

from dataclasses import dataclass, field
from pathlib import Path
from typing import Any

import yaml


@dataclass(slots=True)
class LoadedConfig:
    raw: dict[str, Any]
    path: Path


def load_config(path: str | Path) -> LoadedConfig:
    config_path = Path(path)
    with config_path.open("r", encoding="utf-8") as handle:
        raw = yaml.safe_load(handle) or {}
    if not isinstance(raw, dict):
        raise ValueError(f"Config at {config_path} must be a mapping.")
    return LoadedConfig(raw=raw, path=config_path)


def ensure_directory(path: str | Path, *, allow_existing: bool = True) -> Path:
    directory = Path(path)
    if directory.exists() and not allow_existing:
        raise FileExistsError(f"Refusing to overwrite existing directory: {directory}")
    directory.mkdir(parents=True, exist_ok=allow_existing)
    return directory