#!/usr/bin/env python3
# Copyright: 2026, Maximiliano Curia <maxy@debian.org>
#
# License: ISC
#  Permission to use, copy, modify, and/or distribute this software for any
#  purpose with or without fee is hereby granted, provided that the above
#  copyright notice and this permission notice appear in all copies.
#  .
#  THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
#  REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
#  AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
#  INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
#  LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
#  OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
#  PERFORMANCE OF THIS SOFTWARE.

"""Readers for the shipped license-text data package.

The bulk data (the common-licenses index, the notice headers and the embedded
licence texts) ships as package-data under this directory and is read via
importlib.resources so it works from a wheel as well as a source checkout.
"""

from __future__ import annotations

import functools
import importlib.resources


@functools.cache
def common_licenses_index() -> frozenset[str]:
    """The base-files common-licenses filenames decopy may reference.

    A committed snapshot of the real /usr/share/common-licenses/ entries (the
    GPL/LGPL/GFDL symlinks excluded, explicit versions only), so the map
    validation and runtime stay hermetic and independent of the host.
    """
    text = (
        importlib.resources.files(__package__)
        .joinpath("common_licenses_index.txt")
        .read_text(encoding="utf-8")
    )
    return frozenset(line.strip() for line in text.splitlines() if line.strip())


@functools.cache
def variant_header(name: str) -> str | None:
    """The cleaned notice header for a DEP-5 variant name, or None if none ships.

    Keyed on the full variant name (e.g. "GPL-2" vs "GPL-2+"), since the header
    is what distinguishes the +/only variant. Returns None when no header file
    exists for the name (most licences), so the caller emits the reference alone.
    """
    path = importlib.resources.files(__package__).joinpath("headers", f"{name}.txt")
    if not path.is_file():
        return None
    return path.read_text(encoding="utf-8").strip() or None


@functools.cache
def embedded_license(name: str) -> str | None:
    """The embedded full licence text for a DEP-5 name, or None if none ships.

    Short/popular licences not in common-licenses (Expat, the BSDs, ISC, ...) are
    shipped as verbatim text; returns it as-is (the caller does not wrap it).
    """
    path = importlib.resources.files(__package__).joinpath("licenses", f"{name}.txt")
    if not path.is_file():
        return None
    return path.read_text(encoding="utf-8").strip() or None


@functools.cache
def embedded_exception(label: str) -> str | None:
    """The embedded exception text for a DEP-5 label, or None if none ships.

    Curated exception texts (AutoConf, ClassPath, GCC, ...) are shipped as
    verbatim text; returns it as-is (the caller does not wrap it).
    """
    path = importlib.resources.files(__package__).joinpath("exceptions", f"{label}.txt")
    if not path.is_file():
        return None
    return path.read_text(encoding="utf-8").strip() or None
