# [DEF:report_repository:Module]
# @TIER: STANDARD
# @PURPOSE: Persist and query compliance reports.
# @LAYER: Infra

from typing import Optional, List
from sqlalchemy.orm import Session
from src.models.clean_release import ComplianceReport
from src.core.logger import belief_scope

class ReportRepository:
    """
    @PURPOSE: Encapsulates database operations for ComplianceReport.
    """
    def __init__(self, db: Session):
        self.db = db

    def save(self, report: ComplianceReport) -> ComplianceReport:
        """
        @PURPOSE: Persist a compliance report.
        @POST: Report is committed and refreshed.
        """
        with belief_scope("ReportRepository.save"):
            self.db.add(report)
            self.db.commit()
            self.db.refresh(report)
            return report

    def get_by_id(self, report_id: str) -> Optional[ComplianceReport]:
        """
        @PURPOSE: Retrieve a report by ID.
        """
        with belief_scope("ReportRepository.get_by_id"):
            return self.db.query(ComplianceReport).filter(ComplianceReport.id == report_id).first()

    def get_by_run(self, run_id: str) -> Optional[ComplianceReport]:
        """
        @PURPOSE: Retrieve a report for a specific compliance run.
        """
        with belief_scope("ReportRepository.get_by_run"):
            return self.db.query(ComplianceReport).filter(ComplianceReport.run_id == run_id).first()

    def list_by_candidate(self, candidate_id: str) -> List[ComplianceReport]:
        """
        @PURPOSE: List all reports for a specific candidate.
        """
        with belief_scope("ReportRepository.list_by_candidate"):
            return self.db.query(ComplianceReport).filter(ComplianceReport.candidate_id == candidate_id).all()

# [/DEF:report_repository:Module]