"""
report_generator.py — Opportunity Report Generator
STATUS: DOCUMENTED_ONLY

Assembles an opportunity report from scored, filtered results.
"""

MODULE_STATUS = "documented_only"

import uuid
import datetime


def _now_iso() -> str:
    return datetime.datetime.utcnow().isoformat() + "Z"


def generate_report(target_area: str, opportunities: list,
                    search_terms: list = None, scout_run_id: str = "") -> dict:
    """
    Generate an opportunity report from a list of scored opportunities.
    In documented_only mode, returns a stub report.
    """
    if MODULE_STATUS == "documented_only":
        return {
            "report_id":       str(uuid.uuid4()),
            "version":         "1.0",
            "generated_at":    _now_iso(),
            "scout_run_id":    scout_run_id,
            "target_area":     target_area,
            "search_terms":    search_terms or [],
            "opportunities":   [],
            "total_found":     0,
            "passed_no_go":    0,
            "passed_score":    0,
            "queued_for_review": 0,
            "status":          "documented_only",
            "human_reviewed":  False,
        }
    raise NotImplementedError("Live report generation not yet activated")


def module_status() -> dict:
    return {"module": "report_generator", "status": MODULE_STATUS}