"""Repo-root and path resolution. No domain logic lives here (D-263).

This module is on the push-gate path, so it does no subprocess work: no
`git rev-parse`, no shelling out, nothing beyond the stdlib. Resolution is
`__file__`-relative and validated against a sentinel file. That is not only
faster than asking git — it is *more correct*, because the current working
directory is not a reliable signal. A git hook runs from the repo root, an agent
`Bash` call may not, and `reach` is meant to work from anywhere.
"""

from __future__ import annotations

import os
from pathlib import Path

from tooling.core.errors import ReachError

# The file whose presence proves a directory is the repo root. project.yaml is
# the version source of truth (CLAUDE.md), so it is the honest sentinel: if it
# is absent, everything downstream was going to fail anyway — better to say so
# here, by name, than to hand out a plausible wrong path.
SENTINEL = "project.yaml"

ENV_OVERRIDE = "SR_REPO_ROOT"


def repo_root() -> Path:
    """Absolute path to the repo root.

    `SR_REPO_ROOT` wins if set; otherwise the package's own location is used.
    Both are validated, deliberately: an override pointing somewhere useless
    should fail loudly rather than fall back to a default that happens to work,
    because a silent fallback is how you end up editing one checkout and
    checking another.

    Not cached. The two syscalls are microseconds, and a cache would make the
    override untestable for the sake of nothing measurable.
    """
    override = os.environ.get(ENV_OVERRIDE)
    if override:
        return _validated(Path(override).expanduser().resolve(), f"{ENV_OVERRIDE}={override}")
    # tooling/core/config.py -> tooling/core -> tooling -> repo root
    return _validated(Path(__file__).resolve().parents[2], "the installed package location")


def path(*parts: str) -> Path:
    """Join `parts` onto the repo root, so callers do not each re-resolve it."""
    return repo_root().joinpath(*parts)


def _validated(root: Path, source: str) -> Path:
    if (root / SENTINEL).is_file():
        return root
    raise ReachError(
        f"cannot locate the repo root: {root} contains no {SENTINEL} "
        f"(resolved from {source})",
        fix=(
            "make reach-repoint — from the checkout you want reach to follow. "
            f"For a single command instead: {ENV_OVERRIDE}=<path-to-repo> reach ..."
        ),
    )