build: Wrap dependency libraries' facade headers with IWYU exports to resolve clang-tidy violations.

CMakeLists.txt

@@ -57,6 +57,7 @@ target_compile_features(${CLP_FFI_PY_LIB_IR} PRIVATE cxx_std_20)
 
 set(CLP_FFI_PY_SRC_DIR "${CMAKE_CURRENT_SOURCE_DIR}/src")
 set(CLP_FFI_PY_LIB_SRC_DIR "${CLP_FFI_PY_SRC_DIR}/clp_ffi_py")
+set(CLP_FFI_PY_WRAPPED_DEPENDENCY_HEADERS_DIR "${CLP_FFI_PY_SRC_DIR}/wrapped_dependency_headers")
 set(CLP_FFI_PY_CLP_CORE_DIR "${CLP_FFI_PY_SRC_DIR}/clp/components/core")
 
 # Add CLP's string_utils
@@ -127,16 +128,23 @@ set(CLP_FFI_PY_LIB_IR_SOURCES
     ${CLP_FFI_PY_LIB_SRC_DIR}/PyExceptionContext.hpp
     ${CLP_FFI_PY_LIB_SRC_DIR}/PyObjectCast.hpp
     ${CLP_FFI_PY_LIB_SRC_DIR}/PyObjectUtils.hpp
-    ${CLP_FFI_PY_LIB_SRC_DIR}/Python.hpp
     ${CLP_FFI_PY_LIB_SRC_DIR}/utils.cpp
     ${CLP_FFI_PY_LIB_SRC_DIR}/utils.hpp
 )
 
+# NOTE: these headers are wrappers of third-party dependency libraries. They are required to silent
+# clang-tidy warnings for missing direct includes.
+set(CLP_FFI_PY_WRAPPED_DEPENDENCY_HEADERS_SOURCES
+    ${CLP_FFI_PY_WRAPPED_DEPENDENCY_HEADERS_DIR}/msgpack.hpp
+    ${CLP_FFI_PY_WRAPPED_DEPENDENCY_HEADERS_DIR}/Python.hpp
+)
+
 target_sources(
     ${CLP_FFI_PY_LIB_IR}
     PRIVATE
         ${CLP_FFI_PY_CLP_CORE_SOURCES}
         ${CLP_FFI_PY_LIB_IR_SOURCES}
+        ${CLP_FFI_PY_WRAPPED_DEPENDENCY_HEADERS_SOURCES}
 )
 
 # NOTE: We mark the include directories below as system headers so that the compiler (including

lint-tasks.yml

@@ -4,7 +4,10 @@ vars:
   G_LINT_VENV_DIR: "{{.BUILD_DIR}}/lint-venv"
   G_LINT_VENV_CHECKSUM_FILE: "{{.BUILD_DIR}}/lint#venv.md5"
   # Linter target dirs
-  G_CPP_LINT_DIRS: ["{{.CLP_FFI_PY_CPP_SRC_DIR}}"]
+  G_CPP_WRAPPED_DEPENDENCY_HEADERS_DIR: "{{.ROOT_DIR}}/src/wrapped_dependency_headers"
+  G_CPP_LINT_DIRS:
+    - "{{.CLP_FFI_PY_CPP_SRC_DIR}}"
+    - "{{.G_CPP_WRAPPED_DEPENDENCY_HEADERS_DIR}}"
   G_PYTHON_LINT_DIRS: ["{{.ROOT_DIR}}/clp_ffi_py", "{{.ROOT_DIR}}/tests"]
 
 tasks:
@@ -108,6 +111,7 @@ tasks:
             # and so that the workflow doesn't fail due to violations in other files.
             - "{{.CLP_FFI_PY_CPP_SRC_DIR}}/Py_utils.cpp"
             - "{{.CLP_FFI_PY_CPP_SRC_DIR}}/Py_utils.hpp"
+            - "{{.G_CPP_WRAPPED_DEPENDENCY_HEADERS_DIR}}"
           VENV_DIR: "{{.G_LINT_VENV_DIR}}"
 
   py-check:

src/clp_ffi_py/.clang-format

@@ -4,13 +4,17 @@ IndentExternBlock: "NoIndent"
 IncludeCategories:
   # NOTE: A header is grouped by first matching regex
   # Python header must be included before any others
-  - Regex: "^<clp_ffi_py/Python\\.hpp>$"
+  - Regex: "^<wrapped_dependency_headers/Python\\.hpp>$"
     Priority: -1
   # Project headers
   - Regex: "^<clp_ffi_py"
     Priority: 4
   # Third-party headers. Update when adding new third-party library
-  - Regex: "<(clp|gsl|json|msgpack|outcome)"
+  - Regex: "<(clp|gsl|json|outcome)"
+    Priority: 3
+  # Third-party headers with wrappers to silent clang-tidy warnings. Update when adding new
+  # third-party library
+  - Regex: "<wrapped_dependency_headers"
     Priority: 3
   # C headers
   - Regex: "^<.*.h>$"

src/clp_ffi_py/PyExceptionContext.hpp

@@ -1,7 +1,7 @@
 #ifndef CLP_FFI_PY_PYEXCEPTIONCONTEXT_HPP
 #define CLP_FFI_PY_PYEXCEPTIONCONTEXT_HPP
 
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 namespace clp_ffi_py {
 /**

src/clp_ffi_py/PyObjectCast.hpp

@@ -1,7 +1,7 @@
 #ifndef CLP_FFI_PY_PY_OBJECT_CAST_HPP
 #define CLP_FFI_PY_PY_OBJECT_CAST_HPP
 
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include <type_traits>
 

src/clp_ffi_py/PyObjectUtils.hpp

@@ -1,7 +1,7 @@
 #ifndef CLP_FFI_PY_PY_OBJECT_UTILS_HPP
 #define CLP_FFI_PY_PY_OBJECT_UTILS_HPP
 
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include <memory>
 

src/clp_ffi_py/Py_utils.cpp

@@ -1,4 +1,4 @@
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header file
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header file
 
 #include "Py_utils.hpp"
 

src/clp_ffi_py/Py_utils.hpp

@@ -1,7 +1,7 @@
 #ifndef CLP_FFI_PY_PY_UTILS_HPP
 #define CLP_FFI_PY_PY_UTILS_HPP
 
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include <string>
 #include <string_view>

src/clp_ffi_py/ir/native/DeserializerBufferReader.cpp

@@ -1,4 +1,4 @@
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include "DeserializerBufferReader.hpp"
 

src/clp_ffi_py/ir/native/DeserializerBufferReader.hpp

@@ -1,7 +1,7 @@
 #ifndef CLP_FFI_PY_IR_NATIVE_DESERIALIZERBUFFERREADER_HPP
 #define CLP_FFI_PY_IR_NATIVE_DESERIALIZERBUFFERREADER_HPP
 
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include <cstddef>
 

src/clp_ffi_py/ir/native/PyDeserializer.cpp

@@ -1,4 +1,4 @@
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include "PyDeserializer.hpp"
 

src/clp_ffi_py/ir/native/PyDeserializer.hpp

@@ -1,7 +1,7 @@
 #ifndef CLP_FFI_PY_IR_NATIVE_PYDESERIALIZER_HPP
 #define CLP_FFI_PY_IR_NATIVE_PYDESERIALIZER_HPP
 
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include <functional>
 #include <system_error>

src/clp_ffi_py/ir/native/PyDeserializerBuffer.cpp

@@ -1,4 +1,4 @@
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include "PyDeserializerBuffer.hpp"
 

src/clp_ffi_py/ir/native/PyDeserializerBuffer.hpp

@@ -1,7 +1,7 @@
 #ifndef CLP_FFI_PY_IR_NATIVE_PYDESERIALIZERBUFFER_HPP
 #define CLP_FFI_PY_IR_NATIVE_PYDESERIALIZERBUFFER_HPP
 
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include <span>
 

src/clp_ffi_py/ir/native/PyFourByteDeserializer.cpp

@@ -1,4 +1,4 @@
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include "PyFourByteDeserializer.hpp"
 

src/clp_ffi_py/ir/native/PyFourByteDeserializer.hpp

@@ -1,7 +1,7 @@
 #ifndef CLP_FFI_PY_IR_NATIVE_PYFOURBYTEDESERIALIZER_HPP
 #define CLP_FFI_PY_IR_NATIVE_PYFOURBYTEDESERIALIZER_HPP
 
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include <clp_ffi_py/PyObjectUtils.hpp>
 

src/clp_ffi_py/ir/native/PyFourByteSerializer.cpp

@@ -1,4 +1,4 @@
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include "PyFourByteSerializer.hpp"
 

src/clp_ffi_py/ir/native/PyFourByteSerializer.hpp

@@ -1,7 +1,7 @@
 #ifndef CLP_FFI_PY_IR_NATIVE_PYFOURBYTESERIALIZER_HPP
 #define CLP_FFI_PY_IR_NATIVE_PYFOURBYTESERIALIZER_HPP
 
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include <clp_ffi_py/PyObjectUtils.hpp>
 

src/clp_ffi_py/ir/native/PyKeyValuePairLogEvent.cpp

@@ -1,4 +1,4 @@
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include "PyKeyValuePairLogEvent.hpp"
 

src/clp_ffi_py/ir/native/PyKeyValuePairLogEvent.hpp

@@ -1,7 +1,7 @@
 #ifndef CLP_FFI_PY_IR_NATIVE_PYKEYVALUEPAIRLOGEVENT_HPP
 #define CLP_FFI_PY_IR_NATIVE_PYKEYVALUEPAIRLOGEVENT_HPP
 
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include <clp/ffi/KeyValuePairLogEvent.hpp>
 #include <gsl/gsl>

src/clp_ffi_py/ir/native/PyLogEvent.cpp

@@ -1,4 +1,4 @@
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include "PyLogEvent.hpp"
 

src/clp_ffi_py/ir/native/PyLogEvent.hpp

@@ -1,7 +1,7 @@
 #ifndef CLP_FFI_PY_IR_NATIVE_PYLOGEVENT_HPP
 #define CLP_FFI_PY_IR_NATIVE_PYLOGEVENT_HPP
 
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include <optional>
 

src/clp_ffi_py/ir/native/PyMetadata.cpp

@@ -1,4 +1,4 @@
-#include <clp_ffi_py/Python.hpp>
+#include <wrapped_dependency_headers/Python.hpp>
 
 #include "PyMetadata.hpp"
 

src/clp_ffi_py/ir/native/PyMetadata.hpp

@@ -1,7 +1,7 @@
 #ifndef CLP_FFI_PY_IR_NATIVE_PYMETADATA_HPP
 #define CLP_FFI_PY_IR_NATIVE_PYMETADATA_HPP
 
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include <json/single_include/nlohmann/json.hpp>
 

src/clp_ffi_py/ir/native/PyQuery.cpp

@@ -1,5 +1,5 @@
 
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include "PyQuery.hpp"
 

src/clp_ffi_py/ir/native/PyQuery.hpp

@@ -1,7 +1,7 @@
 #ifndef CLP_FFI_PY_IR_NATIVE_PYQUERY_HPP
 #define CLP_FFI_PY_IR_NATIVE_PYQUERY_HPP
 
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include <clp_ffi_py/ir/native/Query.hpp>
 #include <clp_ffi_py/PyObjectUtils.hpp>

src/clp_ffi_py/ir/native/PySerializer.cpp

@@ -1,4 +1,4 @@
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include "PySerializer.hpp"
 

src/clp_ffi_py/ir/native/PySerializer.hpp

@@ -1,7 +1,7 @@
 #ifndef CLP_FFI_PY_IR_NATIVE_PYSERIALIZER_HPP
 #define CLP_FFI_PY_IR_NATIVE_PYSERIALIZER_HPP
 
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include <cstddef>
 #include <optional>

src/clp_ffi_py/ir/native/deserialization_methods.cpp

@@ -1,4 +1,4 @@
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include "deserialization_methods.hpp"
 

src/clp_ffi_py/ir/native/deserialization_methods.hpp

@@ -1,7 +1,7 @@
 #ifndef CLP_FFI_PY_IR_NATIVE_DESERIALIZATION_METHODS
 #define CLP_FFI_PY_IR_NATIVE_DESERIALIZATION_METHODS
 
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 // Documentation for these methods is in clp/ir/native/PyDeserializer.cpp, as it also serves as the
 // documentation for Python.

src/clp_ffi_py/ir/native/serialization_methods.cpp

@@ -1,4 +1,4 @@
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include "serialization_methods.hpp"
 

src/clp_ffi_py/ir/native/serialization_methods.hpp

@@ -1,7 +1,7 @@
 #ifndef CLP_FFI_PY_IR_NATIVE_SERIALIZATION_METHODS
 #define CLP_FFI_PY_IR_NATIVE_SERIALIZATION_METHODS
 
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 // Documentation for these methods is in clp_ffi_py/ir/native/PyFourByteSerializer.cpp, as it also
 // serves as the documentation for python.

src/clp_ffi_py/modules/ir_native.cpp

@@ -1,4 +1,4 @@
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include <clp_ffi_py/ir/native/PyDeserializer.hpp>
 #include <clp_ffi_py/ir/native/PyDeserializerBuffer.hpp>

src/clp_ffi_py/utils.cpp

@@ -1,4 +1,4 @@
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include "utils.hpp"
 
@@ -7,8 +7,8 @@
 #include <string>
 
 #include <clp/TraceableException.hpp>
-#include <msgpack.hpp>
 #include <outcome/single-header/outcome.hpp>
+#include <wrapped_dependency_headers/msgpack.hpp>
 
 #include <clp_ffi_py/ExceptionFFI.hpp>
 #include <clp_ffi_py/PyObjectCast.hpp>

src/clp_ffi_py/utils.hpp

@@ -1,7 +1,7 @@
 #ifndef CLP_FFI_PY_UTILS_HPP
 #define CLP_FFI_PY_UTILS_HPP
 
-#include <clp_ffi_py/Python.hpp>  // Must always be included before any other header files
+#include <wrapped_dependency_headers/Python.hpp>  // Must be included before any other header files
 
 #include <iostream>
 #include <span>
@@ -12,8 +12,8 @@
 
 #include <clp/ffi/encoding_methods.hpp>
 #include <clp/TraceableException.hpp>
-#include <msgpack.hpp>
 #include <outcome/single-header/outcome.hpp>
+#include <wrapped_dependency_headers/msgpack.hpp>
 
 namespace clp_ffi_py {
 /**

src/clp_ffi_py/Python.hpp → src/wrapped_dependency_headers/Python.hpp

@@ -5,9 +5,11 @@
  * 1. https://docs.python.org/3/c-api/intro.html#include-files
  * 2. https://docs.python.org/3/c-api/arg.html#strings-and-buffers
  */
+// IWYU pragma: begin_exports
 #define PY_SSIZE_T_CLEAN
 #include <Python.h>
 #include <structmember.h>
+// IWYU pragma: end_exports
 
 // clang-format off
 #ifdef CLP_FFI_PY_ENABLE_LINTING

src/wrapped_dependency_headers/msgpack.hpp

@@ -0,0 +1,13 @@
+// IWYU pragma: begin_exports
+#define PY_SSIZE_T_CLEAN
+#include <msgpack.hpp>
+// IWYU pragma: end_exports
+
+// clang-format off
+#ifdef CLP_FFI_PY_ENABLE_LINTING
+// Inform IWYU of the headers that we use that are exported by msgpack.hpp
+// IWYU pragma: begin_exports
+// TODO: add necessary msgpack internal headers to silent clang-tidy warnings
+// IWYU pragma: end_exports
+#endif
+// clang-format on