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

Add a clang-tidy plugin containing one check to replace implicit
conversions (as enabled by default with JSON_USE_IMPLICIT_CONVERSIONS)
with explicit ones. This will make it easier for library users to switch
away from using implicit conversions which should make it possible for
the library to start disallowing them sooner.

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.

Signed-off-by: Mike Crowe <[email protected]>

Author: mikecrowe

.reuse/dep5

@@ -34,3 +34,7 @@ License: BSD-3-Clause
 Files: tools/gdb_pretty_printer/*
 Copyright: 2020 Hannes Domani <https://github.com/ssbssa>
 License: MIT
+
+Files: tests/clang_tidy_plugin/check_clang_tidy.py
+Copyright: 2003-2019 University of Illinois at Urbana-Champaign.
+License: Apache-2.0 WITH LLVM-exception

CMakeLists.txt

@@ -4,7 +4,7 @@ cmake_minimum_required(VERSION 3.5...4.0)
 ## PROJECT
 ## name and version
 ##
-project(nlohmann_json VERSION 3.12.0 LANGUAGES CXX)
+project(nlohmann_json VERSION 3.12.0 LANGUAGES C CXX)
 
 ##
 ## MAIN_PROJECT CHECK
@@ -60,6 +60,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)
@@ -170,6 +171,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

LICENSES/LLVM-exception.txt

@@ -0,0 +1,15 @@
+---- LLVM Exceptions to the Apache 2.0 License ----
+
+   As an exception, if, as a result of your compiling your source code, portions
+   of this Software are embedded into an Object form of such source code, you
+   may redistribute such embedded portions in such Object form without complying
+   with the conditions of Sections 4(a), 4(b) and 4(d) of the License.
+
+   In addition, if you combine or link compiled forms of this Software with
+   software that is licensed under the GPLv2 ("Combined Software") and if a
+   court of competent jurisdiction determines that the patent provision (Section
+   3), the indemnity provision (Section 9) or other Section of the License
+   conflicts with the conditions of the GPLv2, you may retroactively and
+   prospectively choose to deem waived or otherwise exclude such Section(s) of
+   the License, but only in their entirety and only with respect to the Combined
+   Software.

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,78 @@
+// 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 {
+    void replaceAll(std::string &Str, const std::string &From, const std::string &To) {
+        assert(!From.empty());
+
+        std::string::size_type StartPos = 0;
+        while ((StartPos = Str.find(From, StartPos)) != std::string::npos) {
+            Str.replace(StartPos, From.length(), To);
+            StartPos += To.length();
+        }
+    }
+}
+
+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());
+  replaceAll(DestinationTypeStr, "std::basic_string<char>", "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

@@ -181,6 +181,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)