"""Convenience utilities for plugins consuming PluginForge APIs."""

from typing import Any


def config_diff(old: dict[str, Any], new: dict[str, Any]) -> dict[str, tuple[Any, Any]]:
    """Return a top-level diff of two config dicts as {key: (old, new)}.

    Convenience for on_config_changed implementations that only care about
    "what changed" rather than the full new dict. None is used for keys
    missing from one side; a key whose membership differs is included even
    when both values would compare equal (e.g. both None). Nested dicts are
    compared by equality, not recursively; plugins that need deep diffs
    should implement their own.

    Args:
        old: Previous config dict.
        new: New config dict.

    Returns:
        Dict of changed keys to (old_value, new_value) tuples.
    """
    keys = set(old) | set(new)
    diff: dict[str, tuple[Any, Any]] = {}
    for k in keys:
        a = old.get(k)
        b = new.get(k)
        if a != b or (k in old) != (k in new):
            diff[k] = (a, b)
    return diff