tan-cli 0.7.0__py3-none-any.whl

tan/core/devicetree_lint.py

@@ -0,0 +1,168 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Will Zephyr's devicetree LINT pass run for a build on this host?
+
+Zephyr compiles the devicetree with its own Python `gen_defines.py`; `dtc`
+is not needed for that and a build with no `dtc` anywhere still links a real
+`zephyr.elf`. What `dtc` is used for is a SECOND, diagnostics-only pass --
+`zephyr/cmake/modules/dts.cmake` runs the compiler over the assembled `.dts`
+under `if(DTC)`, above the verbatim comment *"This is just to generate
+warnings and errors; we discard the output"*, with `-E unit_address_vs_reg`
+and (when the binary accepts it) `-Wunique_unit_address_if_enabled`. No
+`dtc`, no `if(DTC)` body, no diagnostics -- and nothing on either side says
+so, because the block is skipped rather than failed.
+
+**Why this module exists at all: tan-cli#1176/#1178 changed the premise.**
+`tan bootstrap` acquires the Zephyr SDK with `--no-hosttools`
+(`tan.core.toolchain_provision.NO_HOSTTOOLS_FLAG`), so the install carries no
+`hosttools/` tree -- and `hosttools/` is where the SDK's own `dtc` lives
+(measured on a real `zephyr-sdk-1.0.1`:
+`hosttools/sysroots/x86_64-pokysdk-linux/usr/bin/dtc`, `Version: DTC v1.7.0+`,
+beside `openocd`/`fdtdump`/`fdtget`/`fdtoverlay`/`fdtput`). Before #1178 the
+SDK put a `dtc` in CMake's reach on every install; now it does not, so the
+lint pass silently stopped running on the default path. That is the whole of
+tan-cli#1192.
+
+**This partially reverses a decision `tan.commands.doctor_cmd`'s own module
+docstring records as deliberate** -- `dtc`/`gperf` are named there as the
+frozen Rust oracle's `--build` check vocabulary, NOT ported. That decision was
+correct when it was made and its premise is gone: it was written when `dtc`
+arrived with the SDK, so a `dtc` probe could only ever restate what
+`zephyrSdk` already said. `gperf` stays unported; only `dtc` is reopened here,
+and only as the devicetree-lint question, never as a bare is-it-on-PATH probe.
+
+## The two CMake mechanisms this mirrors, and why BOTH are needed
+
+`find_program(DTC dtc)` (`zephyr/cmake/modules/FindDtc.cmake`) searches
+`CMAKE_PREFIX_PATH` BEFORE the ambient `PATH`, and the Zephyr SDK's own
+`cmake/zephyr/host-tools.cmake` is what puts its `hosttools/` on that prefix
+list -- `list(APPEND CMAKE_PREFIX_PATH ${HOST_TOOLS_HOME}/usr)`, where
+`HOST_TOOLS_HOME` is the poky sysroot on Linux, `<sdk>/hosttools` on macOS,
+and on WINDOWS is never given a `dtc`-bearing prefix at all (that branch
+appends only `qemu`/`qemu-arc`/`openocd`, and the Windows hosttools archive
+ships neither `dtc` nor `gperf` -- `tan.core.bootstrap`'s
+`manual_install_windows` prose records the `7z l` measurement). So a probe
+that looked only at `PATH` would report "no lint" on a host whose SDK carries
+one, which is a report that lies; [`hosttools_bin_dir`] is the other half.
+
+`find_package(Dtc 1.4.6)` (`dts.cmake`, line 10 of the same file) is the
+second mechanism and the one that makes this check worth having a `warn` arm
+at all. `FindDtc.cmake` runs `dtc --version`, scrapes `Version: DTC v?X.Y.Z`
+out of it, hands the result to `find_package_handle_standard_args`, and then:
+
+    if(NOT Dtc_FOUND)
+      # DTC was found but version requirement is not met, or dtc was not working.
+      # Treat it as DTC was never found by resetting the result from `find_program()`
+      set(DTC DTC-NOTFOUND CACHE FILEPATH "Path to a program" FORCE)
+    endif()
+
+A `dtc` that IS installed but is older than [`DTC_MIN_VERSION`], or whose
+`--version` does not run or does not parse, is therefore reset to
+`DTC-NOTFOUND` and the lint is skipped -- with no message. That host is the
+one this module has something to say to: somebody installed `dtc` on purpose,
+believes the lint runs, and it does not. A host with NO `dtc` is the ordinary,
+supported, documented post-#1178 state and gets no warning at all; see
+`doctor_cmd.devicetree_lint_check` for the severity argument.
+
+Pure: no subprocess, no filesystem, no environment. `doctor_cmd` owns the IO
+(`_resolve_dtc`) and builds the `Check`.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import NamedTuple
+
+#: `zephyr/cmake/modules/dts.cmake`'s own `find_package(Dtc 1.4.6)`. A `dtc`
+#: below this is reset to `DTC-NOTFOUND` by `FindDtc.cmake` -- see the module
+#: docstring. Compared component-wise, `>=`, non-EXACT, exactly as CMake's
+#: `find_package_handle_standard_args` compares a `VERSION_VAR`.
+DTC_MIN_VERSION: tuple[int, int, int] = (1, 4, 6)
+
+#: `FindDtc.cmake`'s own scrape, transcribed: `string(REGEX MATCH "Version:
+#: DTC v?([0-9]+[.][0-9]+[.][0-9]+).*" ...)`. Deliberately NOT anchored and
+#: deliberately tolerant of a trailing suffix -- the SDK's own binary answers
+#: `Version: DTC v1.7.0+` (measured), whose `+` CMake drops the same way this
+#: does.
+_DTC_VERSION_RE = re.compile(r"Version: DTC v?([0-9]+)[.]([0-9]+)[.]([0-9]+)")
+
+#: Where the resolved `dtc` came from. `hosttools` means the Zephyr SDK's own
+#: copy, reached through the `CMAKE_PREFIX_PATH` append `host-tools.cmake`
+#: does; `path` means the ambient `PATH`, which CMake searches second;
+#: `absent` means neither had one, which is what a `--no-hosttools` install
+#: with no distro `dtc` looks like.
+ORIGIN_HOSTTOOLS = "hosttools"
+ORIGIN_PATH = "path"
+ORIGIN_ABSENT = "absent"
+
+
+class DtcResolution(NamedTuple):
+    """What a host's `dtc` situation is, in the terms CMake would resolve it.
+
+    `version` is `None` both when there is no binary to ask and when the
+    binary answered something `FindDtc.cmake`'s own regex would not match --
+    the two are distinguished by `origin`, not by this field, because CMake
+    does not distinguish them either: both end at `DTC-NOTFOUND`.
+    """
+
+    path: str | None
+    origin: str
+    version: tuple[int, int, int] | None
+
+
+def parse_dtc_version(text: str | None) -> tuple[int, int, int] | None:
+    """`dtc --version` output -> `(major, minor, patch)`, or `None` when
+    `FindDtc.cmake`'s regex would not have matched it either."""
+    if not text:
+        return None
+    found = _DTC_VERSION_RE.search(text)
+    if found is None:
+        return None
+    return (int(found.group(1)), int(found.group(2)), int(found.group(3)))
+
+
+def format_version(version: tuple[int, int, int]) -> str:
+    return ".".join(str(part) for part in version)
+
+
+def hosttools_bin_dir(sdk_install_dir: Path, host_os: str, host_arch: str) -> Path | None:
+    """The directory `find_program(DTC dtc)` would find the SDK's own `dtc`
+    in, given an install at `sdk_install_dir` -- or `None` on a host whose
+    SDK never puts one on `CMAKE_PREFIX_PATH`.
+
+    One branch per branch of `<sdk>/cmake/zephyr/host-tools.cmake`, whose
+    `list(APPEND CMAKE_PREFIX_PATH ${HOST_TOOLS_HOME}/usr)` is what makes the
+    bundle findable; `find_program` appends `bin` to a prefix itself.
+
+    * `linux` -- `hosttools/sysroots/<arch>-pokysdk-linux/usr/bin`, the arch
+      token coming from `cmake_host_system_information(... OS_PLATFORM)`, i.e.
+      `uname -m`, which is the same token `doctor_cmd._host_os_arch_tags`
+      already normalises (`x86_64`/`aarch64`).
+    * `macos` -- `hosttools/usr/bin`; the per-component `opt/` trees are
+      symlinked into that one directory by the SDK itself.
+    * `windows` -- `None`, and that is a fact about the SDK, not a gap here:
+      the Windows branch appends only `qemu`, `qemu-arc` and `openocd`
+      prefixes, and the Windows hosttools archive ships no `dtc` to append a
+      prefix for. On Windows `dtc` can only ever come from `PATH`.
+    """
+    if host_os == "linux":
+        return (
+            sdk_install_dir
+            / "hosttools"
+            / "sysroots"
+            / f"{host_arch}-pokysdk-linux"
+            / "usr"
+            / "bin"
+        )
+    if host_os == "macos":
+        return sdk_install_dir / "hosttools" / "usr" / "bin"
+    return None
+
+
+def lint_will_run(resolution: DtcResolution) -> bool:
+    """`Dtc_FOUND`, computed the way `FindDtc.cmake` computes it: a binary was
+    resolved AND its version parsed AND that version is at least
+    [`DTC_MIN_VERSION`]. Anything else is the `set(DTC DTC-NOTFOUND ... FORCE)`
+    reset, and `dts.cmake`'s `if(DTC)` block does not run."""
+    if resolution.path is None or resolution.version is None:
+        return False
+    return resolution.version >= DTC_MIN_VERSION

tan/core/dir_removal.py

@@ -0,0 +1,229 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Shared, hardened directory-removal primitives (tan-cli#790).
+
+**Extracted from `tan.commands.clean_cmd`, verbatim logic**, where these six
+names (`is_link`, `os_error_text`, `_reraise_removal_failure`,
+`_retry_after_clearing_readonly`, `_RMTREE_HOOK`, `remove_dir`) first landed
+for `tan clean` and were battle-tested against the frozen v0.4.1 oracle on
+real read-only build outputs, real junctions, and real symlinked build roots
+(see each function's own docstring for the specific oracle-diff that shaped
+it). `tan sdk remove` needs the identical hardening -- a real `tan bootstrap`
+tree can carry a read-only `.git/objects/**` entry from a shallow clone, and
+neither command's job is to reinvent "how does this host actually let me
+delete a stubborn directory" independently.
+
+**Lives in `tan.core`, not a second copy in `tan.commands.sdk_cmd`, and not
+left where it was**, for the same reason `sdk_discovery.py`'s own module
+docstring gives for why IT moved out of a command module:  `tan.core` may
+import no `tan.commands.*` module (the invariant `tan.core.shapes` and
+`tan.core.sdk_discovery` already state and rely on), so a `tan/core/`
+caller — this module has none yet, but `tan.core.sdk_removal` (tan-cli#790)
+is the first — could not reach these primitives while they lived inside
+`clean_cmd.py` without creating exactly the `tan.core` -> `tan.commands`
+inversion that rule exists to forbid.
+
+`clean_cmd.py` re-imports every one of these six names at its own module
+level (`from tan.core.dir_removal import ...`) rather than losing them: its
+own internal call sites still say the bare `_remove_dir(...)` /
+`_retry_after_clearing_readonly(...)`, resolved through `clean_cmd`'s own
+module globals at call time, so `monkeypatch.setattr(clean_cmd, "_remove_dir",
+...)` in the existing test suite keeps working unchanged -- the monkeypatch
+only cares which module attribute it is overwriting, never which module
+originally defined the value that attribute pointed at.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import stat
+import sys
+
+
+def is_link(path: str) -> bool:
+    """Whether `path` is a link that must not be followed -- a POSIX symlink, a
+    Windows directory symlink, OR a Windows JUNCTION.
+
+    **`os.path.islink` is not this test.** On Windows `ntpath.islink` returns
+    True only for `IO_REPARSE_TAG_SYMLINK`; a junction is
+    `IO_REPARSE_TAG_MOUNT_POINT`, and `stat.S_ISLNK` is False for it as well.
+    Measured on this host: for `build/` junctioned at an out-of-tree directory,
+    `os.path.islink` and `S_ISLNK` both report False while
+    `st_reparse_tag == IO_REPARSE_TAG_MOUNT_POINT`. A guard written on
+    `os.path.islink` therefore lets a junction reach `shutil.rmtree` -- which
+    has its OWN, correct check (`shutil._rmtree_islink`, mirrored here) and
+    refuses, so nothing outside the tree is destroyed, but the junction is then
+    never cleaned and the run reports a spurious `remove-failed`. This was a
+    live defect in the first cut of `tan clean`'s port, caught only by diffing
+    against the Rust binary.
+    """
+    try:
+        st = os.lstat(path)
+    except (OSError, ValueError):
+        return False
+    if stat.S_ISLNK(st.st_mode):
+        return True
+    attributes = getattr(st, "st_file_attributes", 0)
+    return bool(
+        attributes & getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0)
+        and getattr(st, "st_reparse_tag", 0)
+        == getattr(stat, "IO_REPARSE_TAG_MOUNT_POINT", -1)
+    )
+
+
+def os_error_text(err: BaseException) -> str:
+    """An `OSError` rendered the way Rust's `io::Error` Display renders it:
+    `<system message> (os error <code>)`.
+
+    Python's own `str(OSError)` is `[WinError 32] <message>: '<path>'`, which
+    both differs from the oracle and repeats a path the message already names.
+    The Windows error code (`winerror`) is preferred over the translated
+    `errno`, matching Rust, which reports the raw OS code.
+
+    One character still differs on Windows: `FormatMessageW` ends its sentences
+    with a period and Rust keeps it, while Python's `strerror` strips it. Not
+    synthesized here -- guessing at punctuation inside a system message is worse
+    than a documented one-character divergence in a warning string.
+    """
+    if not isinstance(err, OSError):
+        return str(err)
+    code = getattr(err, "winerror", None) or err.errno
+    if err.strerror is None or code is None:
+        return str(err)
+    return f"{err.strerror} (os error {code})"
+
+
+#: The two functions `shutil.rmtree` hands its error hook that CANNOT be called
+#: with one positional argument. On POSIX `rmtree` runs the fd-based
+#: `_rmtree_safe_fd` walk, which reports failures of `os.open` (shutil 3.12
+#: lines 682 and 781) and `os.close` (692/712/791/808) through the same hook as
+#: the one-argument `os.scandir`/`os.unlink`/`os.rmdir`/`os.lstat`. `os.open`
+#: needs `flags` and `os.close` takes an fd, not the path the hook is handed --
+#: so retrying either is a `TypeError`, not a repair. Windows' `_rmtree_unsafe`
+#: never passes these, which is why the crash class this guards is POSIX-only.
+_NOT_RETRYABLE_WITH_PATH_ALONE = frozenset({os.open, os.close})
+
+
+def _reraise_removal_failure(func, path, exc) -> None:
+    """Re-raise the failure `shutil.rmtree` reported, so the caller's
+    `except (OSError, ValueError)` sees it and can report it as a removal
+    failure rather than a silent no-op.
+
+    `exc` is the exception under `onexc` and an `exc_info` TUPLE under the
+    deprecated `onerror` (see `_RMTREE_HOOK`), so both shapes are unwrapped
+    here. A hook that has nothing to re-raise still must not return quietly --
+    `rmtree` would then report the tree as removed -- so the fallback states the
+    operation that failed.
+    """
+    if isinstance(exc, tuple) and len(exc) == 3:
+        exc = exc[1]
+    if isinstance(exc, BaseException):
+        raise exc
+    raise OSError(f"{getattr(func, '__name__', func)} failed on {path}")
+
+
+def _retry_after_clearing_readonly(func, path, exc=None) -> None:
+    """`shutil.rmtree` error hook: clear the read-only bit and retry once.
+
+    Rust's `remove_dir_all` deletes a read-only file on Windows outright (it
+    passes `FILE_DISPOSITION_IGNORE_READONLY_ATTRIBUTE`), where `shutil.rmtree`
+    fails the WHOLE tree with `[WinError 5] Access is denied`. Measured against
+    the Rust binary, from `tan clean`'s own port: one read-only file inside
+    `build/` had Rust remove the build dir and exit 0 while a naive port left
+    every artefact in place and warned. Read-only build outputs -- and, for
+    `tan sdk remove`'s own caller, read-only `.git/objects/**` entries left by
+    a shallow `git clone` -- are ORDINARY, not exotic, so this is the primary
+    path here, not a fallback.
+
+    `st_mode | S_IWUSR` rather than a bare `S_IWRITE`: on POSIX the latter would
+    replace the whole mode with `0o200` and strip the owner's read/execute bits
+    from a directory mid-walk. A failure here propagates out of `rmtree` and is
+    the caller's to report.
+
+    The retry is only attempted for a `func` that a path alone can drive
+    ([`_NOT_RETRYABLE_WITH_PATH_ALONE`]). It used to end in a bare `func(path)`,
+    so a build directory the invoking user OWNS but cannot open -- a
+    `chmod -R a-r` or tar-preserved tree, where `os.chmod` SUCCEEDS and
+    `os.open` is what failed -- raised `TypeError: open() missing required
+    argument 'flags' (pos 2)`. That is neither `OSError` nor `ValueError`, so it
+    used to sail past `tan clean`'s best-effort guard, abort the target loop and
+    hit its outer catch-all: exit 5, `clean.internal-failure`, and every
+    remaining target silently skipped. Measured on the oracle for the same
+    tree: exit 0, a warning, and the rest of the run completing -- which is
+    what re-raising the original failure (rather than a `TypeError`) restores.
+
+    **Also clears the PARENT directory's own write bit** (tan-cli#790,
+    `sdk.remove`'s own maintainer follow-up correction). On POSIX, `unlink`
+    and `rmdir` consult only the CONTAINING directory's write+execute
+    permission -- a file or directory's OWN mode bits are irrelevant to
+    whether it can be removed. So the chmod above, alone, fixes nothing on
+    POSIX for the one case that is genuinely common there: a read-only
+    directory (`chmod 555 somedir`, or exactly what a bootstrapped SDK tree's
+    `.git/objects/xx/` subdirectories carry after certain git versions'
+    packing) defeats the unlink of every child inside it, and `path` here is
+    the CHILD's path, whose own mode was never the problem. Measured: with
+    only `path` chmod'd, `shutil.rmtree` over a tree containing one such
+    directory still raised `PermissionError` on the first child inside it.
+    Chmod'ing `os.path.dirname(path)` too -- best-effort, a failure here is
+    swallowed rather than propagated, because the ORIGINAL failure (or
+    whatever `func(path)` raises next) is the honest one to report if this
+    does not fix it -- closes that gap. This is additive to the Windows
+    read-only-ATTRIBUTE fix above, not a replacement for it: the two failure
+    shapes (an NTFS attribute on the file itself; a POSIX permission bit on
+    its parent) are independent and this function now clears both.
+    """
+    if func in _NOT_RETRYABLE_WITH_PATH_ALONE:
+        _reraise_removal_failure(func, path, exc)
+    # tan-cli#1482: never follow a link -- chmod'ing through it would change the
+    # permissions of a file OUTSIDE the tree being removed, and `os.stat` on a
+    # dangling link raised before the parent fix below could run. A link needs
+    # only its parent's write bit (POSIX unlink consults the parent alone).
+    try:
+        if not stat.S_ISLNK(os.lstat(path).st_mode):
+            os.chmod(path, os.lstat(path).st_mode | stat.S_IWUSR)
+    except OSError:
+        pass
+    parent = os.path.dirname(path)
+    if parent and parent != path:
+        try:
+            os.chmod(parent, os.stat(parent).st_mode | stat.S_IWUSR | stat.S_IXUSR)
+        except OSError:
+            pass
+    try:
+        func(path)
+    except TypeError:
+        # Belt and braces for a future `shutil` that routes one more
+        # many-argument callable through this hook: the removal still failed,
+        # and it must be reported as such rather than escaping as a `TypeError`.
+        _reraise_removal_failure(func, path, exc)
+
+
+#: `shutil.rmtree`'s error-hook keyword. `onerror` is deprecated from 3.12 and
+#: scheduled for removal; `onexc` does not exist before it. Selected once here so
+#: the call site stays a single expression on either interpreter -- the handler
+#: signature is compatible because it ignores its third argument, which is the
+#: only thing the two hooks disagree about (`exc_info` tuple vs exception).
+_RMTREE_HOOK = "onexc" if sys.version_info >= (3, 12) else "onerror"
+
+
+def remove_dir(path: str) -> None:
+    """Remove a directory target recursively, never following a link out of the
+    tree, and clearing a read-only attribute/bit in the way instead of failing
+    the whole removal on it.
+
+    A link ([`is_link`]) is unlinked ITSELF, exactly as the oracle's
+    `remove_dir_all` does on Windows: verified against the Rust binary with
+    `build/` junctioned at an out-of-tree directory -- the junction goes, the
+    target's contents stay. `shutil.rmtree` handles the ordinary case and never
+    recurses through a link INSIDE the tree, so both arms are contained.
+
+    `os.rmdir` before `os.unlink`: on Windows a junction or directory symlink is
+    removed by `RemoveDirectory`, and `unlink` fails on it; on POSIX `rmdir`
+    fails on a symlink and `unlink` is what removes it.
+    """
+    if is_link(path):
+        try:
+            os.rmdir(path)
+        except OSError:
+            os.unlink(path)
+        return
+    shutil.rmtree(path, **{_RMTREE_HOOK: _retry_after_clearing_readonly})

tan/core/doctor_git.py

@@ -0,0 +1,172 @@
+# SPDX-License-Identifier: Apache-2.0
+"""SDK-provenance git helpers, extracted out of `tan.commands.doctor_cmd`
+(tan-cli#797 module-size budget) rather than left to grow that file further.
+
+Every spawn here resolves `git` through `tan.core.tool_lookup.resolve_tool`
+FIRST and threads the result through as `executable=` on the actual
+`subprocess`/`probe` call -- never a bare `"git"` argv[0], which on Windows
+`CreateProcess` searches the current directory for ahead of `%PATH%`
+(tan-cli#797, the same hazard class tan-cli#567/#488 closed for
+flash/size/west). `doctor_cmd` re-exports every name here (a plain
+`from tan.core.doctor_git import ...`) so `doctor_cmd._resolve_git_executable`
+etc. keep resolving for every existing caller and test.
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+
+from tan.core.probe import PROBE_TIMEOUT_S, isolated_cwd, probe
+from tan.core.subprocess_env import spawn_env
+from tan.core.tool_lookup import resolve_tool
+
+
+def _resolve_git_executable() -> str | None:
+    """The absolute path to `git`, resolved through the shared
+    `tool_lookup.resolve_tool` walk -- never `shutil.which`, which on Windows
+    inserts the current directory ahead of `%PATH%` (see `tool_lookup`'s own
+    docstring). `None` when `git` is not on PATH at all, which every caller
+    below must treat as "no git provenance to report", not a crash
+    (tan-cli#797): a doctor that raises because git is absent is worse than
+    the bare-argv0 spawn it replaces.
+    """
+    return resolve_tool("git", os.environ).resolved
+
+
+def _is_own_git_checkout(root: str, git_exe: str | None) -> bool:
+    """Whether `root` is itself the TOP of a git checkout, not merely nested
+    somewhere inside an unrelated ENCLOSING one (tan-cli#488 defect 4).
+
+    `git -C <root> ...` discovery walks UPWARD looking for a `.git`, so an SDK
+    with no `.git` of its own -- an extracted release archive, vendored under
+    a customer's own application repository, which this port explicitly
+    supports (`tan.commands.sdk_cmd.check_sdk_readiness`'s own docstring names
+    exactly this shape) -- answers every git query with the ENCLOSING repo's
+    state instead of "not a checkout". `_git_short_commit`/`_git_behind_
+    upstream` below both call this FIRST and refuse (`None`) rather than
+    misattribute a foreign repository's commit or upstream-skew as the SDK's
+    own.
+
+    Compares the RESOLVED `--show-toplevel` against the RESOLVED `root`:
+    lexical string comparison alone would false-negative on a symlinked or
+    differently-cased path to the same directory.
+
+    `git_exe` -- the PATH-RESOLVED absolute `git`, from `_resolve_git_executable`
+    (tan-cli#797). `None` when `git` is not on PATH at all: refuses outright
+    rather than falling back to a bare `probe(["git", ...])`, which would
+    re-open the exact cwd-shadowing hazard this resolution exists to close.
+    """
+    if git_exe is None:
+        return False
+    top = probe(["git", "-C", root, "rev-parse", "--show-toplevel"], executable=git_exe)
+    if top is None:
+        return False
+    try:
+        return Path(top.strip()).resolve() == Path(root).resolve()
+    except OSError:
+        return False
+
+
+def _git_short_commit(root: str, git_exe: str | None) -> str | None:
+    """`git -C <root> rev-parse --short HEAD`, or `None` when `root` is not a
+    git checkout of its own (e.g. an extracted SDK release archive -- including
+    one vendored inside a customer's own git repository, see
+    `_is_own_git_checkout`) or `git_exe` is `None` (git not on PATH)."""
+    if not _is_own_git_checkout(root, git_exe):
+        return None
+    out = probe(["git", "-C", root, "rev-parse", "--short", "HEAD"], executable=git_exe)
+    if out is None:
+        return None
+    commit = out.strip()
+    return commit or None
+
+
+def _git_behind_upstream(root: str, git_exe: str | None) -> int | None:
+    """Commit count `HEAD` is behind its upstream tracking ref, without
+    fetching. `None` when there is no upstream, `root` is not a git checkout
+    of its own (see `_is_own_git_checkout`), or `git_exe` is `None` (git not
+    on PATH)."""
+    if not _is_own_git_checkout(root, git_exe):
+        return None
+    out = probe(
+        ["git", "-C", root, "rev-list", "--count", "HEAD..@{upstream}"], executable=git_exe
+    )
+    if out is None:
+        return None
+    try:
+        return int(out.strip())
+    except ValueError:
+        return None
+
+
+def classify_git_core_longpaths(exit_code: int | None, stdout: str) -> bool | None:
+    """The three-way verdict for a `git config --get core.longpaths`
+    invocation -- the git-side counterpart to `doctor_cmd._long_paths_enabled`'s
+    registry read, split out as its own pure function (mirroring
+    `tan_core::host_env::classify_git_core_longpaths`) so the exact mapping
+    tan-cli#306 argues hardest about is unit-tested without needing a real
+    `git` invocation for every case.
+
+    * exit 0 -> the stdout value, parsed with git's own boolean grammar.
+    * exit 1 -> `False`. `git config --get` documents this code as "the key
+      is not set in any scope (system/global/local)" -- git's own default,
+      and the state a fresh `HOME` is in (tan-cli#306's exact repro).
+    * anything else (`git` not on PATH, a malformed config file, a
+      permissions error) -> `None`: uncertain, not guessed.
+    """
+    if exit_code == 0:
+        value = stdout.strip().lower()
+        return value not in ("false", "no", "off", "0")
+    if exit_code == 1:
+        return False
+    return None
+
+
+def _git_core_longpaths(git_exe: str | None) -> bool | None:
+    """Read git's own EFFECTIVE `core.longpaths` (system -> global precedence
+    -- NOT the project repo's local config, see below -- resolved by `git config --get` itself rather than tan
+    re-implementing that precedence by hand) via a real `git` subprocess.
+
+    A SEPARATE axis from `doctor_cmd._long_paths_enabled` on purpose
+    (tan-cli#306): the registry governs manifested Win32 API calls; it does
+    nothing for git, which `west update` uses for every project
+    clone/checkout and which refuses a long path unless ITS OWN setting says
+    so -- the registry read alone reported `pass` on a fresh `HOME` while
+    `west update` died on `hal_nxp`'s `tf-psa-crypto` tree.
+
+    Not built on `tan.core.probe.probe`: `probe()` collapses "ran and exited
+    non-zero" (exit 1, meaning "unset") and "could not run at all" (meaning
+    "unknown") to the same `None`, and `classify_git_core_longpaths` needs to
+    tell those apart.
+
+    `git_exe` -- the PATH-RESOLVED absolute `git` from `_resolve_git_executable`
+    (tan-cli#797). `None` when git is not on PATH: answers "unknown" rather
+    than spawning the bare `"git"` this used to hand straight to
+    `subprocess.run`, which on Windows searches the CURRENT DIRECTORY (the
+    customer project's, since doctor never `chdir`s) ahead of `%PATH%`.
+    """
+    if git_exe is None:
+        return None
+    try:
+        # Run from a fresh EMPTY directory (not inside any repository): from the
+        # project's cwd `git config --get` also merges that repo's LOCAL config,
+        # but `west update` clones fresh module repos that never inherit it, so
+        # only the system/global scopes predict whether those clones succeed.
+        with isolated_cwd() as empty:
+            out = subprocess.run(
+                ["git", "config", "--get", "core.longpaths"],
+                cwd=empty,
+                executable=git_exe,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                stdin=subprocess.DEVNULL,
+                timeout=PROBE_TIMEOUT_S,
+                env=spawn_env(),
+                check=False,
+            )
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return None
+    return classify_git_core_longpaths(out.returncode, out.stdout)