Export client-facing headers from json.hpp for IWYU / include-cleaner, and check clients in CI (#5813)

* Mark json_fwd.hpp as exported by json.hpp for IWYU / include-cleaner

json_fwd.hpp is the only header declaring the nlohmann::json alias, so
include-what-you-use and clang-tidy's misc-include-cleaner attributed
the name to it and told users of <nlohmann/json.hpp> to include
json_fwd.hpp as well (or instead, which breaks compilation).

Fixes #5812

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

* 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>

---------

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

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;
+}