Export the remaining client-facing headers from json.hpp and check clients with IWYU

Besides json_fwd.hpp, include analyzers also told clients of
<nlohmann/json.hpp> to include detail/json_ref.hpp (brace
initialization), json_literals.hpp (_json, _json_pointer),
adl_serializer.hpp, detail/macro_scope.hpp (NLOHMANN_DEFINE_*) and
detail/abi_macros.hpp. Mark those includes as exported, too.

ci_single_binaries only checked each header on its own, so it could not
notice this. It now also runs IWYU and clang-tidy's misc-include-cleaner
on small client programs in tests/iwyu_consumer, which fail on develop.
With the exports, json_literals.hpp no longer gets the json_fwd.hpp
suggestion that kept it out of the IWYU gate, so it is gated again.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

cmake/ci.cmake

@@ -610,9 +610,8 @@ foreach(SRC_FILE ${SRC_FILES})
     add_executable(single_${RELATIVE_SRC_FILE} EXCLUDE_FROM_ALL ${PROJECT_BINARY_DIR}/src_single/${RELATIVE_SRC_FILE}.cpp)
     target_include_directories(single_${RELATIVE_SRC_FILE} PRIVATE ${PROJECT_SOURCE_DIR}/include)
     target_compile_features(single_${RELATIVE_SRC_FILE} PRIVATE cxx_std_11)
-    if(RELATIVE_SRC_FILE STREQUAL "json" OR RELATIVE_SRC_FILE STREQUAL "json_literals")
-        # see below: report the diagnostics of json.hpp and json_literals.hpp without --error, so they
-        # do not fail the build
+    if(RELATIVE_SRC_FILE STREQUAL "json")
+        # see below: report the diagnostics of json.hpp without --error, so they do not fail the build
         set_property(TARGET single_${RELATIVE_SRC_FILE} PROPERTY CXX_INCLUDE_WHAT_YOU_USE ${IWYU_TOOL} -Xiwyu --max_line_length=300)
     else()
         set_property(TARGET single_${RELATIVE_SRC_FILE} PROPERTY CXX_INCLUDE_WHAT_YOU_USE "${iwyu_path_and_options}")
@@ -626,18 +625,31 @@ foreach(SRC_FILE ${SRC_FILES})
     # reporting its diagnostics (informational, via CXX_INCLUDE_WHAT_YOU_USE above) but exclude it
     # from the hard gate below so a fresh IWYU/compiler combination does not fail this target on a
     # nondeterministic suggestion for a header that already re-exports everything on purpose.
-    # json_literals.hpp and json.hpp include each other on purpose (json.hpp includes it at its end
-    # unless JSON_NO_AUTOMATIC_UDLS is defined), and IWYU, not following the cycle, suggests replacing
-    # json.hpp with json_fwd.hpp although the literals need the complete basic_json; exclude it, too.
-    if(NOT RELATIVE_SRC_FILE STREQUAL "json" AND NOT RELATIVE_SRC_FILE STREQUAL "json_literals")
+    if(NOT RELATIVE_SRC_FILE STREQUAL "json")
         list(APPEND single_binaries_tus src_single/${RELATIVE_SRC_FILE}.cpp)
     endif()
 endforeach()
 
+# The checks above look at each header on its own. Client code that includes only <nlohmann/json.hpp>
+# must not be told by include analyzers to include another nlohmann header for what it uses
+# (issue #5812): json.hpp marks those includes "IWYU pragma: export", and both IWYU and clang-tidy's
+# misc-include-cleaner (disabled in .clang-tidy for the library itself) check these clients.
+file(GLOB CONSUMER_FILES ${PROJECT_SOURCE_DIR}/tests/iwyu_consumer/*.cpp)
+foreach(CONSUMER_FILE ${CONSUMER_FILES})
+    get_filename_component(CONSUMER_NAME "${CONSUMER_FILE}" NAME_WE)
+    add_executable(iwyu_consumer_${CONSUMER_NAME} EXCLUDE_FROM_ALL ${CONSUMER_FILE})
+    target_include_directories(iwyu_consumer_${CONSUMER_NAME} PRIVATE ${PROJECT_SOURCE_DIR}/include)
+    target_compile_features(iwyu_consumer_${CONSUMER_NAME} PRIVATE cxx_std_11)
+    list(APPEND single_binaries iwyu_consumer_${CONSUMER_NAME})
+    list(APPEND single_binaries_tus ${CONSUMER_FILE})
+endforeach()
+
 if(IWYU_TOOL_PY)
     add_custom_target(ci_single_binaries
         DEPENDS ${single_binaries}
         COMMAND ${IWYU_TOOL_PY} -p ${PROJECT_BINARY_DIR} ${single_binaries_tus} -- ${iwyu_options}
+        COMMAND ${CLANG_TIDY_TOOL} -p ${PROJECT_BINARY_DIR} --checks=-*,misc-include-cleaner --warnings-as-errors=* ${CONSUMER_FILES}
+        VERBATIM
         COMMENT "Check if headers are self-contained"
     )
 else()

include/nlohmann/json.hpp

@@ -42,9 +42,14 @@
 // each of these, not only the forward declarations from json_fwd.hpp, so IWYU's suggestion to
 // drop them (nothing in this file otherwise names the type) would break every downstream
 // translation unit that relies on basic_json<>'s defaults actually being usable.
-#include <nlohmann/adl_serializer.hpp> // IWYU pragma: keep
+// export: client code names what these headers declare (nlohmann::json and ordered_json from
+// json_fwd.hpp, adl_serializer for specializations, json_ref behind brace initialization, the
+// NLOHMANN_DEFINE_* and NLOHMANN_JSON_NAMESPACE_* macros, and the literals at the end of this file), and include analyzers must
+// attribute it to this header, not tell clients to include the internal ones (issue #5812).
+// tests/iwyu_consumer checks this.
+#include <nlohmann/adl_serializer.hpp> // IWYU pragma: export
 #include <nlohmann/byte_container_with_subtype.hpp>
-#include <nlohmann/detail/abi_macros.hpp>
+#include <nlohmann/detail/abi_macros.hpp> // IWYU pragma: export
 #include <nlohmann/detail/conversions/from_json.hpp> // IWYU pragma: keep
 #include <nlohmann/detail/conversions/to_json.hpp> // IWYU pragma: keep
 #include <nlohmann/detail/exceptions.hpp>
@@ -61,8 +66,8 @@
 #include <nlohmann/detail/iterators/primitive_iterator.hpp>
 #include <nlohmann/detail/json_custom_base_class.hpp>
 #include <nlohmann/detail/json_pointer.hpp>
-#include <nlohmann/detail/json_ref.hpp>
-#include <nlohmann/detail/macro_scope.hpp>
+#include <nlohmann/detail/json_ref.hpp> // IWYU pragma: export
+#include <nlohmann/detail/macro_scope.hpp> // IWYU pragma: export
 #include <nlohmann/detail/meta/detected.hpp>
 #include <nlohmann/detail/string_concat.hpp>
 #include <nlohmann/detail/string_escape.hpp>
@@ -74,7 +79,7 @@
 #include <nlohmann/detail/output/serializer.hpp>
 #include <nlohmann/detail/recursion_depth_limit.hpp>
 #include <nlohmann/detail/value_t.hpp>
-#include <nlohmann/json_fwd.hpp>
+#include <nlohmann/json_fwd.hpp> // IWYU pragma: export
 #include <nlohmann/ordered_map.hpp> // IWYU pragma: keep
 #include <nlohmann/thirdparty/hedley/hedley.hpp>
 
@@ -7795,7 +7800,7 @@ struct formatter<nlohmann::NLOHMANN_BASIC_JSON_TPL, char> // NOLINT(cert-dcl58-c
 // where needed.
 #ifndef JSON_NO_AUTOMATIC_UDLS
     // NOLINTNEXTLINE(misc-header-include-cycle): json_literals.hpp includes this header
-    #include <nlohmann/json_literals.hpp>
+    #include <nlohmann/json_literals.hpp> // IWYU pragma: export
 #endif
 
 #endif  // INCLUDE_NLOHMANN_JSON_HPP_

single_include/nlohmann/json.hpp

@@ -42,6 +42,11 @@
 // each of these, not only the forward declarations from json_fwd.hpp, so IWYU's suggestion to
 // drop them (nothing in this file otherwise names the type) would break every downstream
 // translation unit that relies on basic_json<>'s defaults actually being usable.
+// export: client code names what these headers declare (nlohmann::json and ordered_json from
+// json_fwd.hpp, adl_serializer for specializations, json_ref behind brace initialization, the
+// NLOHMANN_DEFINE_* and NLOHMANN_JSON_NAMESPACE_* macros, and the literals at the end of this file), and include analyzers must
+// attribute it to this header, not tell clients to include the internal ones (issue #5812).
+// tests/iwyu_consumer checks this.
 // #include <nlohmann/adl_serializer.hpp>
 //     __ _____ _____ _____
 //  __|  |   __|     |   | |  JSON for Modern C++
@@ -7533,7 +7538,7 @@ struct adl_serializer
 };
 
 NLOHMANN_JSON_NAMESPACE_END
-// IWYU pragma: keep
+// IWYU pragma: export
 // #include <nlohmann/byte_container_with_subtype.hpp>
 //     __ _____ _____ _____
 //  __|  |   __|     |   | |  JSON for Modern C++
@@ -7641,7 +7646,7 @@ class byte_container_with_subtype : public BinaryType
 NLOHMANN_JSON_NAMESPACE_END
 
 // #include <nlohmann/detail/abi_macros.hpp>
-
+// IWYU pragma: export
 // #include <nlohmann/detail/conversions/from_json.hpp>
 // IWYU pragma: keep
 // #include <nlohmann/detail/conversions/to_json.hpp>
@@ -21410,9 +21415,9 @@ class json_ref
 
 }  // namespace detail
 NLOHMANN_JSON_NAMESPACE_END
-
+// IWYU pragma: export
 // #include <nlohmann/detail/macro_scope.hpp>
-
+// IWYU pragma: export
 // #include <nlohmann/detail/meta/detected.hpp>
 
 // #include <nlohmann/detail/string_concat.hpp>
@@ -27776,7 +27781,7 @@ NLOHMANN_JSON_NAMESPACE_END
 // #include <nlohmann/detail/value_t.hpp>
 
 // #include <nlohmann/json_fwd.hpp>
-
+// IWYU pragma: export
 // #include <nlohmann/ordered_map.hpp>
 //     __ _____ _____ _____
 //  __|  |   __|     |   | |  JSON for Modern C++
@@ -36209,7 +36214,7 @@ NLOHMANN_JSON_NAMESPACE_END
 #undef NLOHMANN_JSON_LITERAL_OPERATOR
 
 #endif  // INCLUDE_NLOHMANN_JSON_LITERALS_HPP_
-
+// IWYU pragma: export
 #endif
 
 #endif  // INCLUDE_NLOHMANN_JSON_HPP_

tests/iwyu_consumer/conversions.cpp

@@ -0,0 +1,62 @@
+//     __ _____ _____ _____
+//  __|  |   __|     |   | |  JSON for Modern C++ (supporting code)
+// |  |  |__   |  |  | | | |  version 3.12.0
+// |_____|_____|_____|_|___|  https://github.com/nlohmann/json
+//
+// SPDX-FileCopyrightText: 2013-2026 Niels Lohmann <https://nlohmann.me>
+// SPDX-License-Identifier: MIT
+
+// See values.cpp: the conversion macros and nlohmann::adl_serializer must be available through
+// <nlohmann/json.hpp> alone. NLOHMANN_JSON_SERIALIZE_ENUM (from the same header as
+// NLOHMANN_DEFINE_TYPE_INTRUSIVE) is left out: IWYU attributes the basic_json comparison in its
+// expansion to an unrelated standard header, the ambiguity described for json.hpp in cmake/ci.cmake.
+
+#include <string>
+
+#include <nlohmann/json.hpp>
+
+namespace ns
+{
+struct person
+{
+    std::string name;
+    int age;
+    NLOHMANN_DEFINE_TYPE_INTRUSIVE(person, name, age)
+};
+
+struct legacy
+{
+    int value;
+};
+} // namespace ns
+
+namespace nlohmann
+{
+template<>
+struct adl_serializer<ns::legacy>
+{
+    static void to_json(json& j, const ns::legacy& l)
+    {
+        j = l.value;
+    }
+
+    static void from_json(const json& j, ns::legacy& l)
+    {
+        l.value = j.get<int>();
+    }
+};
+} // namespace nlohmann
+
+int main()
+{
+    ns::person ada;
+    ada.name = "Ada";
+    ada.age = 36;
+    ns::legacy one;
+    one.value = 1;
+
+    const nlohmann::json j = ada;
+    const auto p = j.get<ns::person>();
+    const auto l = nlohmann::json(one).get<ns::legacy>();
+    return p.age - 36 + l.value - 1;
+}

tests/iwyu_consumer/literals.cpp

@@ -0,0 +1,19 @@
+//     __ _____ _____ _____
+//  __|  |   __|     |   | |  JSON for Modern C++ (supporting code)
+// |  |  |__   |  |  | | | |  version 3.12.0
+// |_____|_____|_____|_|___|  https://github.com/nlohmann/json
+//
+// SPDX-FileCopyrightText: 2013-2026 Niels Lohmann <https://nlohmann.me>
+// SPDX-License-Identifier: MIT
+
+// See values.cpp: the user-defined literals must be available through <nlohmann/json.hpp> alone.
+
+#include <nlohmann/json.hpp>
+
+using namespace nlohmann::literals; // NOLINT(google-build-using-namespace)
+
+int main()
+{
+    const auto j = R"({"a": [1, 2]})"_json;
+    return j.at("/a/1"_json_pointer).get<int>() - 2;
+}

tests/iwyu_consumer/values.cpp

@@ -0,0 +1,30 @@
+//     __ _____ _____ _____
+//  __|  |   __|     |   | |  JSON for Modern C++ (supporting code)
+// |  |  |__   |  |  | | | |  version 3.12.0
+// |_____|_____|_____|_|___|  https://github.com/nlohmann/json
+//
+// SPDX-FileCopyrightText: 2013-2026 Niels Lohmann <https://nlohmann.me>
+// SPDX-License-Identifier: MIT
+
+// Uses the library the way a client does, including only <nlohmann/json.hpp>. ci_single_binaries
+// runs include-what-you-use and clang-tidy's misc-include-cleaner on this file and fails if either
+// asks for another nlohmann header, which would mean json.hpp does not export it (issue #5812).
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include <nlohmann/json.hpp>
+
+int main()
+{
+    // brace initialization (nlohmann::json, detail::json_ref)
+    nlohmann::json j = {{"pi", 3.141}, {"list", {1, 0, 2}}};
+    const nlohmann::ordered_json o = {{"b", 1}, {"a", 2}};
+
+    j["parsed"] = nlohmann::json::parse(R"({"happy": true})");
+    j["binary"] = nlohmann::json::binary(std::vector<std::uint8_t> {0xCA, 0xFE}, 42);
+
+    const std::string s = j.dump() + o.dump();
+    return s.empty() ? 1 : 0;
+}