from __future__ import annotations

import warnings
from pathlib import Path
from typing import Any

LEGACY_HINTS = {
    ("experiment", "random_seed"): "use experiment.seed",
    ("entrypoint", "script"): "use entrypoint.command",
    ("backend", "type"): "use backend.kind",
}


def warn_legacy_manifest(payload: Any, manifest_path: Path) -> None:
    if not isinstance(payload, dict):
        return

    for (section, key), hint in LEGACY_HINTS.items():
        section_value = payload.get(section)
        if isinstance(section_value, dict) and key in section_value:
            warnings.warn(
                (
                    f"legacy manifest key detected in {manifest_path}: "
                    f"{section}.{key} is deprecated; {hint}."
                ),
                RuntimeWarning,
                stacklevel=2,
            )
