"""
naalscan - Python Dependency Vulnerability Scanner
===================================================

Your own vulnerability scanning library.

Usage:
    import naalscan

    # Scan a requirements.txt
    results = naalscan.scan(open("requirements.txt").read())
    print(f"Found {results['total_vulnerabilities']} vulnerabilities")

    # Check a single package
    vulns = naalscan.check("django", "2.2.12")
    for v in vulns:
        print(v["cve"], v["severity"], v["description"])
"""

from .scanner import NaalScanner

# Create a default scanner instance using the bundled database
_default = NaalScanner()


def scan(requirements_text: str) -> dict:
    """
    Scan requirements.txt content for known vulnerabilities.

    Args:
        requirements_text: Raw string content of your requirements.txt file

    Returns:
        dict with keys:
            total_packages        - how many packages were found in the file
            total_vulnerabilities - total number of CVEs found
            vulnerable_count      - number of packages with vulnerabilities
            safe_count            - number of clean packages
            vulnerabilities       - list of vulnerability dicts
            vulnerable_packages   - list of vulnerable package names
            safe_packages         - list of clean package names

    Example:
        with open("requirements.txt") as f:
            results = naalscan.scan(f.read())

        for v in results["vulnerabilities"]:
            print(f"{v['package']} {v['version']} - {v['cve']}")
            print(f"  Severity : {v['severity']}")
            print(f"  CWE      : {v['cwe']}")
            print(f"  Fix      : update to {v['fixed_version']}")
            print(f"  Detail   : {v['description']}")
    """
    return _default.scan(requirements_text)


def check(package_name: str, package_version: str) -> list:
    """
    Check a single package version for vulnerabilities.

    Args:
        package_name:    e.g. "django"
        package_version: e.g. "2.2.12"

    Returns:
        List of vulnerability dicts. Empty list = clean.

    Example:
        vulns = naalscan.check("requests", "2.24.0")
        if vulns:
            print(f"Found {len(vulns)} vulnerabilities!")
    """
    return _default.check(package_name, package_version)


def stats() -> dict:
    """
    Return statistics about the loaded vulnerability database.

    Returns:
        {
            packages_tracked:      int,
            total_vulnerabilities: int,
        }
    """
    return _default.stats()


def load_extra_db(path: str):
    """
    Load an additional vulnerability database (e.g. Safety DB's insecure_full.json)
    and merge it with the bundled database for more coverage.

    Args:
        path: Path to the JSON file in Safety DB format

    Example:
        naalscan.load_extra_db("insecure_full.json")
        results = naalscan.scan(requirements_text)
    """
    global _default
    _default = NaalScanner(extra_db_path=path)


# Expose the class too for advanced use
__all__ = ["scan", "check", "stats", "load_extra_db", "NaalScanner"]
__version__ = "1.0.0"
__author__  = "naalscan"
