"""Abstract base classes for meshulash-guard scanners and normalizers.

Subclasses must implement:
- BaseScanner.to_guardline_spec() — translate scanner config into a guardline
  spec dict for /api/security/scan.
- BaseNormalizer.to_normalizer_spec() — translate normalizer config into a
  server-side normalizer spec (v2 server support, contract defined here in v1).

Attempting to instantiate BaseScanner or BaseNormalizer directly raises
TypeError at construction time (Python abc enforcement).
"""

from abc import ABC, abstractmethod


class BaseScanner(ABC):
    """Base class for all scanners.

    Each scanner translates its configuration into a guardline spec the
    security server understands. The Guard class calls to_guardline_spec()
    to build the guardline_specs payload for /api/security/scan.
    """

    @abstractmethod
    def to_guardline_spec(self) -> dict:
        """Translate scanner config into a guardline_spec dict.

        Returns:
            dict: A single guardline spec suitable for inclusion in the
                  guardline_specs payload sent to /api/security/scan.
        """


class BaseNormalizer(ABC):
    """Base class for normalizers.

    Normalizers pre-process text before scanning (e.g., unicode normalization,
    invisible character stripping, homoglyph normalization). The contract is
    defined in v1; server-side normalizer execution is v2.
    """

    @abstractmethod
    def to_normalizer_spec(self) -> dict:
        """Translate normalizer config into a server-side normalizer spec.

        Returns:
            dict: A normalizer spec suitable for the normalizers payload
                  sent to /api/security/scan (v2).
        """
