"""A voluptuous mirror faithful enough to SEE a dropped schema default.

The test environment never installs voluptuous (the config-flow tests import
``config_flow`` against import-only stubs), so the harness has to model the two
behaviours the flow schemas depend on:

* ``Optional(field, default=value)`` / ``Required(field, default=value)`` carry
  that default on the KEY object;
* keys compare by FIELD NAME only — real ``voluptuous.Marker.__eq__`` is
  ``self.schema == other`` (no class check at all), so
  ``Optional("x") == Required("x")`` is True, and ``__hash__`` is
  ``hash(self.schema)``. A later re-declaration of the same field therefore
  collides with the FIRST key object, so a default added by a second
  declaration is silently dropped.

That second property is exactly how the t33 F-A discovery-prefill bug hid from
the suite: the old stubs reduced every key to its bare string, so a schema
whose host key carried no default looked identical to one that carried the
discovered address. ``TestVoluptuousMirrorContract`` in
``tests/test_config_flow_ux.py`` pins both properties so the harness itself
cannot regress into blindness.
"""

from __future__ import annotations

UNDEFINED = object()
"""Sentinel for "this key declares no default" (real ``voluptuous.UNDEFINED``)."""


class Marker:
    """Stand-in for ``voluptuous.Marker`` (the ``Required``/``Optional`` base)."""

    def __init__(self, schema, default=UNDEFINED):
        self.schema = schema
        self.default = default

    def __hash__(self):
        # real Marker hashes the field name only
        return hash(self.schema)

    def __eq__(self, other):
        # real Marker.__eq__ is `self.schema == other`: the FIELD is the whole
        # comparison — no class check, so Optional("x") == Required("x") (and
        # even Marker("x") == "x") is True. That is what makes a re-declaration
        # of a field collide with the first key object and drop its default.
        return self.schema == other

    def __repr__(self):
        return f"<{type(self).__name__} {self.schema!r} default={self.default!r}>"


class Required(Marker):
    """Stand-in for ``voluptuous.Required``."""


class Optional(Marker):
    """Stand-in for ``voluptuous.Optional``."""


def install(vol) -> None:
    """Wire the mirror onto a stub ``voluptuous`` module object."""
    vol.UNDEFINED = UNDEFINED
    vol.Marker = Marker
    vol.Required = Required
    vol.Optional = Optional
    vol.Schema = lambda schema: schema


def defaults_by_key(schema_dict) -> dict:
    """``{field: default}`` for a schema declared with mirror keys."""
    return {key.schema: key.default for key in declared_keys(schema_dict)}


def declared_keys(schema_dict) -> list:
    """The schema's marker keys, in declaration order.

    Raises on a non-marker key: a bare string key means the harness (or the
    code under test) lost the KEY structure this mirror exists to check.
    Test-harness bookkeeping keys (``__suggested__`` and friends) are skipped.
    """
    keys = []
    for key in schema_dict:
        if isinstance(key, Marker):
            keys.append(key)
            continue
        if isinstance(key, str) and key.startswith("__"):
            continue
        raise AssertionError(f"schema key {key!r} is not a voluptuous marker")
    return keys


def declared_fields(schema_dict) -> list:
    """The field names of a schema, in declaration order."""
    return [key.schema for key in declared_keys(schema_dict)]