chaindiff 0.1.0__py3-none-any.whl

chaindiff/__init__.py

@@ -0,0 +1,3 @@
+"""Decide whether an Ethereum node client upgrade is safe."""
+
+__version__ = "0.1.0"

chaindiff/__main__.py

@@ -0,0 +1,4 @@
+from chaindiff.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

chaindiff/catalog.py

@@ -0,0 +1,179 @@
+"""Load and store the client registry, release catalog, and advisories."""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+from chaindiff.models import SEVERITIES, Advisory, Client, Release
+from chaindiff.versions import parse_version
+
+SCHEMA_VERSION = 1
+
+
+def data_dir() -> Path:
+    override = os.environ.get("CHAINDIFF_DATA")
+    if override:
+        return Path(override)
+    return Path(__file__).resolve().parent / "data"
+
+
+def format_time(moment: datetime) -> str:
+    return moment.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def parse_time(value: str) -> datetime:
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def _read_json(path: Path) -> dict:
+    try:
+        payload = json.loads(path.read_text())
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"{path} is not valid JSON") from exc
+    if not isinstance(payload, dict):
+        raise ValueError(f"{path} must contain a JSON object")
+    if payload.get("schema_version") != SCHEMA_VERSION:
+        raise ValueError(f"{path} has an unsupported schema_version")
+    return payload
+
+
+def load_clients() -> list[Client]:
+    path = data_dir() / "clients.json"
+    payload = _read_json(path)
+    clients: list[Client] = []
+    seen: set[str] = set()
+    for raw in payload.get("clients", []):
+        client_id = str(raw.get("id", "")).strip()
+        role = raw.get("role")
+        versioning = raw.get("versioning")
+        github = str(raw.get("github", "")).strip()
+        name = str(raw.get("name", "")).strip()
+        if not client_id or not name or not github:
+            raise ValueError(f"{path} has a client missing id, name, or github")
+        if role not in ("execution", "consensus"):
+            raise ValueError(f"{client_id} has an unknown role")
+        if versioning not in ("semver", "calver"):
+            raise ValueError(f"{client_id} has an unknown versioning scheme")
+        if client_id in seen:
+            raise ValueError(f"{client_id} is listed twice")
+        seen.add(client_id)
+        clients.append(
+            Client(
+                id=client_id,
+                name=name,
+                role=role,
+                github=github,
+                versioning=versioning,
+            )
+        )
+    if not clients:
+        raise ValueError(f"{path} does not list any clients")
+    return clients
+
+
+def client_by_id(clients: list[Client], client_id: str) -> Client | None:
+    key = client_id.strip().lower()
+    for client in clients:
+        if client.id == key:
+            return client
+    return None
+
+
+def releases_path(client_id: str) -> Path:
+    return data_dir() / "releases" / f"{client_id}.json"
+
+
+def load_releases(client_id: str) -> tuple[datetime, list[Release]] | None:
+    path = releases_path(client_id)
+    if not path.exists():
+        return None
+    payload = _read_json(path)
+    fetched_at = parse_time(str(payload["fetched_at"]))
+    releases: list[Release] = []
+    for raw in payload.get("releases", []):
+        tag = str(raw.get("tag", ""))
+        version = parse_version(tag)
+        if version is None:
+            continue
+        releases.append(
+            Release(
+                tag=tag,
+                name=str(raw.get("name") or tag),
+                published_at=str(raw.get("published_at") or ""),
+                prerelease=bool(raw.get("prerelease")),
+                url=str(raw.get("url") or ""),
+                version=version,
+            )
+        )
+    return fetched_at, releases
+
+
+def save_releases(
+    client: Client,
+    releases: list[Release],
+    ignored_tag_count: int,
+    fetched_at: datetime,
+) -> None:
+    path = releases_path(client.id)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    ordered = sorted(releases, key=lambda item: (item.version, item.published_at, item.tag), reverse=True)
+    payload = {
+        "schema_version": SCHEMA_VERSION,
+        "client": client.id,
+        "github": client.github,
+        "fetched_at": format_time(fetched_at),
+        "ignored_tag_count": ignored_tag_count,
+        "releases": [
+            {
+                "tag": item.tag,
+                "name": item.name,
+                "published_at": item.published_at,
+                "prerelease": item.prerelease,
+                "url": item.url,
+            }
+            for item in ordered
+        ],
+    }
+    text = json.dumps(payload, indent=2) + "\n"
+    temporary = path.with_suffix(".json.tmp")
+    temporary.write_text(text)
+    temporary.replace(path)
+
+
+def load_advisories(client_id: str) -> list[Advisory]:
+    path = data_dir() / "advisories" / f"{client_id}.json"
+    if not path.exists():
+        return []
+    payload = _read_json(path)
+    advisories: list[Advisory] = []
+    for index, raw in enumerate(payload.get("advisories", []), start=1):
+        version_text = str(raw.get("version", "")).strip()
+        version = parse_version(version_text)
+        severity = str(raw.get("severity", "")).strip()
+        summary = str(raw.get("summary", "")).strip()
+        action = str(raw.get("action", "")).strip()
+        source = str(raw.get("source", "")).strip()
+        where = f"{path} advisory {index} ({version_text or 'missing version'})"
+        if version is None:
+            raise ValueError(f"{where} has a version ChainDiff cannot parse")
+        if severity not in SEVERITIES:
+            raise ValueError(f"{where} has an unknown severity")
+        if not summary:
+            raise ValueError(f"{where} needs a summary")
+        if severity in ("breaking", "deprecated") and not action:
+            raise ValueError(f"{where} needs an action")
+        if not source.startswith(("https://", "http://")):
+            raise ValueError(f"{where} needs an http(s) source URL")
+        advisories.append(
+            Advisory(
+                version=version,
+                severity=severity,
+                summary=summary,
+                action=action,
+                source=source,
+            )
+        )
+    return advisories

chaindiff/cli.py

@@ -0,0 +1,156 @@
+"""Command line for ChainDiff."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+
+from chaindiff import __version__
+from chaindiff.catalog import client_by_id, load_advisories, load_clients, load_releases
+from chaindiff.evaluate import evaluate, latest_stable
+from chaindiff.models import CURRENT, DOWNGRADE, PRERELEASE, REVIEW, SAFE, UNSAFE
+from chaindiff.refresh import refresh_catalog
+from chaindiff.report import check_json, format_check, format_versions, versions_json
+from chaindiff.versions import explain_unparsed, parse_version
+
+_EXIT = {
+    CURRENT: 0,
+    SAFE: 0,
+    REVIEW: 1,
+    UNSAFE: 2,
+    DOWNGRADE: 2,
+    PRERELEASE: 2,
+}
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="chaindiff",
+        description="Decide whether an Ethereum node client upgrade is safe.",
+    )
+    parser.add_argument("--version", action="version", version=f"chaindiff {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    versions = commands.add_parser("versions", help="Show the latest stable release of each client")
+    versions.add_argument("--client", action="append", dest="clients", help="Limit to one client id")
+    versions.add_argument("--json", action="store_true")
+
+    check = commands.add_parser("check", help="Compare an installed version with a target release")
+    plan = commands.add_parser("plan", help="Checklist for the same comparison as check")
+    for command in (check, plan):
+        command.add_argument("--client", required=True, help="Client id, for example geth")
+        command.add_argument("--from", dest="current", required=True, help="Installed version")
+        command.add_argument("--to", dest="target", default="latest", help="Target version, or latest")
+        command.add_argument("--json", action="store_true")
+
+    refresh = commands.add_parser("refresh", help="Download the release catalog from GitHub")
+    refresh.add_argument("--client", action="append", dest="clients", help="Refresh one client id")
+    return parser
+
+
+def _selected_clients(raw_ids: list[str] | None):
+    try:
+        clients = load_clients()
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return None
+    if not raw_ids:
+        return clients
+    selected = []
+    for raw in raw_ids:
+        client = client_by_id(clients, raw)
+        if client is None:
+            known = ", ".join(item.id for item in clients)
+            print(f"Unknown client '{raw}'. Known clients: {known}", file=sys.stderr)
+            return None
+        selected.append(client)
+    return selected
+
+
+def _versions(args: argparse.Namespace) -> int:
+    clients = _selected_clients(args.clients)
+    if clients is None:
+        return 3
+    rows = []
+    missing = False
+    for client in clients:
+        try:
+            loaded = load_releases(client.id)
+        except ValueError as exc:
+            print(str(exc), file=sys.stderr)
+            return 3
+        if loaded is None:
+            missing = True
+            rows.append((client, None, None))
+            continue
+        fetched_at, releases = loaded
+        rows.append((client, fetched_at, releases))
+    now = datetime.now(timezone.utc)
+    if args.json:
+        print(json.dumps(versions_json(rows, now=now), indent=2))
+    else:
+        print(format_versions(rows, now=now), end="")
+    if missing:
+        print("Run `chaindiff refresh` to fill a missing catalog.", file=sys.stderr)
+    return 0
+
+
+def _check(args: argparse.Namespace, *, plan_only: bool) -> int:
+    clients = _selected_clients([args.client])
+    if clients is None:
+        return 3
+    client = clients[0]
+    current = parse_version(args.current)
+    if current is None:
+        print(explain_unparsed(args.current), file=sys.stderr)
+        return 3
+    try:
+        loaded = load_releases(client.id)
+        advisories = load_advisories(client.id)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 3
+    if loaded is None:
+        print(f"No release catalog for {client.id}. Run: chaindiff refresh", file=sys.stderr)
+        return 3
+    fetched_at, releases = loaded
+    target_is_latest = args.target.lower() in ("latest", "stable")
+    if target_is_latest:
+        stable = latest_stable(releases)
+        if stable is None:
+            print(f"{client.id} has no stable release in the catalog.", file=sys.stderr)
+            return 3
+        target = stable.version
+    else:
+        target = parse_version(args.target)
+        if target is None:
+            print(explain_unparsed(args.target), file=sys.stderr)
+            return 3
+    result = evaluate(
+        client=client,
+        releases=releases,
+        advisories=advisories,
+        current=current,
+        target=target,
+        target_is_latest=target_is_latest,
+        fetched_at=fetched_at,
+        now=datetime.now(timezone.utc),
+    )
+    if args.json:
+        print(json.dumps(check_json(result), indent=2))
+    else:
+        print(format_check(result, plan_only=plan_only), end="")
+    return _EXIT[result.verdict]
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    if args.command == "versions":
+        return _versions(args)
+    if args.command == "refresh":
+        return refresh_catalog(args.clients)
+    if args.command == "plan":
+        return _check(args, plan_only=True)
+    return _check(args, plan_only=False)

chaindiff/data/clients.json

@@ -0,0 +1,68 @@
+{
+  "schema_version": 1,
+  "clients": [
+    {
+      "id": "geth",
+      "name": "Geth",
+      "role": "execution",
+      "github": "ethereum/go-ethereum",
+      "versioning": "semver"
+    },
+    {
+      "id": "nethermind",
+      "name": "Nethermind",
+      "role": "execution",
+      "github": "NethermindEth/nethermind",
+      "versioning": "semver"
+    },
+    {
+      "id": "erigon",
+      "name": "Erigon",
+      "role": "execution",
+      "github": "erigontech/erigon",
+      "versioning": "semver"
+    },
+    {
+      "id": "besu",
+      "name": "Besu",
+      "role": "execution",
+      "github": "besu-eth/besu",
+      "versioning": "calver"
+    },
+    {
+      "id": "reth",
+      "name": "Reth",
+      "role": "execution",
+      "github": "paradigmxyz/reth",
+      "versioning": "semver"
+    },
+    {
+      "id": "lighthouse",
+      "name": "Lighthouse",
+      "role": "consensus",
+      "github": "sigp/lighthouse",
+      "versioning": "semver"
+    },
+    {
+      "id": "prysm",
+      "name": "Prysm",
+      "role": "consensus",
+      "github": "OffchainLabs/prysm",
+      "versioning": "semver"
+    },
+    {
+      "id": "teku",
+      "name": "Teku",
+      "role": "consensus",
+      "github": "Consensys-Incorporated/teku",
+      "versioning": "calver"
+    },
+    {
+      "id": "nimbus",
+      "name": "Nimbus",
+      "role": "consensus",
+      "github": "status-im/nimbus-eth2",
+      "versioning": "calver"
+    }
+  ]
+}