"""Abstract base class for all AYN scanners."""

from __future__ import annotations

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

logger = logging.getLogger(__name__)


class BaseScanner(ABC):
    """Common interface that every scanner module must implement.

    Subclasses provide a ``scan`` method whose *target* argument type varies
    by scanner (a file path, a PID, a network connection, etc.).
    """

    # ------------------------------------------------------------------
    # Identity
    # ------------------------------------------------------------------

    @property
    @abstractmethod
    def name(self) -> str:
        """Short, machine-friendly scanner identifier (e.g. ``"file_scanner"``)."""
        ...

    @property
    @abstractmethod
    def description(self) -> str:
        """Human-readable one-liner describing what this scanner does."""
        ...

    # ------------------------------------------------------------------
    # Scanning
    # ------------------------------------------------------------------

    @abstractmethod
    def scan(self, target: Any) -> Any:
        """Run the scanner against *target* and return a result object.

        The concrete return type is defined by each subclass.
        """
        ...

    # ------------------------------------------------------------------
    # Helpers available to all subclasses
    # ------------------------------------------------------------------

    def _log_info(self, msg: str, *args: Any) -> None:
        logger.info("[%s] " + msg, self.name, *args)

    def _log_warning(self, msg: str, *args: Any) -> None:
        logger.warning("[%s] " + msg, self.name, *args)

    def _log_error(self, msg: str, *args: Any) -> None:
        logger.error("[%s] " + msg, self.name, *args)