"""Abstract base class for all collectors."""

from __future__ import annotations

import json
from abc import ABC, abstractmethod
from pathlib import Path
from typing import Any


class BaseCollector(ABC):
    """Collects raw data from the target repository for a single module."""

    module_name: str = "base"

    def __init__(self, repo_path: Path) -> None:
        self.repo_path = repo_path

    @abstractmethod
    def collect(self) -> dict[str, Any]:
        """
        Perform collection and return a raw data dict.
        The dict is serialised to .sentinel/collected/<module>.json.
        """

    def save(self, data: dict[str, Any], artifacts_dir: Path) -> Path:
        """Persist collected data as JSON for the analysis phase."""
        artifacts_dir.mkdir(parents=True, exist_ok=True)
        out = artifacts_dir / f"{self.module_name}.json"
        out.write_text(json.dumps(data, indent=2, default=str))
        return out
