release.py

#!/usr/bin/env python3
"""Generate release metadata (versions.json and release notes) for clang-tools-static-binaries.

Usage:
    python3 release.py --tag 2026.06.04-a1b2c3d4

This script is called from the CI workflow (.github/workflows/build.yml) in the
``draft-release`` job to produce:

* ``versions.json`` – machine-readable metadata about this release.
* ``release-notes.md`` – human-readable Markdown table of included LLVM versions.
"""

import argparse
import json
import sys
from datetime import datetime, timezone
from pathlib import Path

# Allow importing build.py from the repo root (same directory as this script).
sys.path.insert(0, str(Path(__file__).resolve().parent))
import build


def generate_versions_json(tag: str, output_dir: str = ".") -> Path:
    """Write ``versions.json`` to *output_dir* and return its path.

    The generated JSON contains the build timestamp, release tag, a
    mapping of LLVM release names (keys) to source tarball identifiers
    (values), the full list of shipped tools (with minimum LLVM version
    constraints), and the supported platforms. This is the single source
    of truth for all downstream channels (pip, asdf, homebrew, scoop, etc.).
    """
    all_tools = build.TOOLS
    tools_info: dict[str, dict] = {}
    for tool in all_tools:
        info: dict[str, object] = {}
        if tool == "clang-include-cleaner":
            info["min_llvm_version"] = build.INCLUDE_CLEANER_MIN_VERSION
        if tool == "clang-scan-deps":
            info["min_llvm_version"] = build.CLANG_SCAN_DEPS_MIN_VERSION
        tools_info[tool] = info

    platforms = [
        "linux-amd64",
        "linux-arm64",
        "macos-amd64",
        "macos-arm64",
        "windows-amd64",
        "windows-arm64",
    ]

    data = {
        "built_at": datetime.now(timezone.utc).isoformat(),
        "release_tag": tag,
        "llvm_versions": build.RELEASES,
        "tools": tools_info,
        "platforms": platforms,
    }
    out_path = Path(output_dir) / "versions.json"
    out_path.parent.mkdir(parents=True, exist_ok=True)
    out_path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
    print(
        f"Created {out_path} ({len(build.RELEASES)} versions, "
        f"{len(tools_info)} tools, {len(platforms)} platforms)"
    )
    return out_path


def generate_release_notes(output_dir: str = ".") -> Path:
    """Write ``release-notes.md`` to *output_dir* and return its path.

    The notes include a Markdown table of every LLVM version and its
    corresponding source tarball, plus the list of supported platforms.
    """
    lines = [
        "## LLVM Versions in this release",
        "",
        "| Version | Source |",
        "|---------|--------|",
    ]
    # Sort by major version number for readability.
    for ver, src in sorted(
        build.RELEASES.items(),
        key=lambda x: int(x[0].split(".")[0]),
        reverse=True,
    ):
        lines.append(f"| {ver} | `{src}` |")

    lines += [
        "",
        "## Platforms",
        "",
        "Linux x86-64 / Linux ARM64 / macOS x86-64 / macOS ARM64 / Windows x86-64 / Windows ARM64",
    ]

    out_path = Path(output_dir) / "release-notes.md"
    out_path.parent.mkdir(parents=True, exist_ok=True)
    out_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
    print(f"Created {out_path}")
    return out_path


def main() -> None:
    parser = argparse.ArgumentParser(
        description="Generate versions.json and release-notes.md for a release."
    )
    parser.add_argument(
        "--tag",
        required=True,
        metavar="TAG",
        help="Release tag (e.g. 2026.06.04-a1b2c3d4).",
    )
    parser.add_argument(
        "--output-dir",
        "-o",
        default=".",
        metavar="DIR",
        help="Directory to write output files (default: current directory).",
    )
    args = parser.parse_args()

    generate_versions_json(args.tag, args.output_dir)
    generate_release_notes(args.output_dir)


if __name__ == "__main__":
    main()