Cover react/renderer/debug with Stable API guards (#58183)

Summary:
Pull Request resolved: #58183

Classifies `react/renderer/debug:debug` as a public target under the three-tier C++ stable API visibility model, and adds the module umbrella `<React/RendererDebug.h>` as its public entry point. Consumers that opt into `RN_STRICT_API` now get an error if they include the module's headers directly and have to go through the umbrella instead; without that flag the guards are inert, so no existing build changes behaviour.

The pod's source glob is narrowed to the module's own directory so the umbrella is not also flattened into `react/renderer/debug`, and the matching `headers-config.js` exception splits the pod into module and umbrella subspecs so `<React/RendererDebug.h>` resolves in the SwiftPM prebuild.

Changelog: [Internal]

Reviewed By: cipolleschi

Differential Revision: D117850084

fbshipit-source-id: 7e07ee5e9351e77453159c4476b31094332544a9

Author: j-piasecki

packages/react-native/ReactAndroid/build.gradle.kts

@@ -151,6 +151,7 @@ val preparePrefab by
                       Pair("../ReactCommon/react/debug/React/", "React/"),
                       // react_renderer_debug
                       Pair("../ReactCommon/react/renderer/debug/", "react/renderer/debug/"),
+                      Pair("../ReactCommon/react/renderer/debug/React/", "React/"),
                       // react_renderer_graphics
                       Pair("../ReactCommon/react/renderer/graphics/", "react/renderer/graphics/"),
                       Pair("../ReactCommon/react/renderer/graphics/platform/android/", ""),

packages/react-native/ReactCommon/react/renderer/debug/CMakeLists.txt

@@ -12,7 +12,8 @@ file(GLOB react_renderer_debug_SRC CONFIGURE_DEPENDS *.cpp)
 add_library(react_renderer_debug OBJECT ${react_renderer_debug_SRC})
 
 target_include_directories(react_renderer_debug PUBLIC ${REACT_COMMON_DIR})
-target_link_libraries(react_renderer_debug folly_runtime react_debug)
+target_include_directories(react_renderer_debug INTERFACE ${REACT_COMMON_DIR}/react/renderer/debug)
+target_link_libraries(react_renderer_debug folly_runtime react_cxxstableapi react_debug)
 target_compile_reactnative_options(react_renderer_debug PRIVATE)
 target_compile_options(react_renderer_debug PRIVATE -Wpedantic)
 

packages/react-native/ReactCommon/react/renderer/debug/DebugStringConvertible.h

@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <climits>
 #include <memory>
 #include <optional>

packages/react-native/ReactCommon/react/renderer/debug/DebugStringConvertibleItem.h

@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <string>
 
 #include <react/renderer/debug/DebugStringConvertible.h>

packages/react-native/ReactCommon/react/renderer/debug/React-rendererdebug.podspec

@@ -31,9 +31,8 @@ Pod::Spec.new do |s|
   s.author                 = "Meta Platforms, Inc. and its affiliates"
   s.platforms              = min_supported_versions
   s.source                 = source
-  s.source_files           = podspec_sources("**/*.{cpp,h,mm}", "**/*.h")
+  s.source_files           = podspec_sources("*.{cpp,h,mm}", "*.h")
   s.header_dir             = "react/renderer/debug"
-  s.exclude_files          = "tests"
   s.pod_target_xcconfig    = {
     "CLANG_CXX_LANGUAGE_STANDARD" => rct_cxx_language_standard(),
     "HEADER_SEARCH_PATHS" => header_search_paths.join(' '),
@@ -46,5 +45,13 @@ Pod::Spec.new do |s|
   add_rn_third_party_dependencies(s)
   add_rncore_dependency(s)
 
+  s.dependency "React-cxxstableapi"
+
+  s.subspec "debugUmbrella" do |ss|
+    ss.source_files        = "React/*.h"
+    ss.header_dir          = ""
+    ss.header_mappings_dir = "."
+  end
+
   mark_as_react_native_build(s)
 end

packages/react-native/ReactCommon/react/renderer/debug/React/RendererDebug.h

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+// =============================================================================
+// Umbrella header for the `react/renderer/debug` module - public entry point.
+//
+//   #include <React/RendererDebug.h>
+//
+// Re-exports the module's public interface headers. React Native's own code
+// should keep using the fine-grained `<react/renderer/debug/...>` includes,
+// except in headers it exports to consumers: those are preprocessed in the
+// consumer's translation unit, where the fine-grained include hits this
+// module's <react/cxxstableapi/UmbrellaGuard.h>. `RN_ALLOW_FRAMEWORKS` does not
+// suppress that guard, so a "for frameworks" header must reach this module
+// through the umbrella.
+// =============================================================================
+
+// Marks that the following headers are pulled in through the umbrella, so their
+// shared guard (<react/cxxstableapi/UmbrellaGuard.h>) accepts them. The marker
+// is saved and restored rather than defined and undefined: the scope ends at
+// this block, so later *direct* includes in the same TU are still caught, and
+// it nests inside an enclosing umbrella rather than disarming it.
+#pragma push_macro("RN_UMBRELLA_CONTEXT")
+#undef RN_UMBRELLA_CONTEXT
+#define RN_UMBRELLA_CONTEXT 1
+
+#include <react/renderer/debug/DebugStringConvertible.h>
+#include <react/renderer/debug/DebugStringConvertibleItem.h>
+#include <react/renderer/debug/debugStringConvertibleUtils.h>
+#include <react/renderer/debug/flags.h>
+
+#undef RN_UMBRELLA_CONTEXT
+#pragma pop_macro("RN_UMBRELLA_CONTEXT")

packages/react-native/ReactCommon/react/renderer/debug/debugStringConvertibleUtils.h

@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <memory>
 #include <optional>
 #include <string>

packages/react-native/ReactCommon/react/renderer/debug/flags.h

@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <react/debug/flags.h>
 
 //

packages/react-native/scripts/ios-prebuild/headers-config.js

@@ -697,6 +697,23 @@ const PodspecExceptions /*: {[key: string]: PodSpecConfiguration} */ = {
       },
     ],
   },
+  'ReactCommon/react/renderer/debug/React-rendererdebug.podspec': {
+    name: 'React-rendererdebug',
+    headerPatterns: [],
+    headerDir: '',
+    subSpecs: [
+      {
+        name: 'debug',
+        headerPatterns: ['*.h'],
+        headerDir: 'react/renderer/debug',
+      },
+      {
+        name: 'debugUmbrella',
+        headerPatterns: ['React/*.h'],
+        headerDir: 'React',
+      },
+    ],
+  },
 };
 
 module.exports = {PodspecExceptions};