from __future__ import annotations

import json
from pathlib import Path

from ..utils.record_tools import payload_to_records


def load_json_file_records(path: str | Path) -> list[dict[str, object]]:
    """Load one JSON file and normalize it into canonical record dictionaries.

    Parameters
    ----------
    path : str | Path
        Path to a JSON file.

    Returns
    -------
    list[dict[str, object]]
        Normalized records.

    Raises
    ------
    ValueError
        If JSON payload cannot be normalized into records.
    json.JSONDecodeError
        If file content is not valid JSON.
    """
    file_path = Path(path).expanduser()
    payload = json.loads(file_path.read_text(encoding="utf-8"))
    return payload_to_records(payload)
