"""Shared JSON / JSONL I/O and canonical serialization helpers."""
from __future__ import annotations

import json
from pathlib import Path
from typing import Any


def load_json(path: Path) -> dict[str, Any]:
    """Read a JSON file and return its contents as a dict."""
    return json.loads(path.read_text(encoding="utf-8"))


def load_jsonl(path: Path) -> list[dict[str, Any]]:
    """Read a JSONL file and return a list of dicts (skips blank lines)."""
    rows: list[dict[str, Any]] = []
    with path.open("r", encoding="utf-8") as fh:
        for line in fh:
            s = line.strip()
            if s:
                rows.append(json.loads(s))
    return rows


def write_jsonl(path: Path, rows: list[dict[str, Any]], *, append: bool = False) -> None:
    """Write a list of dicts as JSONL (sorted keys for deterministic output)."""
    path.parent.mkdir(parents=True, exist_ok=True)
    mode = "a" if append else "w"
    with path.open(mode, encoding="utf-8") as fh:
        for row in rows:
            fh.write(json.dumps(row, sort_keys=True, ensure_ascii=False) + "\n")


def stable_json(obj: Any) -> str:
    """Deterministic JSON string (sorted keys, compact separators, ASCII-safe)."""
    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True)


def canonical_json(obj: Any) -> str:
    """Deterministic JSON preserving raw non-ASCII characters."""
    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False)


def canonical_json_bytes(obj: Any) -> bytes:
    """Deterministic JSON as bytes — suitable for hashing."""
    return canonical_json(obj).encode("utf-8")