Skip to content

💫 Toolkit to help you get started with SDD or any other process!

5.0 KB
Raw Blame
"""Validate and select display-only integration catalog release metadata."""

from __future__ import annotations

from typing import Any

from packaging.version import InvalidVersion, Version

from . import IntegrationCatalogError

_RELEASE_FIELDS = frozenset(
    {
        "name",
        "description",
        "author",
        "repository",
        "license",
        "tags",
        "requires",
    }
)
_CURRENT_ONLY = frozenset(
    {
        "version",
        "description",
        "repository",
        "license",
        "tags",
        "requires",
        "provides",
        "download_url",
        "sha256",
        "bundled",
        "verified",
        "releases",
    }
)


def _validated_releases(entry: dict[str, Any]) -> dict[str, dict[str, Any]]:
    if "releases" not in entry:
        return {}
    integration_id = entry.get("id", "<unknown>")
    releases = entry["releases"]
    if not isinstance(releases, dict):
        raise IntegrationCatalogError(
            f"Integration '{integration_id}' has an invalid releases mapping."
        )

    current = entry.get("version")
    if not isinstance(current, str) or not current.strip():
        raise IntegrationCatalogError(
            f"Integration '{integration_id}' has releases but no current version."
        )
    try:
        seen = {Version(current)}
    except InvalidVersion:
        raise IntegrationCatalogError(
            f"Integration '{integration_id}' has an invalid current version '{current}'."
        ) from None

    for advertised, metadata in releases.items():
        if not isinstance(advertised, str) or not advertised.strip():
            raise IntegrationCatalogError(
                f"Integration '{integration_id}' has an invalid release version key."
            )
        try:
            normalized = Version(advertised)
        except InvalidVersion:
            raise IntegrationCatalogError(
                f"Integration '{integration_id}' has invalid release version '{advertised}'."
            ) from None
        if normalized in seen:
            raise IntegrationCatalogError(
                f"Integration '{integration_id}' repeats release version '{advertised}'."
            )
        seen.add(normalized)
        if not isinstance(metadata, dict):
            raise IntegrationCatalogError(
                f"Integration '{integration_id}' release '{advertised}' must be an object."
            )
        for field, value in metadata.items():
            if field not in _RELEASE_FIELDS:
                label = (
                    "reserved"
                    if field
                    in {
                        "id",
                        "version",
                        "releases",
                        "_catalog_name",
                        "_install_allowed",
                    }
                    else "unsupported"
                )
                raise IntegrationCatalogError(
                    f"Integration '{integration_id}' release '{advertised}' has {label} field '{field}'."
                )
            if field == "tags":
                valid = isinstance(value, list) and all(
                    isinstance(tag, str) and tag.strip() for tag in value
                )
            elif field == "requires":
                valid = isinstance(value, dict)
            else:
                valid = isinstance(value, str) and (
                    bool(value.strip()) or field == "description"
                )
            if not valid:
                raise IntegrationCatalogError(
                    f"Integration '{integration_id}' release '{advertised}' has invalid {field}."
                )
    return releases


def select_release(entry: dict[str, Any], version: str | None) -> dict[str, Any] | None:
    """Select from the winning source without inheriting current-only metadata."""
    releases = _validated_releases(entry)
    current = entry.get("version")
    if version is None or (
        isinstance(current, str) and current.strip() and version == current
    ):
        return entry
    try:
        requested = Version(version)
    except (InvalidVersion, TypeError):
        return None
    if isinstance(current, str):
        try:
            if requested == Version(current):
                return entry
        except InvalidVersion:
            pass  # Legacy single-release catalogs may use non-PEP 440 versions.
    for advertised, metadata in releases.items():
        if requested == Version(advertised):
            shared = {
                key: value for key, value in entry.items() if key not in _CURRENT_ONLY
            }
            return {**shared, **metadata, "version": advertised}
    return None


def available_versions(entry: dict[str, Any]) -> list[str]:
    """Return current first, then older release spellings in descending order."""
    releases = _validated_releases(entry)
    current = entry.get("version")
    if not isinstance(current, str) or not current:
        return []
    return [current, *sorted(releases, key=Version, reverse=True)]