Add clang-tidy plugin for modernize-nlohmann-json-explicit-conversions

Add a clang-tidy plugin containing one check to replace implicit
conversions with explicit ones.

Being able to test the plugin in a similar way to how checks are tested
within clang-tidy itself requires copying the check_clang_tidy.py script
from the LLVM code itself.

The check itself is virtually identical to the one proposed for
inclusion in clang-tidy itself at
llvm/llvm-project#126425 .

Unfortunately it is necessary to add "C" to the languages for the
project in CMakeLists.txt for find_package to work for LLVM.

Author: mikecrowe

CMakeLists.txt

@@ -4,7 +4,7 @@ cmake_minimum_required(VERSION 3.1...3.14)
 ## PROJECT
 ## name and version
 ##
-project(nlohmann_json VERSION 3.11.3 LANGUAGES CXX)
+project(nlohmann_json VERSION 3.11.3 LANGUAGES C CXX)
 
 ##
 ## MAIN_PROJECT CHECK
@@ -48,6 +48,7 @@ option(JSON_LegacyDiscardedValueComparison "Enable legacy discarded value compar
 option(JSON_Install                        "Install CMake targets during install step." ${MAIN_PROJECT})
 option(JSON_MultipleHeaders                "Use non-amalgamated version of the library." ON)
 option(JSON_SystemInclude                  "Include as system headers (skip for clang-tidy)." OFF)
+option(JSON_ClangTidyPlugin                "Build clang-tidy plug-in." OFF)
 
 if (JSON_CI)
     include(ci)
@@ -158,6 +159,12 @@ CONFIGURE_FILE(
     @ONLY
 )
 
+if (JSON_ClangTidyPlugin)
+    find_package(LLVM REQUIRED CONFIG)
+    find_package(Clang REQUIRED CONFIG)
+    add_subdirectory(clang_tidy_plugin)
+endif()
+
 ##
 ## TESTS
 ## create and configure the unit test target

clang_tidy_plugin/CMakeLists.txt

@@ -0,0 +1,11 @@
+add_library(NlohmannJsonClangTidyPlugin MODULE "")
+target_compile_options(NlohmannJsonClangTidyPlugin PRIVATE -fno-rtti)
+target_include_directories(NlohmannJsonClangTidyPlugin
+    PRIVATE
+        ${CLANG_INCLUDE_DIRS}
+        ${LLVM_INCLUDE_DIRS}
+)
+target_sources(NlohmannJsonClangTidyPlugin PRIVATE
+  ${CMAKE_CURRENT_LIST_DIR}/Module.cpp
+  ${CMAKE_CURRENT_LIST_DIR}/ModernizeNlohmannJsonExplicitConversionsCheck.cpp
+)

clang_tidy_plugin/ModernizeNlohmannJsonExplicitConversionsCheck.cpp

@@ -0,0 +1,67 @@
+// SPDX-FileCopyrightText: 2025 Mike Crowe
+// SPDX-License-Identifier: MIT
+
+#include "ModernizeNlohmannJsonExplicitConversionsCheck.h"
+#include "clang/ASTMatchers/ASTMatchFinder.h"
+#include "clang/Lex/Lexer.h"
+
+using namespace clang::ast_matchers;
+
+namespace clang::tidy::modernize {
+
+void NlohmannJsonExplicitConversionsCheck::registerMatchers(
+    MatchFinder *Finder) {
+  auto Matcher =
+      cxxMemberCallExpr(
+          on(expr().bind("arg")),
+          callee(cxxConversionDecl(ofClass(hasName("nlohmann::basic_json")))
+                     .bind("conversionDecl")))
+          .bind("conversionCall");
+  Finder->addMatcher(Matcher, this);
+}
+
+void NlohmannJsonExplicitConversionsCheck::check(
+    const MatchFinder::MatchResult &Result) {
+  const auto *Decl =
+      Result.Nodes.getNodeAs<CXXConversionDecl>("conversionDecl");
+  const auto *Call =
+      Result.Nodes.getNodeAs<CXXMemberCallExpr>("conversionCall");
+  const auto *Arg = Result.Nodes.getNodeAs<Expr>("arg");
+
+  const QualType DestinationType = Decl->getConversionType();
+  std::string DestinationTypeStr =
+      DestinationType.getAsString(Result.Context->getPrintingPolicy());
+  if (DestinationTypeStr == "std::basic_string<char>")
+    DestinationTypeStr = "std::string";
+
+  const SourceRange ExprRange = Call->getSourceRange();
+  if (!ExprRange.isValid())
+    return;
+
+  bool Deref = false;
+  if (const auto *Op = llvm::dyn_cast<UnaryOperator>(Arg);
+      Op && Op->getOpcode() == UO_Deref)
+    Deref = true;
+  else if (const auto *Op = llvm::dyn_cast<CXXOperatorCallExpr>(Arg);
+           Op && Op->getOperator() == OO_Star)
+    Deref = true;
+
+  llvm::StringRef SourceText = clang::Lexer::getSourceText(
+      clang::CharSourceRange::getTokenRange(ExprRange), *Result.SourceManager,
+      Result.Context->getLangOpts());
+
+  if (Deref)
+    SourceText.consume_front("*");
+
+  const std::string ReplacementText =
+      (llvm::Twine(SourceText) + (Deref ? "->" : ".") + "get<" +
+       DestinationTypeStr + ">()")
+          .str();
+  diag(Call->getExprLoc(),
+       "implicit nlohmann::json conversion to %0 should be explicit")
+      << DestinationTypeStr
+      << FixItHint::CreateReplacement(CharSourceRange::getTokenRange(ExprRange),
+                                      ReplacementText);
+}
+
+} // namespace clang::tidy::modernize

clang_tidy_plugin/ModernizeNlohmannJsonExplicitConversionsCheck.h

@@ -0,0 +1,31 @@
+// SPDX-FileCopyrightText: 2025 Mike Crowe
+// SPDX-License-Identifier: MIT
+
+#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_MODERNIZE_NLOHMANNJSONEXPLICITCONVERSIONSCHECK_H
+#define LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_MODERNIZE_NLOHMANNJSONEXPLICITCONVERSIONSCHECK_H
+
+#include "clang-tidy/ClangTidyCheck.h"
+
+namespace clang::tidy::modernize {
+
+/// Convert implicit conversions via operator ValueType() from nlohmann::json to
+/// explicit calls to the get<> method because the next major version of the
+/// library will remove support for implicit conversions.
+///
+/// For the user-facing documentation see:
+/// https://clang.llvm.org/extra/clang-tidy/checks/modernize/nlohmann-json-explicit-conversions.html
+class NlohmannJsonExplicitConversionsCheck : public ClangTidyCheck {
+public:
+  NlohmannJsonExplicitConversionsCheck(StringRef Name,
+                                       ClangTidyContext *Context)
+      : ClangTidyCheck(Name, Context) {}
+  void registerMatchers(ast_matchers::MatchFinder *Finder) override;
+  void check(const ast_matchers::MatchFinder::MatchResult &Result) override;
+  bool isLanguageVersionSupported(const LangOptions &LangOpts) const override {
+    return LangOpts.CPlusPlus;
+  }
+};
+
+} // namespace clang::tidy::modernize
+
+#endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_MODERNIZE_NLOHMANNJSONEXPLICITCONVERSIONSCHECK_H

clang_tidy_plugin/Module.cpp

@@ -0,0 +1,31 @@
+// SPDX-FileCopyrightText: 2025 Mike Crowe
+// SPDX-License-Identifier: MIT
+
+#include "clang-tidy/ClangTidyModule.h"
+#include "clang-tidy/ClangTidyModuleRegistry.h"
+#include "ModernizeNlohmannJsonExplicitConversionsCheck.h"
+
+namespace {
+
+    using namespace clang::tidy;
+
+class NlohmannJsonChecksModule : public ClangTidyModule
+{
+public:
+    void addCheckFactories(ClangTidyCheckFactories& CheckFactories) override
+    {
+        CheckFactories.registerCheck<clang::tidy::modernize::NlohmannJsonExplicitConversionsCheck>(
+            "modernize-nlohmann-json-explicit-conversions");
+    }
+};
+
+}  // namespace
+
+namespace clang::tidy {
+
+// Register the module using this statically initialized variable.
+    static ClangTidyModuleRegistry::Add<::NlohmannJsonChecksModule> nlohmannJsonChecksInit(
+    "nlohmann-json-checks-module",
+    "Adds 'modernize-nlohmann-json-explicit-conversions' check.");
+
+}  // namespace clang::tidy

tests/CMakeLists.txt

@@ -168,6 +168,10 @@ json_test_add_test_for(src/unit-comparison.cpp
 
 add_subdirectory(abi)
 
+if (JSON_ClangTidyPlugin)
+    add_subdirectory(clang_tidy_plugin)
+endif()
+
 #############################################################################
 # Test the generated build configs
 #############################################################################

tests/clang_tidy_plugin/CMakeLists.txt

@@ -0,0 +1,10 @@
+include(CTest)
+
+if(NOT LLVM_TOOLS_BINARY_DIR)
+    message(FATAL_ERROR "Could not determine LLVM binary directory")
+endif()
+
+add_test(NAME modernize-nlohmann-json-explicit-conversions-check COMMAND ${CMAKE_COMMAND} -E env PATH=${LLVM_TOOLS_BINARY_DIR}:$ENV{PATH}
+  ${CMAKE_CURRENT_LIST_DIR}/check_clang_tidy.py -std=c++17
+  -plugin=$<TARGET_FILE:NlohmannJsonClangTidyPlugin>
+  ${CMAKE_CURRENT_LIST_DIR}/modernize-nlohmann-json-explicit-conversions.cpp modernize-nlohmann-json-explicit-conversions temp)