py-wlcli 0.8.0__py3-none-any.whl

wl_cli/utils/root.py

@@ -0,0 +1,521 @@
+"""The single module that answers "which root does this starting point belong to".
+
+This module is the single answer to "which root does this starting point belong
+to" for the whole CLI. The six same-shaped resolvers it replaces -- a PROJECT
+marker walk, the test subsystem's CWD-reading spelling, its anchored mirror, a
+DEPLOY resolver, a git work-tree probe and the bounded LEGACY walk -- were
+deleted outright in the hard cut (#123). No alias and no deprecated wrapper
+survives: a search for any of those old spellings now finds only the decision
+record and the changelog, never code.
+
+Interface
+---------
+
+Exactly three public names:
+
+* :class:`RootKind` -- *which* rule resolved the root, as a value;
+* :class:`Root` -- the resolved root plus the derived paths below it;
+* :func:`resolve` -- ``resolve(start, kind) -> Root | None``.
+
+``start`` is **required**: the module never reads an implicit current working
+directory. "Not found" is a *result* (``None``), not an exception and not a
+silent fallback -- the module does no fallback of its own. Falling back to the
+CWD when nothing is found is the *caller's* policy and belongs in exactly one
+place at the CLI top level; see ``docs/adr/0006-root-resolution-layering.md``
+for why that layering was chosen and which alternatives were rejected.
+
+Deliberately not part of this module
+------------------------------------
+
+Two functions are sometimes grouped with the resolvers above by name only; both
+answer a different question, and pulling either in would widen this interface
+without deepening it:
+
+* ``WorkspaceDetector._find_workspace_root`` answers "is this starting point a
+  member of a uv workspace" -- a *predicate*, not a locator. A predicate has no
+  business returning a :class:`Root`.
+* ``VersionUpdater._resolve_project_root`` resolves **wl's own installation
+  location** (including a ``Path(__file__)`` fallback). That is a question about
+  the tool, not about the user's root, and it moves with the installation rather
+  than with the directory the user ran from.
+
+Internals
+---------
+
+* **One cache.** Keyed by ``(starting directory, resolution rule)`` and holding
+  the negative ("not found") answer too, so a directory with no root is not
+  re-walked on every ``wl`` invocation. There is a single invalidation entry
+  point, :func:`_clear_root_cache`, and it has a real production caller
+  (``GitInitializer.initialize``, right after ``git init``); before this ticket
+  two per-resolver caches shared the job, one of them with a clearer no
+  production code ever called.
+* **git is an internal seam.** :class:`_GitProbe` is a protocol and
+  :data:`_git_probe` is the default subprocess implementation. Tests inject a
+  stand-in instead of monkey-patching ``subprocess`` globally -- which is what
+  used to force the git probe to carry a defensive "the stubbed result has no
+  usable ``stdout``" shape guard (#105). That guard is gone with the old probe
+  (#123): now that the seam is what tests drive, a completed process really is
+  one.
+* Imports are underscore-aliased so that ``dir(module)`` -- the module's
+  namespace -- really is the three public names and nothing else.
+
+The per-kind rules were lifted from the implementations this module replaces,
+including their asymmetries. The comments keep the *reasoning* behind each
+asymmetry, because those implementations are no longer here to explain
+themselves.
+"""
+
+import enum as _enum
+import os as _os
+import subprocess as _subprocess
+from dataclasses import dataclass as _dataclass
+from pathlib import Path as _Path
+from typing import Protocol as _Protocol
+
+__all__ = ["Root", "RootKind", "resolve"]
+
+_WL_DIR_NAME = ".wl"
+_CONFIG_FILE_NAME = "config.json"
+_PYPROJECT_NAME = "pyproject.toml"
+
+
+class RootKind(_enum.Enum):
+    """Which rule resolved a root -- the input selector *and* the output label.
+
+    Kind is both input and output because each kind is resolved by a different
+    rule, and a caller that must branch on "what kind of root is this" would
+    otherwise have to remember which function name it called.
+    """
+
+    #: The nearest ancestor carrying a ``.wl`` directory or a ``pyproject.toml``
+    #: file -- the plain PROJECT rule, with no git involvement.
+    PROJECT = "project"
+    #: git's own work-tree top (``git rev-parse --show-toplevel``).
+    WORKTREE = "worktree"
+    #: The root the ``.wl`` and the hooks leg are actually deployed under: the
+    #: git work-tree top when there is one, else the project root.
+    DEPLOY = "deploy"
+    #: An ancestor ``.wl`` in the pre-#95/#96 format that still has to be
+    #: migrated to the deploy root. Its boundaries are **completely different**
+    #: from :attr:`DEPLOY` -- a volume-root-bounded walk, a named system-scope
+    #: blacklist, and an explicit refusal of ``<home>/.wl`` -- which is why it
+    #: is its own value rather than a branch of ``DEPLOY``.
+    LEGACY = "legacy"
+
+
+@_dataclass(frozen=True)
+class Root:
+    """A resolved root and the paths derived below it.
+
+    ``path`` is the root directory itself; ``kind`` records which rule produced
+    it (see :class:`RootKind`). The derived-path methods are pure -- they build
+    a path from ``path`` and touch nothing on disk -- so they are testable
+    against a bare :class:`Root` without constructing a directory tree.
+
+    The methods are the only place the ``.wl`` layout is spelled out for the
+    roots this module owns; migrating the ~40 ``.wl`` literals and the bare
+    ``src/`` checks onto them is a separate ticket.
+    """
+
+    path: _Path
+    kind: RootKind
+
+    def wl_dir(self) -> _Path:
+        """The ``.wl`` control directory at this root."""
+        return self.path / _WL_DIR_NAME
+
+    def mypy_ini(self) -> _Path:
+        """The mypy baseline (``.wl/mypy.ini``) at this root."""
+        return self.wl_dir() / "mypy.ini"
+
+    def hooks_dir(self) -> _Path:
+        """The deployed git hooks directory (``.wl/hooks``) at this root."""
+        return self.wl_dir() / "hooks"
+
+    def src_dir(self) -> _Path:
+        """The source package directory (``src/``) at this root."""
+        return self.path / "src"
+
+
+class _GitProbe(_Protocol):
+    """The git seam: answer "what is the work-tree top for *start*".
+
+    Implementations return ``None`` for every "there is no work tree here"
+    shape -- git missing, a failed call, a directory that is not in any work
+    tree -- so no caller has to distinguish them.
+    """
+
+    def work_tree_root(self, start: _Path) -> _Path | None:  # pragma: no cover
+        ...
+
+
+class _SubprocessGitProbe:
+    """Default :class:`_GitProbe`: ``git rev-parse --show-toplevel``.
+
+    Returns ``None`` for every "there is no work tree here" shape -- git
+    missing, a failed call, a directory that is not part of any work tree -- so
+    no caller has to distinguish them.
+
+    Tests drive :data:`_git_probe` directly, so this reads a real
+    ``CompletedProcess``. The old probe also guarded the *shape* of the result
+    because tests patched ``subprocess`` globally and could hand back one whose
+    ``stdout`` was ``None`` or bytes (#105); with no such caller left, that
+    guard was deleted along with the probe it belonged to (#123).
+    """
+
+    def work_tree_root(self, start: _Path) -> _Path | None:
+        try:
+            result = _subprocess.run(
+                ["git", "rev-parse", "--show-toplevel"],
+                cwd=start,
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+        except (OSError, _subprocess.SubprocessError):
+            return None
+        if result.returncode != 0:
+            return None
+        value = result.stdout.strip()
+        return _Path(value) if value else None
+
+
+#: The single git seam. Tests swap this for a stand-in rather than patching
+#: ``subprocess`` module-wide; production never touches it.
+_git_probe: _GitProbe = _SubprocessGitProbe()
+
+#: The one cache: ``(resolved starting directory, kind) -> Root | None``.
+#:
+#: Keyed the way the old caches were individually keyed -- by the *resolved*
+#: spelling of the directory the lookup ran from -- so that two spellings of the
+#: same directory (a relative path, a symlinked ``/tmp``) still share an entry.
+#: The negative answer is cached too: "no root from here" is precisely the case
+#: that would otherwise re-walk the filesystem on every ``wl`` invocation.
+_root_cache: dict[tuple[str, RootKind], Root | None] = {}
+
+
+def _clear_root_cache() -> None:
+    """The one invalidation entry point for :data:`_root_cache`.
+
+    A layout change made *under an already-consulted directory* -- ``wl init``'s
+    ``git init`` is the production example -- can move the answer, and the memo
+    is per-directory, so the change has to be announced. This replaces the two
+    per-resolver caches and their separate clearers; the previous generation had
+    a clearer that no production code ever called, i.e. a cache that never
+    expired.
+
+    The production caller is ``GitInitializer.initialize``, right after a
+    successful ``git init``: the ``wl init`` group callback resolves the deploy
+    root *before* the subcommand runs, so the pre-creation answer is already
+    memoised for that directory and creating the work tree moves it. The
+    test-side entry point is the single ``_cold_root_cache`` fixture in
+    ``tests/conftest.py`` (#115).
+
+    It is underscore-prefixed on purpose: the public face is the three names
+    above, so this stays an internal seam.
+    """
+    _root_cache.clear()
+
+
+def resolve(start: _Path, kind: RootKind) -> Root | None:
+    """Resolve the ``kind``-root that *start* belongs to, or ``None``.
+
+    ``start`` is required and is used exactly as given: the module never reads
+    an implicit current working directory, so a caller's own directory can never
+    leak into the answer (the failure an anchored mirror of the CWD-reading
+    spelling was written to avoid, #110). ``None`` means "no such root from
+    here" -- a result,
+    not an error; this module performs **no** fallback.
+
+    The result is memoised per ``(start, kind)``; see :func:`_clear_root_cache`
+    for the one way to invalidate it.
+    """
+    resolved = _safe_resolve(start)
+    key = (str(resolved), kind)
+    if key in _root_cache:
+        return _root_cache[key]
+    result = _compute(resolved, kind)
+    _root_cache[key] = result
+    return result
+
+
+def _compute(start: _Path, kind: RootKind) -> Root | None:
+    """The uncached body of :func:`resolve`; *start* is already resolved."""
+    if kind is RootKind.PROJECT:
+        found = _project_marker_root(start)
+        return Root(found, kind) if found is not None else None
+    if kind is RootKind.WORKTREE:
+        top = _git_probe.work_tree_root(start)
+        return Root(top, kind) if top is not None else None
+    if kind is RootKind.DEPLOY:
+        return _deploy(start)
+    if kind is RootKind.LEGACY:
+        return _legacy(start)
+    raise ValueError(f"unknown RootKind: {kind!r}")
+
+
+def _deploy(start: _Path) -> Root | None:
+    """``DEPLOY``: the git work-tree top, else the project root.
+
+    The rule is the one the deploy resolver this module replaces used -- "the
+    work-tree top when there is one, otherwise the project root" -- with the one
+    difference that is the whole point of this module: when the git lookup
+    misses *and* no project marker exists, that resolver returned the starting
+    directory (its own CWD fallback); here that is ``None``, and the caller
+    decides whether to substitute anything.
+    """
+    top = _git_probe.work_tree_root(start)
+    if top is not None:
+        return Root(top, RootKind.DEPLOY)
+    found = _project_marker_root(start)
+    return Root(found, RootKind.DEPLOY) if found is not None else None
+
+
+def _legacy(start: _Path) -> Root | None:
+    """``LEGACY``: the nearest ``.wl`` still to be migrated, or ``None``.
+
+    ``start`` is the *invocation* directory, matching the one place the legacy
+    production walk ran from (``check_and_update_wl_dir`` passes the invocation
+    CWD). The deploy anchor the walk goes above is derived
+    internally by :func:`_deploy_anchor`; deriving it here rather than making
+    ``resolve`` take two arguments is what keeps the interface at one starting
+    point.
+
+    The returned :class:`Root` is the *parent* of the legacy ``.wl`` -- the root
+    whose ``.wl`` is the stale one -- so ``result.wl_dir()`` is the directory the
+    old walk returned.
+
+    Both shapes of that walk are reproduced:
+
+    * the invocation directory's project root, when it is not the deploy root
+      (a sub-package with its own ``pyproject.toml``, or a workspace whose
+      ``.wl`` the walk finds above);
+    * an ancestor ``.wl`` above the deploy root, bounded by
+      :func:`_is_out_of_scope_ancestor` and by the explicit ``<home>/.wl``
+      refusal.
+
+    The three bounds are copied from ``wl_dir_updater`` verbatim. They are *not*
+    ``DEPLOY``'s rules: the walk is bounded by the volume's filesystem root and
+    its direct children (plus the named :data:`_SYSTEM_WL_SCOPES`), and
+    ``<home>/.wl`` -- the *user-level* config, a different thing -- is refused by
+    realpath wherever the deploy root happens to sit (#104 N1).
+    """
+    deploy_anchor = _deploy_anchor(start)
+    deploy_wl = deploy_anchor / _WL_DIR_NAME
+
+    project = _project_marker_root(start)
+    # The old project walk never returned None, so the project anchor was the
+    # marker root or, when there was none, the starting directory itself.
+    project_wl = (project if project is not None else start) / _WL_DIR_NAME
+    if not _same_path(project_wl, deploy_wl) and _is_file(
+        project_wl / _CONFIG_FILE_NAME
+    ):
+        return Root(project_wl.parent, RootKind.LEGACY)
+
+    user_level_wl = [home / _WL_DIR_NAME for home in _user_home_dirs()]
+    ceiling = _walk_ceiling(deploy_anchor)
+
+    for ancestor in deploy_anchor.parents:
+        if _is_out_of_scope_ancestor(ancestor, ceiling):
+            # Ceiling / named system scope: stop, adopt nothing, and do not go
+            # higher -- nothing above them belongs to this project either.
+            break
+        candidate = ancestor / _WL_DIR_NAME
+        if any(_same_path(candidate, user_wl) for user_wl in user_level_wl):
+            break
+        if _same_path(candidate, deploy_wl):
+            continue
+        if _is_file(candidate / _CONFIG_FILE_NAME):
+            return Root(candidate.parent, RootKind.LEGACY)
+
+    return None
+
+
+def _deploy_anchor(start: _Path) -> _Path:
+    """The deploy point, never ``None`` -- ``LEGACY``'s internal anchor.
+
+    ``LEGACY`` walks *above* the deploy point, so it needs the anchor to exist
+    even when there is no git work tree and no project marker; the old deploy
+    resolver got that from its starting-directory fallback. Spelled out here as
+    an internal step so that :func:`resolve` can still answer ``None`` for the
+    ``DEPLOY`` kind itself.
+    """
+    top = _git_probe.work_tree_root(start)
+    if top is not None:
+        return top
+    found = _project_marker_root(start)
+    return found if found is not None else start
+
+
+def _project_marker_root(start: _Path) -> _Path | None:
+    """The ``PROJECT`` rule, step for step the one the old walk used.
+
+    That walk defined the markers but then papered over "not found" by returning
+    the starting path; here that outcome is ``None``.
+
+    A directory is a project root when it holds a ``.wl`` *directory* or a
+    ``pyproject.toml`` *file* -- the shapes matter, so a stray ``.wl`` file or a
+    ``pyproject.toml`` directory is not a marker. The nearest such ancestor wins,
+    and the walk stops before the filesystem root, which is never itself scanned.
+
+    The leading ``.wl`` check mirrors the original's ordering exactly, where the
+    starting directory was tested for ``.wl`` before the walk began. Since both
+    markers resolve to the *same* directory, that pre-check is redundant with the
+    walk's first iteration; it is kept only so the two rules stay line-by-line
+    comparable.
+    """
+    if _is_dir(start / _WL_DIR_NAME):
+        return start
+    check = start
+    while check.parent != check:
+        if _is_file(check / _PYPROJECT_NAME):
+            return check
+        if _is_dir(check / _WL_DIR_NAME):
+            return check
+        check = check.parent
+    return None
+
+
+def _safe_resolve(path: _Path) -> _Path:
+    """``Path.resolve()`` is not total -- a symlink loop raises ``RuntimeError``.
+
+    The un-resolved spelling is the fallback: the subsequent marker walk returns
+    the same answer either way, and the cache key stays usable.
+    """
+    try:
+        return path.resolve()
+    except Exception:
+        return path
+
+
+def _is_dir(path: _Path) -> bool:
+    """``is_dir`` without letting an unreadable component raise."""
+    try:
+        return path.is_dir()
+    except OSError:  # pragma: no cover - platform dependent
+        return False
+
+
+def _is_file(path: _Path) -> bool:
+    """``is_file`` without letting an unreadable component raise."""
+    try:
+        return path.is_file()
+    except OSError:  # pragma: no cover - platform dependent
+        return False
+
+
+def _same_path(a: _Path, b: _Path) -> bool:
+    """Whether two paths point at the same directory (tolerating symlinks)."""
+    try:
+        return a.resolve() == b.resolve()
+    except Exception:
+        return a == b
+
+
+# --- LEGACY's bounds ---------------------------------------------------------
+#
+# These used to be duplicated: ``wl_dir_updater`` carried its own copy of the
+# legacy walk and of these three bounds while this module was being expanded
+# ahead of its call sites. The hard cut (#123) deleted that copy, so this is now
+# the only one -- the bounds live with the rule that uses them.
+
+#: Shared, machine-level scopes: a ``.wl`` sitting directly in one of these
+#: belongs to the OS or to another user -- never to *this* checkout. Matched on
+#: the realpath, because on macOS ``/tmp``, ``/var`` and ``/etc`` are symlinks
+#: into ``/private`` while the deploy anchor is handed back resolved.
+_SYSTEM_WL_SCOPES = frozenset(
+    {
+        "/tmp",
+        "/var",
+        "/etc",
+        "/usr",
+        "/opt",
+        "/srv",
+        "/bin",
+        "/sbin",
+        "/lib",
+        "/lib64",
+        "/boot",
+        "/dev",
+        "/proc",
+        "/sys",
+        "/run",
+        "/root",
+        "/home",
+        "/mnt",
+        "/media",
+        "/lost+found",
+        "/private",
+        "/System",
+        "/Library",
+        "/Volumes",
+        "/Applications",
+        "/app",
+        "/builds",
+        "/workspace",
+        "/workspaces",
+    }
+)
+
+#: :data:`_SYSTEM_WL_SCOPES` pre-resolved once, so the per-walk test is a set
+#: lookup. Resolving a path that does not exist is harmless.
+_RESOLVED_SYSTEM_WL_SCOPES = frozenset(_os.path.realpath(p) for p in _SYSTEM_WL_SCOPES)
+
+
+def _user_home_dirs() -> list[_Path]:
+    """Every home directory the environment can vouch for (possibly none).
+
+    Deliberately *not* ``ConfigPathResolver.get_user_home_dir()``: when neither
+    ``$HOME`` nor the account database yields a home that method falls back to
+    ``os.getcwd()``, which would turn the caller's own directory into a bogus
+    "home" and silently disable every guard derived from it. Here an unknown
+    home is simply absent, and the walk ceiling still bounds the walk.
+
+    This distrust is warranted, not vestigial: the 2026-10-08 ruling kept that
+    caller-side CWD fallback in the config layer, and #126 ruled it stays there
+    (it answers the user's **home**, a different question from a project root, so
+    it is deliberately *not* folded into the single root-fallback policy) -- so
+    this module must go on deriving home from the environment alone.
+    """
+    candidates: list[_Path] = []
+    for var in ("HOME", "USERPROFILE"):
+        raw = _os.environ.get(var)
+        if raw:
+            candidates.append(_Path(raw))
+    try:
+        candidates.append(_Path.home())
+    except (RuntimeError, OSError):  # pragma: no cover - platform dependent
+        pass
+
+    # A relative path here is not a home: ``Path.home()`` degrades to ``~`` when
+    # it cannot resolve, and an inherited ``HOME=~`` is nonsense. Sources
+    # routinely agree (``$HOME`` *is* what ``Path.home()`` reads), so dedupe.
+    return list(dict.fromkeys(home for home in candidates if home.is_absolute()))
+
+
+def _walk_ceiling(deploy_root: _Path) -> _Path:
+    """Absolute, HOME-independent ceiling of the legacy ancestor walk.
+
+    The filesystem root of ``deploy_root``'s volume -- the bound that does not
+    care where the checkout lives or whether ``$HOME`` is usable at all.
+    """
+    anchor = _Path(_os.path.realpath(deploy_root)).anchor
+    return _Path(anchor) if anchor else _Path("/")
+
+
+def _is_out_of_scope_ancestor(ancestor: _Path, ceiling: _Path) -> bool:
+    """Whether ``ancestor`` may not be a legacy deploy point -- nor walked above.
+
+    Two absolute, HOME-independent rules:
+
+    * **position** -- the walk never inspects ``ceiling`` (the volume's
+      filesystem root) or any of its direct children;
+    * **the named** :data:`_SYSTEM_WL_SCOPES` -- matched on the realpath so the
+      symlinked spellings line up (macOS ``/tmp`` *is* ``/private/tmp``).
+    """
+    if ancestor == ceiling or ancestor.parent == ceiling:
+        return True
+    resolved = _Path(_os.path.realpath(ancestor))
+    if resolved == ceiling or resolved.parent == ceiling:
+        return True
+    return str(resolved) in _RESOLVED_SYSTEM_WL_SCOPES