"""Gradle home detection utilities."""

from __future__ import annotations

import os
from pathlib import Path

from .constants import DEFAULT_GRADLE_HOME


def detect_gradle_user_home() -> Path:
    """Return Gradle user home using env override when set.

    Gradle honors ``GRADLE_USER_HOME``. If it is absent, default to ``~/.gradle``.
    """

    env_home = os.getenv("GRADLE_USER_HOME")
    if env_home:
        return Path(env_home).expanduser().resolve()

    return DEFAULT_GRADLE_HOME