"""Deprecated config field registry.

To deprecate a top-level config field, add one entry to ``_DEPRECATED_FIELDS``:

- **Renamed field** — set ``replacement`` to the new field name; the value is
  forwarded automatically so existing code keeps working::

      "old_name": DeprecatedField(
          replacement="new_name",
          message="'old_name' is deprecated. Use 'new_name' instead.",
      ),

- **Removed field** — set ``replacement=None`` and point users to the
  alternative (CLI command, docs link, etc.)::

      "engine": DeprecatedField(
          replacement=None,
          message="'engine' was removed. Use 'rai reasoners:create' to manage engines.",
      ),

When a field is fully removed (e.g. its TOML conversion path is gone), delete
its entry here — nothing else needs to change.
"""

from dataclasses import dataclass


@dataclass(frozen=True)
class DeprecatedField:
    """Describes a deprecated top-level config field.

    Parameters
    ----------
    message : str
        Warning message shown to the user.
    replacement : str or None
        New field name to map the value to, or ``None`` if the field was
        removed entirely (e.g. functionality moved to the CLI).
    """
    message: str
    replacement: str | None = None


# Register all deprecated top-level config fields here.
_DEPRECATED_FIELDS: dict[str, DeprecatedField] = {
    "use_direct_access": DeprecatedField(
        replacement="direct_access",
        message="'use_direct_access' is deprecated and will be removed in a future release.",
    ),
}
