Add Frameworks C++ API snapshots (#58836)

Summary:
Pull Request resolved: #58836

Adds a `frameworks` variant to the `ReactCommon`, `ReactAndroid` and `ReactApple` C++ API views. API offered to frameworks gets its own snapshots: `ReactCommonFrameworksCxx.api`, `ReactAndroidFrameworksCxx.api` and `ReactAppleFrameworksCxx.api`. The variant uses each view's base definitions.

To support this, a variant can now set `visibility`, overriding its view's.

Changelog: [Internal]

Reviewed By: coado

Differential Revision: D123001823

Author: j-piasecki

scripts/cxx-api/README.md

@@ -16,8 +16,11 @@ The pipeline produces one `.api` snapshot file per configured **API view × vari
 | `ReactAndroidReleaseCxx.api` | Android-specific C++ API (release) |
 | `ReactAppleDebugCxx.api` | Apple-specific C++/Obj-C API (debug) |
 | `ReactAppleReleaseCxx.api` | Apple-specific C++/Obj-C API (release) |
+| `ReactCommonFrameworksCxx.api` | Platform-independent C++ API, including for-frameworks symbols |
+| `ReactAndroidFrameworksCxx.api` | Android-specific C++ API, including for-frameworks symbols |
+| `ReactAppleFrameworksCxx.api` | Apple-specific C++/Obj-C API, including for-frameworks symbols |
 
-For each view, debug and release variants are generated with different preprocessor definitions (e.g. `REACT_NATIVE_DEBUG` vs `NDEBUG`), since `#ifdef` guards in the source headers can produce a different public API surface per variant.
+For each view, debug and release variants are generated with different preprocessor definitions (e.g. `REACT_NATIVE_DEBUG` vs `NDEBUG`), since `#ifdef` guards in the source headers can produce a different public API surface per variant. The frameworks variant uses the view's base definitions and also includes symbols from "for frameworks" headers.
 
 Snapshot files are committed to the repo under `scripts/cxx-api/api-snapshots/`.
 
@@ -104,7 +107,7 @@ All API views and their variants are defined in `config.yml`. Each view specifie
 | `input_filter` | Whether to run Doxygen through the input filters in `parser/input_filters/` |
 | `visibility` | C++ stable API tiers to include (`public`, `frameworks`, `private`); defaults to `[public]`. See [Tier filtering](#tier-filtering) |
 
-`exclude_patterns` and `exclude_symbols` can also be set at the top level, in which case they apply to every view. A top-level `visibility` applies to every view that does not set its own.
+`exclude_patterns` and `exclude_symbols` can also be set at the top level, in which case they apply to every view. A top-level `visibility` applies to every view that does not set its own, and a variant can set `visibility` to override its view's.
 
 ## Snapshot format
 

scripts/cxx-api/api-snapshots/ReactAndroidFrameworksCxx.api

@@ -45,6 +45,10 @@ platforms:
       newarch:
         definitions:
           RCT_REMOVE_LEGACY_ARCH: 1
+      frameworks:
+        visibility:
+          - public
+          - frameworks
   ReactAndroid:
     codegen:
       platform: android
@@ -78,6 +82,10 @@ platforms:
       newarch:
         definitions:
           RCT_REMOVE_LEGACY_ARCH: 1
+      frameworks:
+        visibility:
+          - public
+          - frameworks
   # ReactIOS?
   ReactApple:
     codegen:
@@ -118,3 +126,7 @@ platforms:
       newarch:
         definitions:
           RCT_REMOVE_LEGACY_ARCH: 1
+      frameworks:
+        visibility:
+          - public
+          - frameworks

scripts/cxx-api/api-snapshots/ReactAppleFrameworksCxx.api

@@ -24,6 +24,7 @@ class ApiViewVariant:
 
     name: str
     definitions: dict[str, str | int] = field(default_factory=dict)
+    visibility: frozenset[Tier] = DEFAULT_TIERS
 
 
 @dataclass
@@ -116,6 +117,9 @@ def parse_config(
             ApiViewVariant(
                 name=variant_name,
                 definitions=variant_config.get("definitions") or {},
+                visibility=_parse_visibility(
+                    variant_config.get("visibility"), visibility
+                ),
             )
             for variant_name, variant_config in raw_variants.items()
         ]
@@ -146,7 +150,7 @@ def parse_config(
                         codegen_platform=codegen_platform,
                         input_filter=input_filter,
                         exclude_symbols=exclude_symbols,
-                        visibility=visibility,
+                        visibility=variant.visibility,
                     )
                 )
 

scripts/cxx-api/api-snapshots/ReactCommonFrameworksCxx.api

@@ -668,6 +668,28 @@ def test_visibility_propagated_to_variants(self):
         for r in result:
             self.assertEqual(r.visibility, frozenset({Tier.PUBLIC, Tier.PRIVATE}))
 
+    def test_variant_visibility_overrides_view(self):
+        """A variant's visibility replaces the view's for that variant only"""
+        config = {
+            "platforms": {
+                "TestView": {
+                    "variants": {
+                        "debug": {},
+                        "frameworks": {"visibility": ["public", "frameworks"]},
+                    },
+                }
+            }
+        }
+        result = parse_config(config, "/base/dir")
+
+        debug = next(r for r in result if r.snapshot_name == "TestViewDebug")
+        self.assertEqual(debug.visibility, frozenset({Tier.PUBLIC}))
+
+        frameworks = next(r for r in result if r.snapshot_name == "TestViewFrameworks")
+        self.assertEqual(
+            frameworks.visibility, frozenset({Tier.PUBLIC, Tier.FRAMEWORKS})
+        )
+
     def test_unknown_visibility_rejected(self):
         """An unknown tier name in visibility raises"""
         config = {"platforms": {"TestView": {"visibility": ["internal"]}}}