"""``ReportWriter`` ABC.

See: ``DESIGN.md`` §3.7 + ``mgf.apiprobe.reporting.__init__`` for the
roadmap. Each concrete writer's :meth:`write` returns its native
output type (str / dict / etc.) — the ABC declares the shape but
doesn't constrain the return type, since different consumers want
different shapes (a Slack writer returns dict, a markdown writer
returns str, …).
"""

from __future__ import annotations

from abc import ABC, abstractmethod
from typing import TYPE_CHECKING, Any

if TYPE_CHECKING:
    from mgf.apiprobe.core.report import Report


class ReportWriter(ABC):
    """Abstract base for report writers."""

    @abstractmethod
    def write(self, report: Report) -> Any:
        """Render ``report`` and return the result.

        Concrete writers narrow the return type:

        - :class:`HumanReportWriter.write` → ``str``
        - :class:`JsonReportWriter.write` → ``dict[str, Any]``

        Override ``write`` rather than introducing additional public
        methods so consumers can iterate writers polymorphically::

            for writer in writers:
                print(writer.write(report))
        """


__all__ = ["ReportWriter"]
