chaindiff 0.1.0__py3-none-any.whl

chaindiff/evaluate.py

@@ -0,0 +1,229 @@
+"""Decide whether a client upgrade is safe."""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta
+
+from chaindiff.models import (
+    CURRENT,
+    DOWNGRADE,
+    PRERELEASE,
+    REVIEW,
+    SAFE,
+    UNSAFE,
+    Advisory,
+    CheckResult,
+    Client,
+    Release,
+)
+from chaindiff.versions import Version
+
+STALE_AFTER = timedelta(days=5)
+_SECURITY = re.compile(r"(?i)\b(security|cve-\d+|vulnerability)\b")
+_SEVERITY_RANK = {"none": 0, "note": 1, "deprecated": 2, "breaking": 3}
+
+
+def latest_stable(releases: list[Release]) -> Release | None:
+    stable = [item for item in releases if not item.prerelease]
+    if not stable:
+        return None
+    return max(stable, key=lambda item: (item.version, item.published_at))
+
+
+def newer_prerelease(releases: list[Release], stable: Release | None) -> Release | None:
+    if stable is None:
+        return None
+    newer = [item for item in releases if item.prerelease and item.version > stable.version]
+    if not newer:
+        return None
+    return max(newer, key=lambda item: (item.version, item.published_at))
+
+
+def advisories_for(advisories: list[Advisory], version: Version) -> list[Advisory]:
+    return [item for item in advisories if item.version == version]
+
+
+def _worst(advisories: list[Advisory]) -> Advisory | None:
+    if not advisories:
+        return None
+    return max(advisories, key=lambda item: _SEVERITY_RANK[item.severity])
+
+
+def _backup_steps() -> list[str]:
+    return [
+        "Read the release notes for every release in this range.",
+        "Back up the data directory, or snapshot the disk, before changing the binary.",
+        "Keep the current binary so you can roll back.",
+        "Upgrade this client only. Confirm it is healthy before changing the client paired with it.",
+        "If the release notes require an order for a network upgrade, follow that order.",
+        "If the node fails to start or stops syncing, restore the previous binary.",
+    ]
+
+
+def _plan_steps(verdict: str, hops: list[Release], advisories: list[Advisory]) -> list[str]:
+    if verdict == CURRENT:
+        return ["No upgrade to plan."]
+    if verdict == DOWNGRADE:
+        return ["Stay on the newer version you already run."]
+    steps: list[str] = []
+    for hop in sorted(hops, key=lambda item: item.version):
+        for advisory in advisories_for(advisories, hop.version):
+            if advisory.severity in ("breaking", "deprecated") or (
+                advisory.severity == "note" and advisory.action
+            ):
+                steps.append(f"{hop.tag}: {advisory.action} ({advisory.source})")
+    steps.extend(_backup_steps())
+    return steps
+
+
+def _choose_target(releases: list[Release], target: Version) -> Release | None:
+    matches = [item for item in releases if item.version == target]
+    if not matches:
+        return None
+    if target.pre is None:
+        stable = [item for item in matches if not item.prerelease]
+        if stable:
+            matches = stable
+    return max(matches, key=lambda item: item.published_at)
+
+
+def _major_crossings(client: Client, current: Version, hops: list[Release]) -> list[Release]:
+    """First release in range that enters each new semver major."""
+    if client.versioning != "semver":
+        return []
+    crossings: list[Release] = []
+    seen: set[int] = set()
+    for hop in sorted(hops, key=lambda item: item.version):
+        major = hop.version.numbers[0]
+        if major <= current.numbers[0] or major in seen:
+            continue
+        seen.add(major)
+        crossings.append(hop)
+    return crossings
+
+
+def evaluate(
+    *,
+    client: Client,
+    releases: list[Release],
+    advisories: list[Advisory],
+    current: Version,
+    target: Version,
+    target_is_latest: bool,
+    fetched_at: datetime,
+    now: datetime,
+) -> CheckResult:
+    warnings: list[str] = []
+    reasons: list[str] = []
+    stale = now - fetched_at > STALE_AFTER
+    chosen = _choose_target(releases, target)
+    target_tag = chosen.tag if chosen else None
+
+    if not any(item.version == current and not item.prerelease for item in releases):
+        warnings.append(
+            "The current version is not a known stable tag. Comparison uses the version number only."
+        )
+    if chosen is None:
+        warnings.append("The target version is not in the catalog. The hop list may be incomplete.")
+
+    def finish(verdict: str, hops: list[Release]) -> CheckResult:
+        if stale and not (target_is_latest and verdict == REVIEW):
+            warnings.append("The release catalog is more than 5 days old.")
+        return CheckResult(
+            client=client,
+            current=current,
+            target=target,
+            target_tag=target_tag,
+            verdict=verdict,
+            reasons=reasons,
+            warnings=warnings,
+            releases=hops,
+            steps=_plan_steps(verdict, hops, advisories),
+            fetched_at=fetched_at,
+            stale=stale,
+        )
+
+    if current == target:
+        reasons.append("The target is the version you already run.")
+        if stale and target_is_latest:
+            reasons.append(
+                "The release catalog is more than 5 days old, so a newer stable release may exist."
+            )
+            result = finish(REVIEW, [])
+            result.steps = ["Refresh the release catalog, then run this check again."]
+            return result
+        return finish(CURRENT, [])
+
+    if target < current:
+        reasons.append("The target is older than the version you already run.")
+        return finish(DOWNGRADE, [])
+
+    include_prereleases = target.pre is not None or (chosen is not None and chosen.prerelease)
+    hops = [
+        item
+        for item in releases
+        if current < item.version <= target and (include_prereleases or not item.prerelease)
+    ]
+    hops.sort(key=lambda item: item.version, reverse=True)
+
+    breaking: list[tuple[Release, Advisory]] = []
+    deprecated: list[tuple[Release, Advisory]] = []
+    unreviewed: list[Release] = []
+    for hop in hops:
+        matched = advisories_for(advisories, hop.version)
+        if not matched:
+            unreviewed.append(hop)
+            continue
+        worst = _worst(matched)
+        if worst is not None and worst.severity == "breaking":
+            breaking.append((hop, worst))
+        elif worst is not None and worst.severity == "deprecated":
+            deprecated.append((hop, worst))
+
+    unreviewed_versions = {hop.version for hop in unreviewed}
+    unreviewed_majors = [
+        hop
+        for hop in _major_crossings(client, current, hops)
+        if hop.version in unreviewed_versions
+    ]
+
+    for hop, advisory in sorted(breaking, key=lambda item: item[0].version):
+        reasons.append(f"{hop.tag} is breaking: {advisory.summary}")
+    for hop in unreviewed_majors:
+        reasons.append(f"{hop.tag} raises the major version and has no review. Treat it as breaking.")
+    if len(unreviewed) == 1 and len(hops) == 1:
+        reasons.append("The release in this range has no advisory yet.")
+    elif len(unreviewed) == 1:
+        reasons.append(f"1 of {len(hops)} releases in this range has no advisory yet.")
+    elif unreviewed and len(unreviewed) == len(hops):
+        reasons.append(f"None of the {len(hops)} releases in this range has an advisory yet.")
+    elif unreviewed:
+        reasons.append(f"{len(unreviewed)} of {len(hops)} releases in this range have no advisory yet.")
+    for hop, advisory in sorted(deprecated, key=lambda item: item[0].version):
+        reasons.append(f"{hop.tag} deprecates something you may still be using: {advisory.summary}")
+    if not hops:
+        reasons.append("No catalog releases sit strictly between these versions.")
+
+    for hop in hops:
+        if _SECURITY.search(hop.name):
+            warnings.append(f"{hop.tag}: the release title mentions a security fix.")
+
+    target_is_pre = target.pre is not None or (chosen is not None and chosen.prerelease)
+    if target_is_pre:
+        reasons.append("The target is a prerelease. Do not run it on a mainnet node.")
+    if breaking or unreviewed_majors:
+        verdict = UNSAFE
+    elif target_is_pre:
+        verdict = PRERELEASE
+    elif not hops or unreviewed or deprecated or (stale and target_is_latest):
+        verdict = REVIEW
+        if stale and target_is_latest:
+            reasons.append(
+                "The release catalog is more than 5 days old, so this latest-stable result may be behind."
+            )
+    else:
+        verdict = SAFE
+        reasons.append("Every release in this range has been reviewed, and none is marked breaking.")
+
+    return finish(verdict, hops)

chaindiff/models.py

@@ -0,0 +1,69 @@
+"""Shared records for clients, releases, and advisories."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+
+from chaindiff.versions import Version
+
+CURRENT = "current"
+SAFE = "safe"
+REVIEW = "review"
+UNSAFE = "unsafe"
+DOWNGRADE = "downgrade"
+PRERELEASE = "prerelease"
+
+VERDICT_LABELS = {
+    CURRENT: "ALREADY CURRENT",
+    SAFE: "SAFE",
+    REVIEW: "REVIEW REQUIRED",
+    UNSAFE: "NOT SAFE",
+    DOWNGRADE: "DOWNGRADE",
+    PRERELEASE: "PRERELEASE",
+}
+
+SEVERITIES = ("none", "note", "deprecated", "breaking")
+
+
+@dataclass(frozen=True)
+class Client:
+    id: str
+    name: str
+    role: str
+    github: str
+    versioning: str
+
+
+@dataclass(frozen=True)
+class Release:
+    tag: str
+    name: str
+    published_at: str
+    prerelease: bool
+    url: str
+    version: Version
+
+
+@dataclass(frozen=True)
+class Advisory:
+    version: Version
+    severity: str
+    summary: str
+    action: str
+    source: str
+
+
+@dataclass
+class CheckResult:
+    client: Client
+    current: Version
+    target: Version
+    target_tag: str | None
+    verdict: str
+    reasons: list[str]
+    warnings: list[str]
+    releases: list[Release]
+    steps: list[str]
+    fetched_at: datetime
+    stale: bool

chaindiff/refresh.py

@@ -0,0 +1,155 @@
+"""Fetch client releases from GitHub."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import urllib.error
+import urllib.request
+from collections.abc import Callable
+from datetime import datetime, timezone
+from typing import Any
+
+from chaindiff.catalog import load_clients, save_releases
+from chaindiff.models import Client, Release
+from chaindiff.versions import parse_version, tag_is_prerelease
+
+API_ROOT = "https://api.github.com"
+_NEXT_LINK = re.compile(r'<([^>]+)>;\s*rel="next"')
+Opener = Callable[[str, str | None], tuple[Any, str | None]]
+
+
+class GitHubError(Exception):
+    pass
+
+
+def _default_opener(url: str, token: str | None) -> tuple[Any, str | None]:
+    headers = {
+        "Accept": "application/vnd.github+json",
+        "User-Agent": "chaindiff/0.1",
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    request = urllib.request.Request(url, headers=headers)
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            payload = json.load(response)
+            return payload, response.headers.get("Link")
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", errors="replace")
+        message = ""
+        try:
+            message = json.loads(detail).get("message", "")
+        except json.JSONDecodeError:
+            message = detail.strip()
+        if exc.code == 403 and "rate limit" in message.lower():
+            raise GitHubError(
+                "GitHub rate limit reached. Set GH_TOKEN or GITHUB_TOKEN and run refresh again."
+            ) from exc
+        raise GitHubError(f"GitHub returned {exc.code} for {url}: {message}") from exc
+    except urllib.error.URLError as exc:
+        raise GitHubError(f"Could not reach GitHub: {exc.reason}") from exc
+
+
+def _next_url(link_header: str | None) -> str | None:
+    if not link_header:
+        return None
+    matched = _NEXT_LINK.search(link_header)
+    if not matched:
+        return None
+    return matched.group(1)
+
+
+def releases_from_payload(items: list[dict[str, Any]]) -> tuple[list[Release], int]:
+    releases: list[Release] = []
+    ignored = 0
+    seen: set[str] = set()
+    for item in items:
+        if item.get("draft"):
+            ignored += 1
+            continue
+        tag = str(item.get("tag_name") or "")
+        if not tag or tag in seen:
+            ignored += 1
+            continue
+        version = parse_version(tag)
+        if version is None:
+            ignored += 1
+            continue
+        seen.add(tag)
+        published = str(item.get("published_at") or "")
+        prerelease = bool(item.get("prerelease")) or tag_is_prerelease(tag)
+        releases.append(
+            Release(
+                tag=tag,
+                name=str(item.get("name") or tag),
+                published_at=published,
+                prerelease=prerelease,
+                url=str(item.get("html_url") or ""),
+                version=version,
+            )
+        )
+    return releases, ignored
+
+
+def fetch_releases(
+    client: Client,
+    token: str | None = None,
+    opener: Opener | None = None,
+) -> tuple[list[Release], int]:
+    fetch = opener or _default_opener
+    url = f"{API_ROOT}/repos/{client.github}/releases?per_page=100"
+    pages: list[dict[str, Any]] = []
+    for _ in range(20):
+        payload, link = fetch(url, token)
+        if isinstance(payload, dict):
+            message = payload.get("message", "unexpected GitHub response")
+            raise GitHubError(f"{client.github}: {message}")
+        if not isinstance(payload, list):
+            raise GitHubError(f"{client.github}: unexpected GitHub response")
+        pages.extend(payload)
+        nxt = _next_url(link)
+        if nxt is None:
+            break
+        url = nxt
+    else:
+        raise GitHubError(f"{client.github}: too many release pages")
+    return releases_from_payload(pages)
+
+
+def github_token() -> str | None:
+    return os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN") or None
+
+
+def refresh_catalog(client_ids: list[str] | None = None) -> int:
+    clients = load_clients()
+    if client_ids:
+        wanted = {item.strip().lower() for item in client_ids}
+        unknown = wanted - {client.id for client in clients}
+        if unknown:
+            names = ", ".join(sorted(unknown))
+            print(f"Unknown client: {names}")
+            return 3
+        clients = [client for client in clients if client.id in wanted]
+
+    token = github_token()
+    failures: list[str] = []
+    fetched_at = datetime.now(timezone.utc)
+    for client in clients:
+        try:
+            releases, ignored = fetch_releases(client, token=token)
+        except GitHubError as exc:
+            failures.append(f"{client.id}: {exc}")
+            print(f"{client.id}: failed — {exc}")
+            continue
+        save_releases(client, releases, ignored, fetched_at)
+        stable = sum(1 for item in releases if not item.prerelease)
+        print(
+            f"{client.id}: {stable} stable releases, "
+            f"{len(releases) - stable} prereleases, {ignored} ignored tags"
+        )
+    if failures:
+        return 1
+    return 0

chaindiff/report.py

@@ -0,0 +1,166 @@
+"""Text and JSON reports."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+from chaindiff.catalog import format_time
+from chaindiff.evaluate import latest_stable, newer_prerelease
+from chaindiff.models import VERDICT_LABELS, CheckResult, Client, Release
+
+
+def _day(value: str) -> str:
+    return value[:10] if len(value) >= 10 else "-"
+
+
+def _shown_releases(releases: list[Release]) -> tuple[list[Release | None], int]:
+    if len(releases) <= 12:
+        return list(releases), 0
+    hidden = releases[8:-3]
+    shown: list[Release | None] = list(releases[:8]) + [None] + list(releases[-3:])
+    return shown, len(hidden)
+
+
+def format_check(result: CheckResult, *, plan_only: bool = False) -> str:
+    lines = [
+        f"{result.client.name}  {result.client.role}",
+        result.client.github,
+        f"Catalog: {format_time(result.fetched_at)}",
+        "",
+        f"{result.current.text}  →  {result.target.text}"
+        + (f"  ({result.target_tag})" if result.target_tag else ""),
+        "",
+        f"Verdict: {VERDICT_LABELS[result.verdict]}",
+        "",
+    ]
+    if result.reasons:
+        lines.append("Why")
+        lines.extend(f"  {reason}" for reason in result.reasons)
+        lines.append("")
+    if result.warnings:
+        lines.append("Warnings")
+        lines.extend(f"  {warning}" for warning in result.warnings)
+        lines.append("")
+    if not plan_only and result.releases:
+        lines.append("Releases")
+        shown, hidden = _shown_releases(result.releases)
+        for item in shown:
+            if item is None:
+                lines.append(f"  ({hidden} older releases omitted)")
+                continue
+            lines.append(f"  {item.tag:<16} {_day(item.published_at)}  {item.url}")
+        oldest = min(result.releases, key=lambda item: item.version)
+        if len(result.releases) > 1:
+            lines.append(
+                f"  First release after {result.current.text}: {oldest.tag} on {_day(oldest.published_at)}"
+            )
+        lines.append("")
+    if result.steps:
+        lines.append("Before any upgrade")
+        for index, step in enumerate(result.steps, start=1):
+            lines.append(f"  {index}. {step}")
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def check_json(result: CheckResult) -> dict:
+    return {
+        "client": result.client.id,
+        "name": result.client.name,
+        "role": result.client.role,
+        "github": result.client.github,
+        "from": result.current.text,
+        "to": result.target.text,
+        "target_tag": result.target_tag,
+        "verdict": result.verdict,
+        "reasons": result.reasons,
+        "warnings": result.warnings,
+        "releases": [
+            {
+                "tag": item.tag,
+                "name": item.name,
+                "published_at": item.published_at,
+                "prerelease": item.prerelease,
+                "url": item.url,
+            }
+            for item in result.releases
+        ],
+        "steps": result.steps,
+        "catalog_fetched_at": format_time(result.fetched_at),
+        "catalog_stale": result.stale,
+    }
+
+
+def format_versions(
+    rows: list[tuple[Client, datetime | None, list[Release] | None]],
+    now: datetime | None = None,
+) -> str:
+    moment = now or datetime.now(timezone.utc)
+    lines = [f"{'Client':<12} {'Role':<10} {'Latest':<18} {'Published':<12} Notes"]
+    stale = False
+    for client, fetched_at, releases in rows:
+        if releases is None or fetched_at is None:
+            lines.append(f"{client.id:<12} {client.role:<10} {'-':<18} {'-':<12} no catalog")
+            continue
+        is_stale = moment - fetched_at > timedelta(days=5)
+        stale = stale or is_stale
+        stable = latest_stable(releases)
+        ahead = newer_prerelease(releases, stable)
+        if stable is None:
+            latest = "-"
+            published = "-"
+        else:
+            latest = stable.tag
+            published = _day(stable.published_at)
+        notes = f"prerelease {ahead.tag} is newer" if ahead else ""
+        if is_stale:
+            notes = (notes + "; " if notes else "") + "catalog is stale"
+        lines.append(f"{client.id:<12} {client.role:<10} {latest:<18} {published:<12} {notes}".rstrip())
+    if stale:
+        lines.insert(0, "Release catalog is more than 5 days old. Run: chaindiff refresh")
+        lines.insert(1, "")
+    return "\n".join(lines) + "\n"
+
+
+def versions_json(
+    rows: list[tuple[Client, datetime | None, list[Release] | None]],
+    now: datetime | None = None,
+) -> dict:
+    moment = now or datetime.now(timezone.utc)
+    clients = []
+    for client, fetched_at, releases in rows:
+        if releases is None or fetched_at is None:
+            clients.append(
+                {
+                    "id": client.id,
+                    "name": client.name,
+                    "role": client.role,
+                    "github": client.github,
+                    "catalog": None,
+                }
+            )
+            continue
+        stable = latest_stable(releases)
+        ahead = newer_prerelease(releases, stable)
+        clients.append(
+            {
+                "id": client.id,
+                "name": client.name,
+                "role": client.role,
+                "github": client.github,
+                "fetched_at": format_time(fetched_at),
+                "stale": moment - fetched_at > timedelta(days=5),
+                "latest_stable": None
+                if stable is None
+                else {
+                    "tag": stable.tag,
+                    "version": stable.version.text,
+                    "published_at": stable.published_at,
+                    "url": stable.url,
+                },
+                "prerelease_ahead": None
+                if ahead is None
+                else {"tag": ahead.tag, "published_at": ahead.published_at, "url": ahead.url},
+            }
+        )
+    return {"clients": clients}