fix(pathfinder): change found_via from "CUDA_HOME" to "CUDA_PATH"

Aligns the provenance label with the new CUDA_PATH-first priority.
The label signals the highest-priority env var name, not necessarily
which variable supplied the value.

Discovered via independent review from GPT-5.4 Extra High

Made-with: Cursor

Author: rwgk

cuda_pathfinder/cuda/pathfinder/_dynamic_libs/load_dl_common.py

@@ -28,7 +28,7 @@ class LoadedDL:
     abs_path: str | None
     was_already_loaded_from_elsewhere: bool
     _handle_uint: int  # Platform-agnostic unsigned pointer value
-    found_via: str
+    found_via: str  # "CUDA_PATH" covers both CUDA_PATH and CUDA_HOME env vars
 
 
 def load_dependencies(desc: LibDescriptor, load_func: Callable[[str], LoadedDL]) -> None:

cuda_pathfinder/cuda/pathfinder/_dynamic_libs/search_steps.py

@@ -183,20 +183,23 @@ def find_in_conda(ctx: SearchContext) -> FindResult | None:
 
 
 def find_in_cuda_home(ctx: SearchContext) -> FindResult | None:
-    """Search ``$CUDA_HOME`` / ``$CUDA_PATH``.
+    """Search ``$CUDA_PATH`` / ``$CUDA_HOME``.
 
     On Windows, this is the normal fallback for system-installed CTK DLLs when
     they are not already discoverable via the native ``LoadLibraryExW(..., 0)``
     path used by :func:`cuda.pathfinder._dynamic_libs.load_dl_windows.load_with_system_search`.
     Python 3.8+ does not include ``PATH`` in that native DLL search.
+
+    The returned ``found_via`` is always ``"CUDA_PATH"`` regardless of which
+    environment variable actually provided the value.
     """
     cuda_home = get_cuda_path_or_home()
     if cuda_home is None:
         return None
     lib_dir = _find_lib_dir_using_anchor(ctx.desc, ctx.platform, cuda_home)
     abs_path = _find_using_lib_dir(ctx, lib_dir)
     if abs_path is not None:
-        return FindResult(abs_path, "CUDA_HOME")
+        return FindResult(abs_path, "CUDA_PATH")
     return None
 
 

cuda_pathfinder/cuda/pathfinder/_headers/find_nvidia_headers.py

@@ -107,7 +107,7 @@ def find_in_cuda_home(desc: HeaderDescriptor) -> LocatedHeaderDir | None:
         return None
     result = _locate_in_anchor_layout(desc, cuda_home)
     if result is not None:
-        return LocatedHeaderDir(abs_path=result, found_via="CUDA_HOME")
+        return LocatedHeaderDir(abs_path=result, found_via="CUDA_PATH")
     return None
 
 

cuda_pathfinder/cuda/pathfinder/_static_libs/find_bitcode_lib.py

@@ -145,7 +145,7 @@ def locate_bitcode_lib(name: str) -> LocatedBitcodeLib:
             name=name,
             abs_path=abs_path,
             filename=finder.filename,
-            found_via="CUDA_HOME",
+            found_via="CUDA_PATH",
         )
 
     finder.raise_not_found_error()

cuda_pathfinder/cuda/pathfinder/_static_libs/find_static_lib.py

@@ -149,7 +149,7 @@ def locate_static_lib(name: str) -> LocatedStaticLib:
             name=name,
             abs_path=abs_path,
             filename=finder.filename,
-            found_via="CUDA_HOME",
+            found_via="CUDA_PATH",
         )
 
     finder.raise_not_found_error()

cuda_pathfinder/docs/source/release/1.5.0-notes.rst

@@ -15,6 +15,13 @@ Breaking Change
   a warning will be issued and ``CUDA_PATH`` will be used. This change aligns
   with industry standards and NVIDIA's recommended practices.
 
+  The ``found_via`` provenance field on ``LoadedDL``, ``LocatedHeaderDir``,
+  ``LocatedStaticLib``, and ``LocatedBitcodeLib`` now reports ``"CUDA_PATH"``
+  (previously ``"CUDA_HOME"``) when a library or header was discovered through
+  the ``CUDA_PATH``/``CUDA_HOME`` environment variables. The label reflects
+  the highest-priority variable name, not necessarily the variable that
+  supplied the value.
+
   **Migration Guide**:
 
   - If you rely on ``CUDA_HOME``, consider switching to ``CUDA_PATH``

cuda_pathfinder/tests/test_ctk_root_discovery.py

@@ -424,7 +424,7 @@ def test_cuda_home_takes_priority_over_canary(tmp_path, mocker):
     result = _load_lib_no_cache("nvvm")
 
     # CUDA_HOME must win; the canary should never have been consulted
-    assert result.found_via == "CUDA_HOME"
+    assert result.found_via == "CUDA_PATH"
     assert result.abs_path == str(nvvm_home_lib)
     canary_mock.assert_not_called()
 

cuda_pathfinder/tests/test_find_bitcode_lib.py

@@ -54,7 +54,7 @@ def _located_bitcode_lib_asserts(located_bitcode_lib):
     assert isinstance(located_bitcode_lib.abs_path, str)
     assert isinstance(located_bitcode_lib.filename, str)
     assert isinstance(located_bitcode_lib.found_via, str)
-    assert located_bitcode_lib.found_via in ("site-packages", "conda", "CUDA_HOME")
+    assert located_bitcode_lib.found_via in ("site-packages", "conda", "CUDA_PATH")
     assert os.path.isfile(located_bitcode_lib.abs_path)
 
 
@@ -110,7 +110,7 @@ def test_locate_bitcode_lib_search_order(monkeypatch, tmp_path):
 
     located_lib = locate_bitcode_lib("device")
     assert located_lib.abs_path == cuda_home_path
-    assert located_lib.found_via == "CUDA_HOME"
+    assert located_lib.found_via == "CUDA_PATH"
 
 
 @pytest.mark.usefixtures("clear_find_bitcode_lib_cache")

cuda_pathfinder/tests/test_find_nvidia_headers.py

@@ -56,7 +56,7 @@ def _located_hdr_dir_asserts(located_hdr_dir):
     assert located_hdr_dir.found_via in (
         "site-packages",
         "conda",
-        "CUDA_HOME",
+        "CUDA_PATH",
         "system-ctk-root",
         "supported_install_dir",
     )
@@ -201,7 +201,7 @@ def test_locate_ctk_headers_cuda_home_takes_priority_over_canary(tmp_path, monke
 
     assert located_hdr_dir is not None
     assert located_hdr_dir.abs_path == expected_hdr_dir
-    assert located_hdr_dir.found_via == "CUDA_HOME"
+    assert located_hdr_dir.found_via == "CUDA_PATH"
     probe.assert_not_called()
 
 

cuda_pathfinder/tests/test_find_static_lib.py

@@ -51,7 +51,7 @@ def _located_static_lib_asserts(located_static_lib):
     assert isinstance(located_static_lib.abs_path, str)
     assert isinstance(located_static_lib.filename, str)
     assert isinstance(located_static_lib.found_via, str)
-    assert located_static_lib.found_via in ("site-packages", "conda", "CUDA_HOME")
+    assert located_static_lib.found_via in ("site-packages", "conda", "CUDA_PATH")
     assert os.path.isfile(located_static_lib.abs_path)
 
 
@@ -114,7 +114,7 @@ def test_locate_static_lib_search_order(monkeypatch, tmp_path):
 
     located_lib = locate_static_lib("cudadevrt")
     assert located_lib.abs_path == cuda_home_path
-    assert located_lib.found_via == "CUDA_HOME"
+    assert located_lib.found_via == "CUDA_PATH"
 
 
 @pytest.mark.usefixtures("clear_find_static_lib_cache")