gpu-stack-inspector 0.1.0__py3-none-any.whl

gpu_stack_inspector/__init__.py

@@ -0,0 +1,8 @@
+"""GPU Stack Inspector: explain GPU differences between Python environments."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("gpu-stack-inspector")
+except PackageNotFoundError:  # imported from a source tree that was never installed
+    __version__ = "0+unknown"

gpu_stack_inspector/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m gpu_stack_inspector``."""
+
+from gpu_stack_inspector.cli import main
+
+if __name__ == "__main__":
+    main()

gpu_stack_inspector/cli.py

@@ -0,0 +1,335 @@
+"""Command-line interface: parses arguments and wires the layers together.
+
+No diagnosis logic lives here; commands call collectors, rules and renderers.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from enum import StrEnum
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+from gpu_stack_inspector import __version__, orchestrator
+from gpu_stack_inspector.exit_codes import ExitCode
+from gpu_stack_inspector.models import FailureKind, Snapshot
+from gpu_stack_inspector.privacy import RedactionContext, Redactor, redact_snapshot
+from gpu_stack_inspector.reports.json_report import render_json
+from gpu_stack_inspector.reports.markdown import render_markdown
+from gpu_stack_inspector.reports.terminal import redaction_line, render_compare, render_terminal
+from gpu_stack_inspector.rules.catalog import builtin_rules
+from gpu_stack_inspector.rules.engine import RuleContext
+from gpu_stack_inspector.runner import SubprocessRunner
+
+HELP = (
+    "Explain why PyTorch can use the GPU in one Python environment but not another.\n\n"
+    "Inspection is read-only: nothing is installed or changed, no root is needed and no "
+    "network connection is made. PyTorch is only imported with `probe --runtime`."
+)
+
+app = typer.Typer(
+    name="gpu-stack-inspector",
+    help=HELP,
+    no_args_is_help=True,
+    add_completion=False,
+    # Rich tracebacks print local variables, which can hold environment values.
+    pretty_exceptions_enable=False,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def _show_version(value: bool) -> None:
+    if value:
+        typer.echo(f"gpu-stack-inspector {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def cli(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version", callback=_show_version, is_eager=True, help="Show the version and exit."
+        ),
+    ] = False,
+) -> None:
+    """Global options (the help text comes from HELP)."""
+
+
+rules_app = typer.Typer(
+    help="List the checks and explain what each one looks at.", no_args_is_help=True
+)
+app.add_typer(rules_app, name="rules")
+
+
+@rules_app.command("list")
+def rules_list() -> None:
+    """List every check with its code."""
+    table = Table(box=None, pad_edge=False, show_edge=False)
+    table.add_column("Code", no_wrap=True)
+    table.add_column("Check")
+    for rule in builtin_rules():
+        table.add_row(Text(rule.id), Text(rule.title))
+    Console().print(table)
+
+
+@rules_app.command("explain")
+def rules_explain(
+    code: Annotated[
+        str, typer.Argument(metavar="CODE", help="A finding code, e.g. GSI-TORCH-002.")
+    ],
+) -> None:
+    """Explain what a check looks at, how it decides, and its sources."""
+    rule = builtin_rules().get(code.strip())
+    if rule is None:
+        typer.echo(
+            f"Unknown code {code}; `gpu-stack-inspector rules list` shows them all.", err=True
+        )
+        raise typer.Exit(ExitCode.ERROR)
+    console = Console()
+    console.print(Text(f"{rule.id}  {rule.title}", style="bold"))
+    console.print()
+    console.print(Text(rule.explanation))
+    if rule.sources:
+        console.print()
+        console.print(Text("Sources:", style="bold"))
+        for source in rule.sources:
+            console.print(Text(f"  {source}"))
+
+
+class OutputFormat(StrEnum):
+    TEXT = "text"
+    JSON = "json"
+
+
+@app.command()
+def inspect(
+    python: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--python",
+            "-p",
+            metavar="PATH",
+            help=(
+                "Python interpreter to inspect. Repeat it to inspect several. "
+                "Default: the python on PATH."
+            ),
+        ),
+    ] = None,
+    output_format: Annotated[
+        OutputFormat, typer.Option("--format", "-f", help="Output format.")
+    ] = OutputFormat.TEXT,
+) -> None:
+    """Inspect this machine and Python interpreters, read-only.
+
+    Interpreters are inspected from their metadata only; nothing is imported into
+    them beyond the standard library.
+    """
+    snapshot = _collect(python, compare=False)
+    redacted = redact_snapshot(snapshot)
+    if output_format is OutputFormat.JSON:
+        typer.echo(render_json(redacted), nl=False)
+    else:
+        render_terminal(redacted, Console())
+    if _unusable_interpreters(snapshot):
+        raise typer.Exit(ExitCode.CONTEXT_UNAVAILABLE)
+
+
+@app.command()
+def compare(
+    python: Annotated[
+        list[str],
+        typer.Option(
+            "--python",
+            "-p",
+            metavar="PATH",
+            help="An interpreter to compare. Give it at least twice.",
+        ),
+    ],
+    output_format: Annotated[
+        OutputFormat, typer.Option("--format", "-f", help="Output format.")
+    ] = OutputFormat.TEXT,
+    show_all: Annotated[
+        bool, typer.Option("--all", help="Show the fields that are the same too.")
+    ] = False,
+) -> None:
+    """Compare interpreters side by side: which fields differ, and what that means.
+
+    Read-only, like inspect: interpreters are inspected from their metadata only.
+    """
+    if len(python) < 2:
+        raise typer.BadParameter("give --python at least twice", param_hint="--python")
+    snapshot = _collect(python, compare=True)
+    redacted = redact_snapshot(snapshot)
+    if output_format is OutputFormat.JSON:
+        typer.echo(render_json(redacted), nl=False)
+    else:
+        render_compare(redacted, Console(), show_all=show_all)
+    if _unusable_interpreters(snapshot):
+        raise typer.Exit(ExitCode.CONTEXT_UNAVAILABLE)
+
+
+@app.command()
+def probe(
+    runtime: Annotated[
+        bool,
+        typer.Option(
+            "--runtime",
+            help="Agree to import torch in each interpreter and run a tiny CUDA operation.",
+        ),
+    ] = False,
+    python: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--python",
+            "-p",
+            metavar="PATH",
+            help="Interpreter to test. Repeat it to test several. Default: the python on PATH.",
+        ),
+    ] = None,
+    output_format: Annotated[
+        OutputFormat, typer.Option("--format", "-f", help="Output format.")
+    ] = OutputFormat.TEXT,
+) -> None:
+    """Prove CUDA works: import torch and run a tiny CUDA operation (needs --runtime).
+
+    This is the only command that imports packages of the inspected environments. It
+    creates a CUDA context and uses a few kilobytes of GPU memory for a moment, so it only
+    runs when you pass --runtime.
+    """
+    if not runtime:
+        typer.echo(
+            "probe imports torch in each interpreter and runs a tiny CUDA operation, which "
+            "uses a little GPU memory. Run it again with --runtime to agree.",
+            err=True,
+        )
+        raise typer.Exit(ExitCode.ERROR)
+    count = len(python) if python else 1
+    typer.echo(
+        f"Importing torch and running a tiny CUDA operation in {count} interpreter(s)…", err=True
+    )
+    snapshot = _collect(python, compare=count >= 2, runtime=True)
+    redacted = redact_snapshot(snapshot)
+    if output_format is OutputFormat.JSON:
+        typer.echo(render_json(redacted), nl=False)
+    else:
+        render_terminal(redacted, Console())
+    if _unusable_interpreters(snapshot):
+        raise typer.Exit(ExitCode.CONTEXT_UNAVAILABLE)
+
+
+class ReportFormat(StrEnum):
+    MARKDOWN = "markdown"
+    JSON = "json"
+
+
+@app.command()
+def report(
+    python: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--python",
+            "-p",
+            metavar="PATH",
+            help=(
+                "Interpreter to include. Repeat it to compare several. Default: the python on PATH."
+            ),
+        ),
+    ] = None,
+    report_format: Annotated[
+        ReportFormat, typer.Option("--format", "-f", help="Report format.")
+    ] = ReportFormat.MARKDOWN,
+    output: Annotated[
+        Path | None,
+        typer.Option(
+            "--output",
+            "-o",
+            metavar="FILE",
+            help="Write the report to FILE instead of printing it ('-' prints).",
+        ),
+    ] = None,
+    force: Annotated[bool, typer.Option("--force", help="Overwrite FILE if it exists.")] = False,
+) -> None:
+    """Write a redacted report to paste into a bug tracker.
+
+    By default the report is printed, so it can be read before it is shared. With two or
+    more interpreters it includes their comparison. The file named with --output is the
+    only thing this tool ever writes.
+    """
+    to_file = output is not None and str(output) != "-"
+    if to_file and output is not None and output.exists() and not force:
+        typer.echo(f"{output} exists; use --force to overwrite it.", err=True)
+        raise typer.Exit(ExitCode.ERROR)
+    snapshot = _collect(python, compare=len(python or []) >= 2)
+    redacted = redact_snapshot(snapshot)
+    if report_format is ReportFormat.JSON:
+        rendered = render_json(redacted)
+    else:
+        rendered = render_markdown(redacted)
+    if to_file and output is not None:
+        output.write_text(rendered, encoding="utf-8")
+        note = redaction_line(redacted) or "Nothing needed redacting"
+        typer.echo(f"Wrote {output}. {note}. Read it before you share it.", err=True)
+    else:
+        typer.echo(rendered, nl=False)
+    if _unusable_interpreters(snapshot):
+        raise typer.Exit(ExitCode.CONTEXT_UNAVAILABLE)
+
+
+def _collect(python: list[str] | None, *, compare: bool, runtime: bool = False) -> Snapshot:
+    """Inspect, run every check and, if asked, compare: the shared part of each command.
+
+    Without interpreters the python on PATH is used; the shell's python also goes into the
+    rule context. ``runtime`` is the user's consent to import torch and use CUDA.
+    """
+    shell_python = next(iter(orchestrator.default_interpreters()), None)
+    pythons = python or ([shell_python] if shell_python else [])
+    if not pythons:
+        typer.echo("No python found on PATH; name interpreters with --python.", err=True)
+    snapshot = orchestrator.diagnose(
+        orchestrator.inspect(SubprocessRunner(), pythons, runtime=runtime),
+        RuleContext(shell_python=shell_python),
+    )
+    return orchestrator.with_comparison(snapshot) if compare else snapshot
+
+
+_UNUSABLE = frozenset({FailureKind.NOT_FOUND, FailureKind.PERMISSION_DENIED})
+
+
+def _unusable_interpreters(snapshot: Snapshot) -> bool:
+    """A named interpreter that could not even be started: exit code 3, after the report.
+
+    An interpreter that starts and then crashes is a finding about that environment,
+    not missing context, so it does not count.
+    """
+    return any(
+        interpreter.version is None and any(f.kind in _UNUSABLE for f in interpreter.failures)
+        for interpreter in snapshot.interpreters
+    )
+
+
+def main() -> None:
+    """Console entry point.
+
+    Typer reports usage errors itself (exit code 2) and turns Ctrl+C into 130. Anything
+    else that escapes is a bug: print one redacted line instead of a traceback, which
+    could contain local values, and exit with 2. ``GSI_DEBUG=1`` shows the traceback.
+    """
+    try:
+        app()
+    except Exception as exc:  # SystemExit (normal exits) is not an Exception
+        if os.environ.get("GSI_DEBUG"):
+            raise
+        message = Redactor(RedactionContext.current()).text(str(exc)) or type(exc).__name__
+        typer.echo(
+            f"gpu-stack-inspector: internal error: {message}\n"
+            "Run it again with GSI_DEBUG=1 to see the traceback, and please report it.",
+            err=True,
+        )
+        sys.exit(ExitCode.ERROR)

gpu_stack_inspector/collectors/__init__.py

@@ -0,0 +1 @@
+"""Collectors read facts from the system; they never decide what a fact means."""

gpu_stack_inspector/collectors/environment.py

@@ -0,0 +1,31 @@
+"""Allowlisted CUDA-related environment variables of the tool's own process.
+
+Target interpreters inherit them, so they explain differences such as a GPU hidden by
+``CUDA_VISIBLE_DEVICES``. Nothing outside the allowlist is ever read: the rest of the
+environment can hold tokens and passwords.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+
+from gpu_stack_inspector.models import EnvironmentVariable
+
+ALLOWLIST: tuple[str, ...] = (
+    "CUDA_VISIBLE_DEVICES",
+    "CUDA_DEVICE_ORDER",
+    "NVIDIA_VISIBLE_DEVICES",
+    "NVIDIA_DRIVER_CAPABILITIES",
+    "CUDA_HOME",
+    "CUDA_PATH",
+    "LD_LIBRARY_PATH",
+    "PYTORCH_CUDA_ALLOC_CONF",
+)
+
+
+def collect_cuda_environment(
+    environ: Mapping[str, str] = os.environ,
+) -> tuple[EnvironmentVariable, ...]:
+    """The allowlisted variables that are set, in allowlist order."""
+    return tuple(EnvironmentVariable(name, environ[name]) for name in ALLOWLIST if name in environ)

gpu_stack_inspector/collectors/host.py

@@ -0,0 +1,48 @@
+"""Operating system facts."""
+
+from __future__ import annotations
+
+import platform
+from collections.abc import Callable
+
+from gpu_stack_inspector.models import HostFacts
+
+
+def collect_host(
+    *,
+    system: Callable[[], str] = platform.system,
+    machine: Callable[[], str] = platform.machine,
+    release: Callable[[], str] = platform.release,
+    os_release: Callable[[], dict[str, str]] = platform.freedesktop_os_release,
+) -> HostFacts:
+    """Read the OS name, architecture, kernel release and Linux distribution.
+
+    Never runs a command. The distribution comes from ``/etc/os-release`` (or
+    ``/usr/lib/os-release``); if neither can be read it stays unknown.
+    """
+    name = system() or "unknown"
+    kernel = release() or None
+    return HostFacts(
+        system=name,
+        machine=machine() or "unknown",
+        kernel=kernel,
+        distribution=_distribution(os_release) if name == "Linux" else None,
+        wsl=_is_wsl(kernel),
+    )
+
+
+def _distribution(os_release: Callable[[], dict[str, str]]) -> str | None:
+    try:
+        info = os_release()
+    except OSError:
+        return None
+    pretty = info.get("PRETTY_NAME", "").strip()
+    if pretty:
+        return pretty
+    fallback = " ".join(part for part in (info.get("NAME", ""), info.get("VERSION_ID", "")) if part)
+    return fallback or None
+
+
+def _is_wsl(kernel: str | None) -> bool:
+    # WSL kernels are built by Microsoft and say so: "5.15.167.4-microsoft-standard-WSL2".
+    return kernel is not None and "microsoft" in kernel.lower()

gpu_stack_inspector/collectors/nvidia.py

@@ -0,0 +1,166 @@
+"""NVIDIA driver and GPU facts from nvidia-smi."""
+
+from __future__ import annotations
+
+import csv
+import re
+import shutil
+from collections.abc import Callable, Sequence
+
+from gpu_stack_inspector.models import FailureKind, GpuDevice, NvidiaFacts, ProbeFailure
+from gpu_stack_inspector.runner import CommandResult, CommandRunner, Outcome, probe_failure
+
+PROBE = "nvidia-smi"
+TIMEOUT = 8.0
+"""nvidia-smi answers in well under a second; a hung driver must not hang the tool."""
+
+_ENV = {"LC_ALL": "C"}  # decimal points and English messages, whatever the user's locale
+_FIELDS = ("index", "name", "driver_version", "memory.total", "compute_cap")
+_UNAVAILABLE = frozenset(
+    {"", "n/a", "[n/a]", "not supported", "[not supported]", "[unknown error]"}
+)
+_COMPUTE_CAPABILITY = re.compile(r"[0-9]+\.[0-9]+")
+_TABLE_HEADER = re.compile(
+    r"Driver Version:\s*(?P<driver>[0-9][0-9.]*)\s+CUDA Version:\s*(?P<cuda>[0-9][0-9.]*)"
+)
+_VERSION_LINE = re.compile(r"^\s*(?P<key>[A-Za-z -]+?)\s*:\s*(?P<value>\S+)\s*$", re.MULTILINE)
+
+
+def collect_nvidia(
+    runner: CommandRunner,
+    *,
+    which: Callable[[str], str | None] = shutil.which,
+    timeout: float = TIMEOUT,
+) -> NvidiaFacts:
+    """Ask nvidia-smi for the driver version and the GPUs it can see.
+
+    Only read-only queries are run. A missing nvidia-smi is reported as such; a failing
+    one is recorded as a failure and no further queries are attempted.
+    """
+    smi = which("nvidia-smi")
+    if smi is None:
+        return NvidiaFacts(smi_path=None)
+
+    fields: Sequence[str] = _FIELDS
+    result = runner.run(_query_argv(smi, fields), timeout=timeout, env_overrides=_ENV)
+    if _rejects_field(result, "compute_cap"):
+        # Drivers older than about R510 do not know compute_cap; ask without it.
+        fields = tuple(field for field in _FIELDS if field != "compute_cap")
+        result = runner.run(_query_argv(smi, fields), timeout=timeout, env_overrides=_ENV)
+    if _no_devices(result):
+        # The driver answered but sees no GPU: zero devices is the fact to report.
+        versions = _versions(runner, smi, timeout)
+        return NvidiaFacts(
+            smi_path=smi,
+            driver_version=versions.get("driver version"),
+            max_cuda_version=versions.get("cuda version"),
+        )
+    failure = probe_failure(PROBE, result)
+    if failure is not None:
+        return NvidiaFacts(smi_path=smi, failures=(failure,))
+
+    gpus, driver_version, failures = _parse_query(result.stdout, fields)
+    versions = _versions(runner, smi, timeout)
+    if "cuda version" not in versions:
+        failures.append(_malformed("nvidia-smi did not report the driver's maximum CUDA version"))
+    return NvidiaFacts(
+        smi_path=smi,
+        driver_version=driver_version or versions.get("driver version"),
+        max_cuda_version=versions.get("cuda version"),
+        gpus=tuple(gpus),
+        failures=tuple(failures),
+    )
+
+
+def _versions(runner: CommandRunner, smi: str, timeout: float) -> dict[str, str]:
+    """Driver and maximum CUDA version from ``nvidia-smi --version``, keys lower-cased.
+
+    Its output looks like ``CUDA Version        : 13.2``.
+    """
+    result = runner.run([smi, "--version"], timeout=timeout, env_overrides=_ENV)
+    if result.ok:
+        return {
+            match["key"].strip().lower(): match["value"]
+            for match in _VERSION_LINE.finditer(result.stdout)
+        }
+    # Older drivers have no --version; the classic table's header has both values:
+    # "| NVIDIA-SMI 470.256.02   Driver Version: 470.256.02   CUDA Version: 11.4 |".
+    # Only the header is read; the process list further down is never parsed or kept.
+    table = runner.run([smi], timeout=timeout, env_overrides=_ENV)
+    header = _TABLE_HEADER.search(table.stdout) if table.ok else None
+    if header is None:
+        return {}
+    return {"driver version": header["driver"], "cuda version": header["cuda"]}
+
+
+def _rejects_field(result: CommandResult, field: str) -> bool:
+    # nvidia-smi prints this on stdout: Field "compute_cap" is not a valid field to query.
+    return result.outcome is Outcome.NONZERO and f'"{field}" is not a valid field' in result.stdout
+
+
+def _no_devices(result: CommandResult) -> bool:
+    return result.outcome is Outcome.NONZERO and "no devices were found" in result.stdout.lower()
+
+
+def _query_argv(smi: str, fields: Sequence[str]) -> list[str]:
+    return [smi, f"--query-gpu={','.join(fields)}", "--format=csv,noheader,nounits"]
+
+
+def _parse_query(
+    stdout: str, fields: Sequence[str]
+) -> tuple[list[GpuDevice], str | None, list[ProbeFailure]]:
+    gpus: list[GpuDevice] = []
+    failures: list[ProbeFailure] = []
+    driver_version: str | None = None
+    try:
+        rows = list(csv.reader(stdout.splitlines(), skipinitialspace=True))
+    except csv.Error as exc:
+        return [], None, [_malformed(f"unreadable CSV output: {exc}")]
+    for number, row in enumerate(rows, start=1):
+        if not any(cell.strip() for cell in row):
+            continue
+        if len(row) != len(fields):
+            failures.append(
+                _malformed(f"line {number} has {len(row)} fields, expected {len(fields)}")
+            )
+            continue
+        values = dict(zip(fields, (cell.strip() for cell in row), strict=True))
+        index = _integer(values["index"])
+        name = _value(values["name"])
+        if index is None or name is None:
+            failures.append(_malformed(f"line {number} has no GPU index or name"))
+            continue
+        gpus.append(
+            GpuDevice(
+                index=index,
+                name=name,
+                memory_total_mib=_integer(values.get("memory.total", "")),
+                compute_capability=_compute_capability(values.get("compute_cap", "")),
+            )
+        )
+        driver_version = driver_version or _value(values["driver_version"])
+    return gpus, driver_version, failures
+
+
+def _malformed(detail: str) -> ProbeFailure:
+    return ProbeFailure(PROBE, FailureKind.MALFORMED_OUTPUT, detail)
+
+
+def _value(raw: str) -> str | None:
+    value = raw.strip()
+    return None if value.lower() in _UNAVAILABLE else value
+
+
+def _integer(raw: str) -> int | None:
+    value = _value(raw)
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except ValueError:
+        return None
+
+
+def _compute_capability(raw: str) -> str | None:
+    value = _value(raw)
+    return value if value is not None and _COMPUTE_CAPABILITY.fullmatch(value) else None

gpu_stack_inspector/collectors/python_env.py

@@ -0,0 +1,63 @@
+"""Target Python interpreters, inspected from the outside.
+
+The tool never imports a target environment's packages into its own process; it runs
+the target interpreter as a subprocess.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from gpu_stack_inspector.models import FailureKind, ProbeFailure
+
+PROBE = "python"
+_INTERPRETERS_IN_AN_ENVIRONMENT = (
+    Path("bin", "python"),
+    Path("bin", "python3"),
+    Path("Scripts", "python.exe"),
+    Path("python.exe"),  # conda on Windows
+)
+
+
+def interpreter_path(
+    raw: str, *, cwd: Path | None = None, windows: bool = os.name == "nt"
+) -> tuple[Path | None, ProbeFailure | None]:
+    """Turn a ``--python`` argument into an absolute path that can be run.
+
+    ``~`` is expanded and relative paths are taken from ``cwd``. Symlinks are kept on
+    purpose: a virtual environment's ``bin/python`` is a symlink to the base
+    interpreter, and only the symlink's location tells Python it runs inside the venv.
+    On Windows a path without a suffix also matches ``<path>.exe``, as it does in the
+    shell (``.venv\\Scripts\\python``). Returns the path, or the reason it cannot be used.
+    """
+    text = raw.strip()
+    if not text:
+        return None, _failure(FailureKind.NOT_FOUND, "no interpreter path was given")
+    path = Path(text).expanduser()
+    if not path.is_absolute():
+        path = (cwd or Path.cwd()) / path
+    if windows and not path.exists() and not path.suffix and path.with_suffix(".exe").exists():
+        path = path.with_suffix(".exe")
+    if not path.exists():
+        if path.is_symlink():
+            target = path.readlink()
+            detail = f"{path} is a symlink to {target}, which does not exist"
+        else:
+            detail = f"{path} does not exist"
+        return None, _failure(FailureKind.NOT_FOUND, detail)
+    if path.is_dir():
+        detail = f"{path} is a directory, not an interpreter"
+        inside = next(
+            (path / c for c in _INTERPRETERS_IN_AN_ENVIRONMENT if (path / c).is_file()), None
+        )
+        if inside is not None:
+            detail += f"; did you mean {inside}?"
+        return None, _failure(FailureKind.NOT_FOUND, detail)
+    if not os.access(path, os.X_OK):
+        return None, _failure(FailureKind.PERMISSION_DENIED, f"{path} is not executable")
+    return path, None
+
+
+def _failure(kind: FailureKind, detail: str) -> ProbeFailure:
+    return ProbeFailure(PROBE, kind, detail)