MeshTerm/packaging/notices.py

# SPDX-License-Identifier: Apache-2.0
"""Builds ``THIRD-PARTY-NOTICES.txt``: every license the frozen build has to carry.

A one-file PyInstaller build is a *copy* of MeshTerm and of everything MeshTerm imports
at runtime — Apache-2.0 §4(a)/(d) want MeshTerm's own LICENSE and NOTICE distributed
with every such copy, and each MIT/BSD/PSF dependency wants its own notice kept with
copies too. Before this module existed, the spec (``packaging/meshterm.spec``) bundled
neither: the five installers carried the bundled font's license and nothing else.

This is deliberately a *generator*, not a checked-in file: a checked-in copy invites
drift the moment a dependency changes hands or its license text, silently, the next time
someone bumps a version pin. It runs at build time (see the spec) and again in
:mod:`tests.test_notices`, walking the actual runtime dependency closure of the
``mesh-term`` distribution installed in *this* interpreter — so a build's notices always
match what that build actually bundled, on whichever platform built it. A dependency
only one platform needs (a bleak backend, ``tomli`` below 3.11) shows up only in that
platform's notices, because it was never in the other platforms' closures to begin with.

Two things get no exception:

* A dependency with no discoverable license file fails the whole build, loudly, rather
  than shipping quietly without one — see :data:`_VENDORED_LICENSE_GAPS` for the one
  currently-known exception, and why it is a documented fix rather than a silent one.
* Python's own PSF license is always the first entry, found the same way the ``license``
  builtin finds it (reusing its own candidate-file search, not re-deriving the layout it
  already knows) — venv or not, Windows or POSIX, a future interpreter layout it wasn't
  written against still resolves correctly, or fails loudly instead of guessing wrong.
"""

from __future__ import annotations

import builtins
import platform
import sys
from dataclasses import dataclass
from importlib.metadata import Distribution, PackagePath, distribution
from pathlib import Path

from packaging.markers import default_environment
from packaging.requirements import Requirement
from packaging.utils import canonicalize_name

#: The distribution this build actually ships — see ``pyproject.toml``. Not a parameter
#: callers are expected to vary: a notices file for a *different* distribution's closure
#: would not describe what this build bundles.
ROOT_DISTRIBUTION = "mesh-term"

#: A handful of dependencies whose wheels on PyPI carry a license *classifier* or
#: *expression* but were built and uploaded without the license text itself — verified
#: by inspecting each wheel directly (``unzip -l``), not assumed from the metadata
#: alone. Their real text is vendored here, unmodified, from each project's own
#: repository — see each vendored file's own header for the exact source and the date
#: it was pulled. Nothing else gets this treatment: a dependency not listed here still
#: fails the build the moment its wheel has the same gap, which is the point — this is
#: a documented fix for known, verified problems, not a general escape hatch for an
#: unknown future one.
#:
#: * ``pyserial`` — no newer release exists to bump to; 3.5 (2020) is still the latest
#:   pyserial on PyPI, and its wheel has never shipped a LICENSE, COPYING, or NOTICE
#:   file of any kind.
#: * The nine ``winrt-*`` packages — bleak's Windows BLE backend (``bleak.backends.
#:   winrt``) pulls these in only on ``sys_platform == "win32"``, so they only appear
#:   in a Windows build's closure. All nine are generated and published together by the
#:   pywinrt project and share the one upstream license file, which none of their
#:   wheels include.
#: * ``pyobjc-core`` and ``pyobjc-framework-libdispatch`` — two of the four pyobjc
#:   packages bleak's macOS BLE backend (``bleak.backends.corebluetooth``) pulls in on
#:   ``sys_platform == "darwin"``, so they only appear in a macOS build's closure, which
#:   is where the 0.3.3 release build caught them. Their 12.2.2 wheels ship no license
#:   file; the other two (Cocoa, CoreBluetooth) do, and are read from their dist-info
#:   like everything else. All four come from the one pyobjc repository and its single
#:   MIT text.
_VENDORED_LICENSE_GAPS: dict[str, tuple[str, ...]] = {
    "pyserial": ("vendored-licenses/pyserial-LICENSE.txt",),
    "pyobjc-core": ("vendored-licenses/pyobjc-LICENSE.txt",),
    "pyobjc-framework-libdispatch": ("vendored-licenses/pyobjc-LICENSE.txt",),
    "winrt-runtime": ("vendored-licenses/pywinrt-LICENSE.txt",),
    "winrt-windows-devices-bluetooth": ("vendored-licenses/pywinrt-LICENSE.txt",),
    "winrt-windows-devices-bluetooth-advertisement": ("vendored-licenses/pywinrt-LICENSE.txt",),
    "winrt-windows-devices-bluetooth-genericattributeprofile": (
        "vendored-licenses/pywinrt-LICENSE.txt",
    ),
    "winrt-windows-devices-enumeration": ("vendored-licenses/pywinrt-LICENSE.txt",),
    "winrt-windows-devices-radios": ("vendored-licenses/pywinrt-LICENSE.txt",),
    "winrt-windows-foundation": ("vendored-licenses/pywinrt-LICENSE.txt",),
    "winrt-windows-foundation-collections": ("vendored-licenses/pywinrt-LICENSE.txt",),
    "winrt-windows-storage-streams": ("vendored-licenses/pywinrt-LICENSE.txt",),
}

#: Conventional bare-directory license filenames a pre-PEP-639 wheel might bundle at its
#: dist-info root without ever declaring them in metadata. Matched case-insensitively by
#: prefix, so ``LICENSE``, ``LICENSE.txt``, ``LICENSE-MIT`` and ``License.rst`` all hit.
_CONVENTIONAL_LICENSE_PREFIXES = ("LICENSE", "LICENCE", "COPYING", "NOTICE")


class NoticesError(RuntimeError):
    """A license notice this build needs could not be found.

    Raised instead of quietly omitting an entry — a bundle that silently drops a notice
    is the exact failure mode this module exists to prevent, so a missing one stops the
    build rather than shipping.
    """


@dataclass(frozen=True)
class Notice:
    """One entry in the generated notices file.

    Attributes:
        name: The distribution's own name, as PyPI (or, for Python itself, the
            ``platform`` module) spells it — not canonicalised, so the rendered file
            reads the way a person searching for the package by its usual name expects.
        version: The installed version.
        summary: The license expression or classifier(s) this distribution declares,
            for the header line. Never the license text itself — that is :attr:`text`.
        text: The verbatim license text (one or more files, concatenated), unmodified.
    """

    name: str
    version: str
    summary: str
    text: str


def _python_notice() -> Notice:
    """Return the PSF license notice for the interpreter running this build.

    Reuses the candidate-file search the ``license`` builtin itself does
    (``site.setcopyright`` builds it from ``os.path.dirname(os.__file__)`` plus the
    Windows install-root layout, the POSIX lib layout, and a same-directory fallback)
    rather than re-deriving those paths and risking a layout it didn't anticipate. This
    resolves correctly from inside a venv too, without any venv-specific casing here,
    because ``os.__file__`` always points at the *base* interpreter's standard library.

    Raises:
        NoticesError: No candidate file exists, and the ``license`` builtin's own
            fallback text (a pointer to a URL, not license text) is not good enough to
            ship as a notice.
    """
    printer = getattr(builtins, "license", None)
    if printer is None:
        # `site` normally installs this at interpreter startup; it is only missing if
        # the interpreter was started with `-S`. Install it ourselves rather than give
        # up — a build environment that happens to do this shouldn't lose the notice.
        import site

        site.setcopyright()
        printer = builtins.license
    candidates = getattr(printer, "_Printer__filenames", None)
    if not candidates:
        raise NoticesError(
            "could not find Python's own license: the 'license' builtin exposes no "
            "candidate file list (unexpected interpreter internals)"
        )
    for candidate in candidates:
        path = Path(candidate)
        if path.is_file():
            return Notice(
                name="Python",
                version=platform.python_version(),
                summary="PSF License Agreement",
                text=path.read_text(encoding="utf-8"),
            )
    raise NoticesError(
        "could not find Python's own license text; looked in: "
        + ", ".join(str(c) for c in candidates)
    )


def _license_summary(dist: Distribution) -> str:
    """The short "which license" line for a distribution's header.

    Prefers the PEP 639 ``License-Expression`` (the SPDX expression a modern build
    backend writes), then the ``License ::`` classifiers older packages rely on
    instead, then the legacy free-text ``License`` field only if it is short enough to
    be a label rather than a pasted-in license itself. "unspecified" is a last resort,
    not a failure: an unclear *label* is a readability problem, unlike a missing license
    *file*, which is a compliance one and raises instead (see :func:`_license_text`).
    """
    metadata = dist.metadata
    expression = metadata.get("License-Expression")
    if expression:
        return expression
    classifiers = [c for c in metadata.get_all("Classifier") or [] if c.startswith("License")]
    if classifiers:
        return "; ".join(classifiers)
    legacy = metadata.get("License")
    if legacy and "\n" not in legacy and len(legacy) <= 100:
        return legacy
    return "unspecified"


def _dist_info_files(dist: Distribution) -> list[PackagePath]:
    """Every file RECORD lists under this distribution's own ``.dist-info`` directory.

    Built from :attr:`Distribution.files` rather than the private
    ``Distribution._path`` some tools reach for, so this stays correct however a future
    ``importlib.metadata`` lays a distribution's metadata out on disk — it only ever
    asks the distribution for files it already told us it owns.
    """
    files = dist.files or []
    return [f for f in files if str(f).split("/", 1)[0].endswith(".dist-info")]


def _license_files(dist: Distribution) -> list[PackagePath]:
    """The dist-info files that make up this distribution's license text.

    PEP 639's ``License-File`` metadata entries win when present, matched by basename
    since a build backend is free to nest them (hatchling puts every one under a
    ``licenses/`` subdirectory; other tools leave them at the dist-info root). Lacking
    any declaration at all — true of most wheels built before 2024 — falls back to
    whatever the wheel happened to bundle at the dist-info root under a conventional
    name, which is the same thing a person skimming the directory would go looking for.
    """
    dist_files = _dist_info_files(dist)
    declared = dist.metadata.get_all("License-File") or []
    if declared:
        wanted = [Path(name).name for name in declared]
        by_name = {Path(str(f)).name: f for f in dist_files}
        # Declared order, not RECORD's, so the concatenated text below reads in the
        # order the package's own author declared it.
        return [by_name[name] for name in wanted if name in by_name]
    return sorted(
        (
            f
            for f in dist_files
            # dist-info root only — one path segment below the directory itself. A
            # nested `licenses/` folder with no metadata declaration pointing at it
            # isn't a convention to guess at.
            if str(f).count("/") == 1
            and Path(str(f)).name.upper().startswith(_CONVENTIONAL_LICENSE_PREFIXES)
        ),
        key=str,
    )


def _vendored_license_files(canonical_name: str) -> list[Path]:
    """Local fallback license text for a dependency whose wheel ships none at all."""
    here = Path(__file__).parent
    return [here / rel for rel in _VENDORED_LICENSE_GAPS.get(canonical_name, ())]


def _license_text(dist: Distribution, canonical_name: str) -> str:
    """The concatenated, verbatim license text for one distribution.

    Raises:
        NoticesError: Nothing was found in the dist-info and nothing is vendored for
            it either. Nothing downstream is in a position to notice a quietly-missing
            notice, so this stops the build instead of shipping a gap.
    """
    matches = _license_files(dist)
    if matches:
        return "\n\n".join(
            f"--- {Path(str(f)).name} ---\n{f.locate().read_text(encoding='utf-8')}"
            for f in matches
        )
    vendored = _vendored_license_files(canonical_name)
    if vendored:
        for path in vendored:
            if not path.is_file():
                raise NoticesError(
                    f"{dist.metadata['Name']} {dist.version}: vendored license file "
                    f"missing at {path} (see _VENDORED_LICENSE_GAPS)"
                )
        return "\n\n".join(
            f"--- {path.name} ---\n{path.read_text(encoding='utf-8')}" for path in vendored
        )
    raise NoticesError(
        f"{dist.metadata['Name']} {dist.version}: no license file found in its "
        "dist-info (checked declared License-File entries and "
        "LICENSE*/LICENCE*/COPYING*/NOTICE* at the dist-info root) and none is "
        "vendored for it either — a bundle would ship this dependency without its "
        "license notice"
    )


def dependency_closure(root: str = ROOT_DISTRIBUTION) -> list[Distribution]:
    """The installed distributions ``root`` actually pulls in on this interpreter.

    Walks ``Requires-Dist`` recursively (``importlib.metadata`` exposes it as
    :attr:`Distribution.requires`), evaluating each requirement's environment marker
    against *this* interpreter and platform — with ``extra`` forced to the empty
    string, which is what "no extras requested" means to a marker (a bare
    ``pip install mesh-term`` asks for none), so a requirement guarded by
    ``extra == "dev"`` reads as false and the ``dev`` extra's own tooling (pytest,
    pytest-asyncio, ruff) never enters the closure. A marker that instead names a
    platform or Python version this interpreter doesn't match is excluded the same
    way — the point of evaluating markers at all rather than reading every
    ``Requires-Dist`` line flat.

    Returns:
        Distributions sorted by their canonical (PEP 503) name, deterministically, and
        never including ``root`` itself — MeshTerm's own license is ``LICENSE`` and
        ``NOTICE``, not a third-party notice.
    """
    environment = default_environment()
    environment["extra"] = ""
    root_key = canonicalize_name(root)
    seen: dict[str, Distribution] = {}
    pending = [root]
    while pending:
        name = pending.pop()
        key = canonicalize_name(name)
        if key in seen:
            continue
        dist = distribution(name)
        seen[key] = dist
        for raw in dist.requires or ():
            requirement = Requirement(raw)
            if requirement.marker is not None and not requirement.marker.evaluate(environment):
                continue
            pending.append(requirement.name)
    seen.pop(root_key, None)
    return sorted(seen.values(), key=lambda d: canonicalize_name(d.metadata["Name"]))


def collect_notices(root: str = ROOT_DISTRIBUTION) -> list[Notice]:
    """All notices this build's ``THIRD-PARTY-NOTICES.txt`` should carry.

    Python's own PSF notice always comes first — Python is not a PyPI distribution
    ``Requires-Dist`` can name, so it can never turn up in :func:`dependency_closure`.
    Every dependency follows it, sorted by name, for a stable, reviewable diff between
    one build's notices file and the next.
    """
    notices = [_python_notice()]
    for dist in dependency_closure(root):
        canonical = canonicalize_name(dist.metadata["Name"])
        notices.append(
            Notice(
                name=dist.metadata["Name"],
                version=dist.version,
                summary=_license_summary(dist),
                text=_license_text(dist, canonical),
            )
        )
    return notices


_HEADER = """\
Third-party notices
====================

This build of MeshTerm bundles the packages listed below as part of its Python
runtime. Each entry below reproduces that package's own license, verbatim and
unmodified, as its terms require. MeshTerm's own license and copyright notice are
in the LICENSE and NOTICE files bundled alongside this one, not repeated here.

Generated by packaging/notices.py at build time -- do not edit by hand.
"""

_RULE = "=" * 78


def render(notices: list[Notice]) -> str:
    """Render ``notices`` as one deterministic, newline-terminated UTF-8 document."""
    blocks = [_HEADER]
    for notice in notices:
        header = f"{notice.name} {notice.version} — {notice.summary}"
        blocks.append(f"{_RULE}\n{header}\n{_RULE}\n\n{notice.text.rstrip()}\n")
    return "\n".join(blocks).rstrip("\n") + "\n"


def write_third_party_notices(path: str | Path, root: str = ROOT_DISTRIBUTION) -> Path:
    r"""Generate and write ``THIRD-PARTY-NOTICES.txt`` to ``path``.

    Written as raw UTF-8 bytes rather than through text mode, so a Windows build
    doesn't translate the ``\n`` line endings to ``\r\n`` — the file is meant to be
    byte-identical in content across the platforms that each build it.

    Returns:
        ``path``, resolved to a :class:`~pathlib.Path`, for the caller's convenience.
    """
    path = Path(path)
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_bytes(render(collect_notices(root)).encode("utf-8"))
    return path


def main(argv: list[str] | None = None) -> int:
    """CLI entry point: ``python packaging/notices.py OUTPUT_PATH``."""
    args = sys.argv[1:] if argv is None else argv
    if len(args) != 1:
        print("usage: notices.py OUTPUT_PATH", file=sys.stderr)
        return 2
    written = write_third_party_notices(args[0])
    print(f"wrote {written}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())