Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

12.4 KB
Raw Blame
#!/usr/bin/env python3
# ruff: noqa: T201 allow print statements
"""
Validate uv configuration for local development and CI.

The shape we enforce:

- pyproject.toml [tool.uv].required-version is a FLOOR (e.g. ">=0.10.2"). It is
  the lowest uv version that can read this repo's config and lockfile. Bumping
  CI to a newer uv does NOT raise this floor — that keeps stale branches from
  breaking the moment master ships a new pin. Raise the floor only when the
  code on master genuinely requires a newer uv feature.

- .github/actions/setup-uv/action.yml holds CI's exact uv version. The Depot
  mirror and jobs that check out older revisions keep matching exact pins.
  Exact pins prevent CI from floating to a new release. setup-uv v7.6.0 uses
  a static manifest rather than the rate-limited releases API used by v7.3.0.

- .flox/env/manifest.toml mirrors the CI pin for parity between local dev and
  CI. Comparison is on major.minor to allow patch drift.

Performs four checks:
1. CI pins are present, exact literals, and identical across all files.
2. The pin satisfies pyproject's required-version floor.
3. The pin can download the required Python version.
4. Flox manifest uv version matches the CI pin on major.minor.

Run in CI via .github/workflows/ci-python.yml to catch issues early.

Exit codes:
    0: All checks passed
    1: any check failed
"""

import re
import sys
import subprocess
from pathlib import Path

try:
    import tomllib
except ImportError:
    import tomli as tomllib  # type: ignore


Version = tuple[int, int, int]


def parse_version(s: str) -> Version:
    """Parse 'X.Y.Z' into a tuple. Extra suffixes are ignored."""
    match = re.match(r"^(\d+)\.(\d+)\.(\d+)", s)
    if not match:
        raise ValueError(f"Cannot parse version: {s}")
    return (int(match.group(1)), int(match.group(2)), int(match.group(3)))


def get_python_version_from_pyproject() -> str:
    """Extract the required Python version from pyproject.toml."""
    pyproject_path = Path(__file__).parent.parent / "pyproject.toml"

    with open(pyproject_path, "rb") as f:
        data = tomllib.load(f)

    requires_python = data.get("project", {}).get("requires-python", "")
    # Extract version from format like "==X.Y.Z" or ">=X.Y.Z"
    match = re.search(r"(\d+\.\d+\.\d+)", requires_python)
    if not match:
        raise ValueError(f"Could not parse Python version from: {requires_python}")

    return match.group(1)


def get_uv_floor_from_pyproject() -> str | None:
    """Extract the uv floor version from pyproject.toml [tool.uv].required-version.

    Expects a `>=X.Y.Z` form. Returns the X.Y.Z literal, or None if absent.
    """
    pyproject_path = Path(__file__).parent.parent / "pyproject.toml"

    with open(pyproject_path, "rb") as f:
        data = tomllib.load(f)

    required_version = data.get("tool", {}).get("uv", {}).get("required-version", "")
    if not required_version:
        return None

    match = re.search(r"(\d+\.\d+\.\d+)", required_version)
    return match.group(1) if match else None


def get_uv_version_from_flox() -> str | None:
    """Extract the uv version literal from the flox manifest."""
    flox_manifest = Path(__file__).parent.parent / ".flox" / "env" / "manifest.toml"

    if not flox_manifest.exists():
        return None

    with open(flox_manifest, "rb") as f:
        data = tomllib.load(f)

    version = data.get("install", {}).get("uv", {}).get("version", "")
    if not version:
        return None

    match = re.search(r"(\d+\.\d+\.\d+)", version)
    return match.group(1) if match else None


def get_uv_pins_from_ci_files() -> dict[str, list[str | None]]:
    """Find direct setup-uv usages in CI configuration and their version pins.

    Returns a dict mapping each repo-relative file to its direct setup-uv
    versions. Composite actions are globbed rather than named, so a second
    wrapper — a .depot mirror, or a future per-tool action — cannot carry an
    unpinned setup-uv past this check.
    """
    repo_root = Path(__file__).parent.parent
    ci_files = [
        *sorted(repo_root.glob(".github/actions/*/action.y*ml")),
        *sorted(repo_root.glob(".depot/actions/*/action.y*ml")),
        *sorted((repo_root / ".github" / "workflows").glob("*.y*ml")),
        *sorted((repo_root / ".depot" / "workflows").glob("*.y*ml")),
    ]
    uv_usages: dict[str, list[str | None]] = {}

    for ci_file in ci_files:
        lines = ci_file.read_text().splitlines()
        for i, line in enumerate(lines):
            if "setup-uv@" not in line:
                continue
            version: str | None = None
            step_indent = len(line) - len(line.lstrip()) - (0 if line.lstrip().startswith("- ") else 2)
            for lookahead in lines[i + 1 :]:
                if not lookahead.strip() or lookahead.lstrip().startswith("#"):
                    continue
                if len(lookahead) - len(lookahead.lstrip()) <= step_indent:
                    break
                m = re.fullmatch(r"\s+version:\s*(['\"]?)(\d+\.\d+\.\d+)\1\s*(?:#.*)?", lookahead)
                if m:
                    version = m.group(2)
                    break
            path = str(ci_file.relative_to(repo_root))
            uv_usages.setdefault(path, []).append(version)

    return uv_usages


def check_uv_python_compatibility(uv_version: str, python_version: str) -> tuple[bool, str]:
    """Check if the given uv version can download the specified Python version."""
    try:
        result = subprocess.run(
            [
                "uvx",
                "--from",
                f"uv=={uv_version}",
                "uv",
                "python",
                "list",
                python_version,
                "--only-downloads",
            ],
            capture_output=True,
            text=True,
            timeout=30,
        )
        if result.returncode == 0 and result.stdout.strip():
            return True, "verified via uv python list"
        return False, f"Python {python_version} not available for uv {uv_version}"
    except subprocess.TimeoutExpired:
        return True, "uv command timed out, assuming compatible"
    except FileNotFoundError:
        return True, "uvx not installed, assuming compatible"
    except Exception as e:
        return True, f"unable to verify ({type(e).__name__})"


def _section(title: str) -> None:
    print(title)
    print("-" * 60)


def _divider() -> None:
    print()
    print("=" * 60)
    print()


def label_workflow_pins(workflow_usages: dict[str, list[str | None]]) -> tuple[list[str], dict[str, list[str]]]:
    """Split usages into missing pins and pins grouped by version.

    Returns (missing_pins, pin_locations). Each usage is labelled with its
    repo-relative path, plus a `(usage N)` suffix when a file has several.
    """
    missing_pins: list[str] = []
    pin_locations: dict[str, list[str]] = {}

    for workflow_name, versions in sorted(workflow_usages.items()):
        for i, version in enumerate(versions):
            usage = f"{workflow_name} (usage {i + 1})" if len(versions) > 1 else workflow_name
            if version is None:
                missing_pins.append(usage)
            else:
                pin_locations.setdefault(version, []).append(usage)

    return missing_pins, pin_locations


def check_workflow_pins() -> tuple[bool, str | None]:
    """Check 1: pins present, exact literals, and identical across CI files.

    Returns (ok, workflow_pin). The pin is the single agreed version, or None
    when it is missing or ambiguous.
    """
    _section("Check 1: CI workflow uv version pins")

    workflow_usages = get_uv_pins_from_ci_files()
    missing_pins, pin_locations = label_workflow_pins(workflow_usages)
    distinct_pins = set(pin_locations)

    ok = True
    if missing_pins:
        print("✗ setup-uv usages missing version pin (add `version: 'x.y.z'`):")
        for name in missing_pins:
            print(f"  - {name}")
        print()
        print("  Use the shared setup-uv action, or an exact pin for an older-revision job.")
        ok = False

    workflow_pin: str | None = None
    if len(distinct_pins) > 1:
        print("✗ setup-uv usages pinned to different versions (must all match):")
        for pin in sorted(distinct_pins):
            print(f"  {pin}:")
            for loc in pin_locations[pin]:
                print(f"    - {loc}")
        ok = False
    elif len(distinct_pins) == 1:
        workflow_pin = next(iter(distinct_pins))
        if not missing_pins:
            print(f"✓ All {sum(len(v) for v in workflow_usages.values())} setup-uv usages pinned to {workflow_pin}")
    elif not missing_pins:
        print("⚠ No setup-uv usages found in workflows")

    return ok, workflow_pin


def check_floor_satisfied(workflow_pin: str | None, floor: str | None) -> bool:
    """Check 2: the workflow pin is at or above the pyproject floor."""
    _section("Check 2: Workflow pin satisfies pyproject floor")

    if not (floor and workflow_pin):
        print("⚠ Skipped: missing workflow pin or pyproject floor")
        return True

    try:
        if parse_version(workflow_pin) >= parse_version(floor):
            print(f"✓ Workflow pin {workflow_pin} >= pyproject floor {floor}")
            return True
        print(f"✗ Workflow pin {workflow_pin} is below pyproject floor {floor}")
        print("  Either raise the workflow pin or lower the floor.")
        return False
    except ValueError as e:
        print(f"⚠ Skipped: {e}")
        return True


def check_python_downloadable(workflow_pin: str | None, python_version: str) -> bool:
    """Check 3: the workflow pin can download the required Python version."""
    _section("Check 3: uv Python compatibility")

    if not workflow_pin:
        print("⚠ Skipped: no workflow pin to test")
        return True

    compatible, message = check_uv_python_compatibility(workflow_pin, python_version)
    if compatible:
        print(f"✓ uv {workflow_pin} can download Python {python_version}")
        print(f"  {message}")
        return True

    print(f"✗ uv {workflow_pin} cannot download Python {python_version}")
    print(f"  {message}")
    print()
    print("  To fix: pick a uv version whose `uv python list X.Y.Z --only-downloads` succeeds.")
    print("  See: https://github.com/astral-sh/uv/releases")
    return False


def check_flox_alignment(workflow_pin: str | None) -> bool:
    """Check 4: the flox manifest matches the workflow pin on major.minor."""
    _section("Check 4: Flox manifest uv version alignment")

    flox_uv = get_uv_version_from_flox()
    if not flox_uv:
        print("⚠ Skipped: No flox manifest or uv version found")
        return True
    if not workflow_pin:
        print("⚠ Skipped: No workflow pin to compare against")
        return True

    flox_mm = ".".join(flox_uv.split(".")[:2])
    pin_mm = ".".join(workflow_pin.split(".")[:2])
    if flox_mm == pin_mm:
        print(f"✓ Flox uv {flox_uv} matches workflow pin {workflow_pin} on major.minor")
        return True
    print(f"✗ Flox uv {flox_uv} diverges from workflow pin {workflow_pin}")
    print("  Update .flox/env/manifest.toml to match the workflow pin.")
    return False


def main() -> int:
    """Main entry point for the validation script."""
    print("Validating uv configuration...")
    print()

    try:
        python_version = get_python_version_from_pyproject()
        print(f"Python version required: {python_version}")
    except Exception as e:
        print(f"✗ Error reading Python version: {e}")
        return 1

    floor = get_uv_floor_from_pyproject()
    print(f"uv floor (pyproject.toml): >={floor}" if floor else "uv floor: not set")

    _divider()
    pins_ok, workflow_pin = check_workflow_pins()
    _divider()
    floor_ok = check_floor_satisfied(workflow_pin, floor)
    _divider()
    python_ok = check_python_downloadable(workflow_pin, python_version)
    _divider()
    flox_ok = check_flox_alignment(workflow_pin)
    _divider()

    if pins_ok and floor_ok and python_ok and flox_ok:
        print("✓ All checks passed")
        return 0

    failures = []
    if not pins_ok:
        failures.append("workflow uv pins missing, mismatched, or not exact")
    if not floor_ok:
        failures.append("workflow pin below pyproject floor")
    if not python_ok:
        failures.append("workflow uv cannot download required Python")
    if not flox_ok:
        failures.append("flox uv diverges from workflow pin")
    print(f"✗ Failed: {'; '.join(failures)}")
    return 1


if __name__ == "__main__":
    sys.exit(main())