clang-tidy as part of the actual build

cuda_core/.clang-tidy

@@ -0,0 +1,70 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# Layout is clang-format's job (see .clang-format), so clang-tidy does no
+# formatting of its own (FormatStyle: none below). Each enabled check is meant
+# to be adoptable on its own, so findings can be fixed one check at a time.
+#
+# Checks are opt-in (-*) by group, minus the ones below. They cannot be
+# commented inline because Checks is a single YAML string.
+#
+# Disabled because they conflict with the C-style CUDA driver API idioms:
+#   bugprone-easily-swappable-parameters: wrappers of driver calls take many
+#       adjacent parameters of the same type; the signatures mirror the API.
+#   bugprone-assignment-in-if-condition: `if (CUDA_SUCCESS != (err = CALL(...)))`
+#       is the standard error-handling pattern here.
+#   performance-no-int-to-ptr: opaque handles and file descriptors are
+#       converted to pointers with reinterpret_cast on purpose.
+#   modernize-avoid-c-arrays: arrays are passed to and filled by C APIs.
+#   modernize-return-braced-init-list: `return {};` vs. an explicit type is
+#       left to the author; it adds noise for the driver-API result structs.
+#   bugprone-throwing-static-initialization: the handle registries are
+#       process-lifetime globals whose constructors allocate on some standard
+#       libraries (MSVC); running out of memory while loading the module is
+#       fatal either way.
+#
+# Disabled because they do not match the codebase style:
+#   performance-enum-size: enum underlying types are left as they are.
+#   misc-const-correctness: const on every local is not the convention here.
+#   readability-function-cognitive-complexity: too disruptive.
+#   readability-identifier-length: short names such as the handle parameter `h`
+#       are used throughout.
+#   readability-implicit-bool-conversion: `if (ptr)` and `if (handle)` are the
+#       idiom for pointers and handles.
+#   misc-include-cleaner: too noisy with the CUDA and CPython umbrella headers.
+#   misc-no-recursion: recursion is used deliberately.
+#   misc-use-anonymous-namespace: file-local functions use `static`.
+#   modernize-use-trailing-return-type: the code uses `Type\nname()` layout.
+Checks: >
+  -*,
+  bugprone-*,
+  -bugprone-easily-swappable-parameters,
+  -bugprone-assignment-in-if-condition,
+  -bugprone-throwing-static-initialization,
+  clang-analyzer-*,
+  misc-*,
+  -misc-include-cleaner,
+  -misc-const-correctness,
+  -misc-no-recursion,
+  -misc-use-anonymous-namespace,
+  modernize-*,
+  -modernize-use-trailing-return-type,
+  -modernize-avoid-c-arrays,
+  -modernize-return-braced-init-list,
+  performance-*,
+  -performance-enum-size,
+  -performance-no-int-to-ptr,
+  readability-*,
+  -readability-function-cognitive-complexity,
+  -readability-identifier-length,
+  -readability-implicit-bool-conversion
+FormatStyle: none
+CheckOptions:
+  # Records whose members are all public (the *Box and guard structs) are plain
+  # data holders; only a mix of public and private members is flagged.
+  misc-non-private-member-variables-in-classes.IgnoreClassesWithAllMemberVariablesBeingPublic: true
+WarningsAsErrors: '*'
+# Only report diagnostics for our own headers, not CUDA/CPython/libstdc++.
+HeaderFilterRegex: 'cuda/core/_(cpp|include)/'
+ExcludeHeaderFilterRegex: 'cuda/core/_include/(dlpack|aoti_shim)\.h'

cuda_core/MANIFEST.in

@@ -6,6 +6,8 @@ recursive-include cuda/core *.pyx *.pxd *.pxi *.pyi
 recursive-include cuda/core/_cpp *.cpp *.h *.hpp
 recursive-include cuda/core/_include *.h *.hpp *.def
 include build_hooks.py
+# configuration of the clang-tidy run in the build
+include .clang-tidy
 include cuda/core/py.typed
 include NOTICE
 # package-local shared PEP 517 helper

cuda_core/build_hooks.py

@@ -12,6 +12,7 @@
 import importlib.util
 import os
 import re
+import subprocess
 import sys
 import tempfile
 import zipfile
@@ -704,6 +705,59 @@ def build_wheel(wheel_directory, config_settings=None, metadata_directory=None):
     return wheel_name
 
 
+def _find_clang_tidy() -> str:
+    """The clang-tidy executable of the clang-tidy wheel in the build environment.
+
+    The wheel is a build-system requirement in pyproject.toml.
+
+    It is located through the wheel's ``clang_tidy`` package, never PATH, so a
+    system clang-tidy cannot be picked up. Raises RuntimeError when the wheel is
+    not installed.
+    """
+    spec = importlib.util.find_spec("clang_tidy")
+    if spec is not None and spec.submodule_search_locations is not None:
+        exe = "clang-tidy"
+        if sys.platform == "win32":
+            exe = "clang-tidy.exe"
+        for base in spec.submodule_search_locations:
+            candidate = Path(base) / "data" / "bin" / exe
+            if candidate.is_file():
+                return str(candidate)
+    raise RuntimeError(
+        "The clang-tidy build requirement of pyproject.toml is not installed. Isolated builds install it "
+        "automatically. For other builds, install the pinned version of it."
+    )
+
+
+def _is_handwritten_cpp(path) -> bool:
+    """Whether path is a handwritten C++ source, not a Cython-generated one."""
+    path = Path(path)
+    return path.suffix == ".cpp" and path.resolve().is_relative_to(_PACKAGE_DIR / "_cpp")
+
+
+def check_with_clang_tidy(compile_command) -> None:
+    """Run clang-tidy on the handwritten .cpp that a compiler command line compiles.
+
+    ``compile_command`` is the exact command that setuptools is about to spawn,
+    so clang-tidy sees the same compiler, include directories, macros and
+    flags as the build. Commands that do not compile a handwritten source are
+    ignored. The configuration is cuda_core/.clang-tidy, which turns every
+    finding into an error. Raises RuntimeError with the findings.
+    """
+    sources = [arg for arg in compile_command if _is_handwritten_cpp(arg)]
+    if not sources:
+        return
+    (source,) = sources
+    config = Path(__file__).resolve().parent / ".clang-tidy"
+    result = subprocess.run(  # noqa: S603
+        [_find_clang_tidy(), f"--config-file={config}", "--quiet", source, "--", *compile_command],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"clang-tidy reported errors in {source}:\n{result.stdout}{result.stderr}")
+
+
 def _get_cuda_bindings_require():
     """The cuda-bindings build requirement for isolated builds.
 

cuda_core/cuda/core/_cpp/rt/context.cpp

@@ -125,15 +125,15 @@ struct GreenCtxBox {
     CUgreenCtx resource;
 };
 
-static const ContextBox *
+const ContextBox *
 get_box(const ContextHandle &h) noexcept
 {
     const CUcontext *p = h.get();
     return reinterpret_cast<const ContextBox *>(reinterpret_cast<const char *>(p) - offsetof(ContextBox, resource));
 }
 
 // See REGISTRY_DESIGN.md (Level 1: Driver Handle -> Resource Handle)
-static HandleRegistry<CUcontext, ContextHandle> context_registry;
+HandleRegistry<CUcontext, ContextHandle> context_registry;
 
 // Create a context handle reference, with optional green context as source.
 ContextHandle

cuda_core/cuda/core/_cpp/rt/context_scope.hpp

@@ -126,7 +126,7 @@ cleanup_in_context(
     }
     std::invoke(std::forward<AfterCleanup>(after_cleanup));
     if (status != CUDA_SUCCESS || restore != CUDA_SUCCESS) {
-        char operation_name[160];
+        char operation_name[kOperationNameSize];
         format_operation(operation_name, sizeof(operation_name), name, handle);
         if (status != CUDA_SUCCESS) {
             report_cuda_error(operation_name, status, detail);

cuda_core/cuda/core/_cpp/rt/driver_api.cpp

@@ -9,7 +9,7 @@
 namespace cuda_core::rt {
 
 // The pointers. Null until ensure_fn_table() fills the table. See driver_api.hpp.
-#define CUDA_CORE_DEFINE_DRIVER_FN(name, introduced) decltype(&name) p_##name = nullptr;
+#define CUDA_CORE_DEFINE_DRIVER_FN(name, introduced) decltype(&(name)) p_##name = nullptr;
 CUDA_CORE_DRIVER_FUNCTIONS(CUDA_CORE_DEFINE_DRIVER_FN)
 #undef CUDA_CORE_DEFINE_DRIVER_FN
 

cuda_core/cuda/core/_cpp/rt/driver_api.hpp

@@ -141,7 +141,7 @@ namespace cuda_core::rt {
     X(cuStreamIsCapturing, 10000)                                               \
     X(cuThreadExchangeStreamCaptureMode, 10010)
 
-#define CUDA_CORE_DECLARE_DRIVER_FN(name, introduced) extern decltype(&name) p_##name;
+#define CUDA_CORE_DECLARE_DRIVER_FN(name, introduced) extern decltype(&(name)) p_##name;
 CUDA_CORE_DRIVER_FUNCTIONS(CUDA_CORE_DECLARE_DRIVER_FN)
 #undef CUDA_CORE_DECLARE_DRIVER_FN
 
@@ -229,7 +229,7 @@ struct Unavailable;
 template <class R, class... A>
 struct Unavailable<R (*)(A...)> {
     static R
-    call(A...) noexcept
+    call(A... /*unused*/) noexcept
     {
         return UnavailableStatus<R>::value;
     }

cuda_core/cuda/core/_cpp/rt/error.cpp

@@ -27,8 +27,8 @@ namespace {
 // Thread-local detail attached to the next raised CUDAError with a matching
 // status (see take_last_error_detail()). Written only by propagating helpers.
 // The taken copy stays valid until the next take on the same thread.
-thread_local char last_error_detail[512] = {0};
-thread_local char taken_error_detail[512] = {0};
+thread_local char last_error_detail[kErrorMessageSize] = {0};
+thread_local char taken_error_detail[kErrorMessageSize] = {0};
 thread_local CUresult last_error_detail_status = CUDA_SUCCESS;
 }  // namespace
 
@@ -66,7 +66,7 @@ format_operation(char *buffer, size_t size, const char *operation, unsigned long
 void
 report_status_code(const char *operation, long code) noexcept
 {
-    char message[256];
+    char message[kErrorMessageSize];
     std::snprintf(message, sizeof(message), "%s failed (status %ld)", operation, code);
     report_message(message);
 }
@@ -80,7 +80,7 @@ report_cuda_error(const char *operation, CUresult status, const char *detail) no
     if (status == CUDA_SUCCESS || status == CUDA_ERROR_DEINITIALIZED) {
         return;
     }
-    char message[512];
+    char message[kErrorMessageSize];
     format_cuda_error(message, sizeof(message), operation, status, detail);
     report_message(message);
 }
@@ -122,7 +122,7 @@ note_context_not_restored(CUcontext previous, CUresult operation_status, CUresul
     if (DRIVER_CALL(cuCtxGetCurrent, &current) != CUDA_SUCCESS) {
         current = nullptr;
     }
-    char cause[128] = {0};
+    char cause[kErrorMessageSize] = {0};
     if (operation_status != CUDA_SUCCESS) {
         const char *error_name = nullptr;
         if (DRIVER_CALL(cuGetErrorName, restore_status, &error_name) == CUDA_SUCCESS) {

cuda_core/cuda/core/_cpp/rt/error.hpp

@@ -5,9 +5,17 @@
 #pragma once
 
 #include <cuda.h>
+#include <cstddef>
 
 namespace cuda_core::rt {
 
+// Sizes of the stack buffers that format error text. Messages are truncated by
+// snprintf, never overrun.
+constexpr std::size_t kOperationNameSize = 160;  // "<call> (handle 0x...)" from format_operation()
+constexpr std::size_t kErrorMessageSize = 512;   // a full error message or error detail
+// A message that embeds one error message after some fixed text.
+constexpr std::size_t kNestedMessageSize = kErrorMessageSize + (kErrorMessageSize / 2);
+
 // ============================================================================
 // Thread-local error handling
 // ============================================================================

cuda_core/cuda/core/_cpp/rt/graph.cpp

@@ -83,9 +83,10 @@ struct GraphBox : GraphBoxBase {
     GraphAttachmentMap attachments;       // Non-owning attachment index.
     HandleRegistry<CUgraphNode, GraphNodeHandle> node_handles;
 
+    // Not noexcept: the std::map and HandleRegistry members allocate.
     GraphBox(
         CUgraph resource_, GraphHierarchy *hierarchy_, GraphBox *parent_ = nullptr, CUgraphNode owner_node_ = nullptr
-    ) noexcept
+    )
         : GraphBoxBase{resource_}, hierarchy(hierarchy_), parent(parent_), owner_node(owner_node_)
     {
     }
@@ -106,7 +107,7 @@ struct GraphHierarchy {
 
 // See REGISTRY_DESIGN.md (Level 1: Driver Handle -> Resource Handle)
 using GraphRegistry = HandleRegistry<CUgraph, GraphHandle>;
-static GraphRegistry graph_registry;
+GraphRegistry graph_registry;
 
 // Immutable resource owners for one version of a graph node's parameters.
 // Inheriting DeferredCleanupItem lets CUDA's user-object destructor enqueue
@@ -140,7 +141,7 @@ free_deleter(const void *p) noexcept
 GraphBox *
 get_box(const GraphHandle &h) noexcept
 {
-    auto *value = reinterpret_cast<const GraphBoxBase *>(h.get());
+    const auto *value = reinterpret_cast<const GraphBoxBase *>(h.get());
     return const_cast<GraphBox *>(static_cast<const GraphBox *>(value));
 }
 
@@ -254,7 +255,7 @@ struct PreparedAttachmentState {
     explicit PreparedAttachmentState(GraphHandle h_graph_) : h_graph(std::move(h_graph_)) {}
 };
 
-void
+static void
 rollback_prepared_attachment(PreparedAttachmentState *state) noexcept
 {
     if (!state) {
@@ -389,7 +390,7 @@ graph_prepare_child_graph_update(
     return CUDA_SUCCESS;
 }
 
-void
+static void
 publish_child_graph_update(PreparedChildGraphUpdateState &state, GraphHandle *out_child)
 {
     GraphBox *parent = get_box(state.h_parent);

cuda_core/cuda/core/_cpp/rt/graph_exec.cpp

@@ -92,7 +92,7 @@ struct ExecAttachmentStaging {
         if (!h_source || !accumulator) {
             return CUDA_SUCCESS;
         }
-        const CUuserObject object = accumulator->object;
+        CUuserObject object = accumulator->object;
         const GraphHandle source = std::move(h_source);
         accumulator = nullptr;
         GILReleaseGuard gil;
@@ -154,7 +154,7 @@ struct PreparedExecAttachmentState {
     }
 };
 
-void
+static void
 rollback_prepared_exec_attachment(PreparedExecAttachmentState *state) noexcept
 {
     if (!state) {