Add CocoaPods opt-in for RN_STRICT_API

Summary:
Let iOS apps that use CocoaPods enforce React Native's C++ stable API. Setting `RCT_STRICT_CXX_API=1` before `pod install` defines `RN_STRICT_API` in the app project and the Pods project, so the `react/cxxstableapi` guards apply to the app, third-party pods and app codegen. React Native's own pods are unaffected because they define `RN_BUILDING`.

Under the flag, a direct include of a public module header is an error that points to the module's umbrella (`<React/<Module>.h>`), a private header is an error, and a "for frameworks" header is a warning that `RN_ALLOW_FRAMEWORKS` silences.

The flag is off by default: libraries that still include React Native's internal headers would stop compiling. Turning it back off removes the define on the next `pod install`. This mirrors the existing `RCT_REMOVE_LEGACY_*` opt-ins and matches the scope of the Android opt-in.

Changelog:
[iOS][Added] - Add `RCT_STRICT_CXX_API` CocoaPods opt-in to enforce React Native's C++ stable API in app and library native code

Differential Revision: D124979668

Author: coado

packages/react-native/scripts/cocoapods/__tests__/utils-test.rb

@@ -39,6 +39,7 @@ def teardown
         ENV['USE_FRAMEWORKS'] = nil
         ENV['RCT_REMOVE_LEGACY_MODULE_INTEROP'] = nil
         ENV['RCT_REMOVE_LEGACY_COMPONENT_INTEROP'] = nil
+        ENV['RCT_STRICT_CXX_API'] = nil
         system_reset_commands
         $RN_PLATFORMS = nil
     end
@@ -613,6 +614,92 @@ def test_setLegacyInteropRemovalFlags_whenEnabledWithPrebuiltRNCore_warns
         assert(Pod::UI.collected_warns.first.include?("RCT_USE_PREBUILT_RNCORE=0"))
     end
 
+    # ==================================== #
+    # Test - Set strict C++ API flag       #
+    # ==================================== #
+
+    def strict_cxx_api_installer_mock(user_project_mock, pods_project_mock)
+        return InstallerMock.new(pods_project_mock, [AggregatedProjectMock.new(user_project_mock)])
+    end
+
+    def strict_cxx_api_pods_project_mock
+        return PodsProjectMock.new([], {"hermes-engine" => {}}, "test/path-pod.xcodeproj", [
+            BuildConfigurationMock.new("Debug"),
+            BuildConfigurationMock.new("Release"),
+        ])
+    end
+
+    def assert_strict_cxx_api_flag(project_mock, enabled)
+        project_mock.build_configurations.each do |config|
+            ["OTHER_CFLAGS", "OTHER_CPLUSPLUSFLAGS"].each do |key|
+                assert_equal(enabled, config.build_settings[key].include?("-DRN_STRICT_API"))
+            end
+        end
+    end
+
+    def test_setStrictCxxApiFlag_whenUnset_doesNotAddFlag
+        # Arrange
+        user_project_mock = prepare_empty_user_project_mock()
+        pods_project_mock = strict_cxx_api_pods_project_mock()
+        installer = strict_cxx_api_installer_mock(user_project_mock, pods_project_mock)
+
+        # Act
+        ReactNativePodsUtils.set_strict_cxx_api_flag(installer)
+
+        # Assert
+        assert_strict_cxx_api_flag(user_project_mock, false)
+        assert_strict_cxx_api_flag(pods_project_mock, false)
+    end
+
+    def test_setStrictCxxApiFlag_whenEnabled_addsFlagToUserAndPodsProjects
+        # Arrange
+        ENV['RCT_STRICT_CXX_API'] = '1'
+        user_project_mock = prepare_empty_user_project_mock()
+        pods_project_mock = strict_cxx_api_pods_project_mock()
+        installer = strict_cxx_api_installer_mock(user_project_mock, pods_project_mock)
+
+        # Act
+        ReactNativePodsUtils.set_strict_cxx_api_flag(installer)
+
+        # Assert
+        assert_strict_cxx_api_flag(user_project_mock, true)
+        assert_strict_cxx_api_flag(pods_project_mock, true)
+    end
+
+    def test_setStrictCxxApiFlag_whenCalledTwice_addsFlagOnce
+        # Arrange
+        ENV['RCT_STRICT_CXX_API'] = '1'
+        user_project_mock = prepare_empty_user_project_mock()
+        pods_project_mock = strict_cxx_api_pods_project_mock()
+        installer = strict_cxx_api_installer_mock(user_project_mock, pods_project_mock)
+
+        # Act
+        ReactNativePodsUtils.set_strict_cxx_api_flag(installer)
+        ReactNativePodsUtils.set_strict_cxx_api_flag(installer)
+
+        # Assert
+        user_project_mock.build_configurations.each do |config|
+            assert_equal(1, config.build_settings["OTHER_CPLUSPLUSFLAGS"].scan("-DRN_STRICT_API").length)
+        end
+    end
+
+    def test_setStrictCxxApiFlag_whenDisabled_removesPreviouslyAddedFlag
+        # Arrange
+        ENV['RCT_STRICT_CXX_API'] = '1'
+        user_project_mock = prepare_empty_user_project_mock()
+        pods_project_mock = strict_cxx_api_pods_project_mock()
+        installer = strict_cxx_api_installer_mock(user_project_mock, pods_project_mock)
+        ReactNativePodsUtils.set_strict_cxx_api_flag(installer)
+
+        # Act
+        ENV['RCT_STRICT_CXX_API'] = '0'
+        ReactNativePodsUtils.set_strict_cxx_api_flag(installer)
+
+        # Assert
+        assert_strict_cxx_api_flag(user_project_mock, false)
+        assert_strict_cxx_api_flag(pods_project_mock, false)
+    end
+
     # ==================================== #
     # Test - Set build setting             #
     # ==================================== #

packages/react-native/scripts/cocoapods/utils.rb

@@ -24,6 +24,9 @@ class ReactNativePodsUtils
         'RCT_REMOVE_LEGACY_COMPONENT_INTEROP',
     ]
 
+    # Opt-in enforcement of React Native's C++ stable API.
+    STRICT_CXX_API_FLAG = 'RCT_STRICT_CXX_API'
+
     # URI::File.build validates path components as ASCII, so escape the filesystem path first.
     def self.local_file_uri(path)
         URI::File.build(path: URI::DEFAULT_PARSER.escape(path)).to_s
@@ -598,6 +601,17 @@ def self.set_legacy_interop_removal_flags(installer, build_rncore_from_source:)
         end
     end
 
+    # RN_STRICT_API arms the react/cxxstableapi guards for every target that inherits the
+    # project settings: the app, third-party pods and app codegen. React Native's own pods
+    # define RN_BUILDING, which keeps the guards inert for them.
+    def self.set_strict_cxx_api_flag(installer)
+        if ENV[STRICT_CXX_API_FLAG] == '1'
+            self.add_compiler_flag_to_project(installer, "-DRN_STRICT_API")
+        else
+            self.remove_compiler_flag_from_project(installer, "-DRN_STRICT_API")
+        end
+    end
+
     def self.add_compiler_flag_to_pods(installer, flag, configuration: nil)
         installer.target_installation_results.pod_target_installation_results.each do |pod_name, target_installation_result|
             target_installation_result.native_target.build_configurations.each do |config|

packages/react-native/scripts/react_native_pods.rb

@@ -122,6 +122,9 @@ def use_react_native! (
   # layers are still supported. Both will default to 1 in a future React Native release.
   ENV['RCT_REMOVE_LEGACY_MODULE_INTEROP'] = ENV['RCT_REMOVE_LEGACY_MODULE_INTEROP'] == '1' ? '1' : '0'
   ENV['RCT_REMOVE_LEGACY_COMPONENT_INTEROP'] = ENV['RCT_REMOVE_LEGACY_COMPONENT_INTEROP'] == '1' ? '1' : '0'
+  # Enforcing the C++ stable API is opt-in: third-party libraries that still include
+  # React Native's internal headers would stop compiling.
+  ENV['RCT_STRICT_CXX_API'] = ENV['RCT_STRICT_CXX_API'] == '1' ? '1' : '0'
 
   ReactNativePodsUtils.check_minimum_required_xcode()
 
@@ -631,6 +634,8 @@ def react_native_post_install(
     build_rncore_from_source: ReactNativeCoreUtils.build_rncore_from_source()
   )
 
+  ReactNativePodsUtils.set_strict_cxx_api_flag(installer)
+
   ReactNativePodsUtils.set_ccache_compiler_and_linker_build_settings(installer, react_native_path, ccache_enabled)
   ReactNativePodsUtils.updateOSDeploymentTarget(installer)
   ReactNativePodsUtils.set_dynamic_frameworks_flags(installer)