"""
citation_tracker.py — Citation Registry and Deduplication
STATUS: DOCUMENTED_ONLY

Tracks all citations used in research to prevent duplication and
enable full traceability from finding back to source.
"""

MODULE_STATUS = "documented_only"

import uuid
import datetime

_CITATION_REGISTRY: dict = {}  # url → citation entry


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


def register_citation(url: str, title: str, source_name: str,
                       date: str = "", notes: str = "") -> dict:
    """
    Register a citation URL. Deduplicates by URL.
    Returns existing entry if URL already registered.
    """
    if MODULE_STATUS == "documented_only":
        return {
            "citation_id": str(uuid.uuid4()),
            "url":         url,
            "title":       title,
            "source_name": source_name,
            "date":        date,
            "notes":       notes,
            "registered_at": _now_iso(),
            "use_count":   0,
            "status":      "documented_only",
        }
    if url in _CITATION_REGISTRY:
        entry = _CITATION_REGISTRY[url]
        entry["use_count"] += 1
        return entry
    entry = {
        "citation_id":   str(uuid.uuid4()),
        "url":           url,
        "title":         title,
        "source_name":   source_name,
        "date":          date,
        "notes":         notes,
        "registered_at": _now_iso(),
        "use_count":     1,
    }
    _CITATION_REGISTRY[url] = entry
    return entry


def is_registered(url: str) -> bool:
    return url in _CITATION_REGISTRY


def get_all_citations() -> list:
    if MODULE_STATUS == "documented_only":
        return []
    return list(_CITATION_REGISTRY.values())


def module_status() -> dict:
    return {
        "module":  "citation_tracker",
        "status":  MODULE_STATUS,
        "count":   len(_CITATION_REGISTRY),
    }