Let the C++ API snapshot config select its visibility (#58838)

Summary:

Adds a `visibility` option to the C++ API snapshot `config.yml`, listing which C++ stable API tiers (`public`, `frameworks`, `private`) a view includes. It can be set per view or at the top level, where it applies to views that do not set their own. When omitted it defaults to `public`, so existing snapshots are unchanged.

Headers in tiers outside the selection are skipped unless a header in an included tier reaches them. Unclassified headers are still kept.

Changelog: [Internal]

Differential Revision: D123001791

Author: j-piasecki

scripts/cxx-api/README.md

@@ -4,7 +4,7 @@ Python build pipeline for React Native's C++ (and Objective-C) API snapshots.
 
 ## Overview
 
-`scripts/cxx-api` generates human-readable snapshots of React Native's public C++ API surface. It uses [Doxygen](https://www.doxygen.nl/) to parse C/C++/Objective-C headers and a custom Python parser to produce a simplified, sorted representation of every public symbol. Symbols declared in headers that the C++ stable API classifies as private or "for frameworks" are left out (see [Tier filtering](#tier-filtering)).
+`scripts/cxx-api` generates human-readable snapshots of React Native's public C++ API surface. It uses [Doxygen](https://www.doxygen.nl/) to parse C/C++/Objective-C headers and a custom Python parser to produce a simplified, sorted representation of every public symbol. Symbols declared in headers that the C++ stable API classifies as private or "for frameworks" are left out by default (see [Tier filtering](#tier-filtering)).
 
 The pipeline produces one `.api` snapshot file per configured **API view × variant** combination:
 
@@ -76,7 +76,7 @@ The Python parser (`parser/`) reads the Doxygen XML output and builds a scope tr
 
 ## Tier filtering
 
-A private or for-frameworks header is skipped unless a public header reaches it, directly or through other includes: anything a public header includes is public in practice, whatever its own guard says. Unclassified headers are never skipped.
+Each view includes the tiers listed in its `visibility` config (`public`, `frameworks`, `private`), only `public` by default. A header in any other tier is skipped unless a header in an included tier reaches it, directly or through other includes: anything a public header includes is public in practice, whatever its own guard says. Unclassified headers are never skipped.
 
 A boundary break is a public header that reaches a for-frameworks or private header, or a for-frameworks header that reaches a private one. `--log-boundary-breaks` reports them at the edge where visibility drops.
 
@@ -102,8 +102,9 @@ All API views and their variants are defined in `config.yml`. Each view specifie
 | `codegen` | Optional codegen platform (`android`, `ios`) to generate TurboModule/Component headers before scanning |
 | `exclude_symbols` | Regex patterns for symbols to skip |
 | `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.
+`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.
 
 ## Snapshot format
 

scripts/cxx-api/parser/__main__.py

@@ -163,67 +163,87 @@ def _display_path(path: str, react_native_dir: str) -> str:
 def classify_views(
     configs: list[ApiViewSnapshotConfig],
     codegen_dirs: dict[str, str],
-) -> list[tuple[list[str], HeaderGraph]]:
+) -> list[tuple[list[ApiViewSnapshotConfig], HeaderGraph]]:
     # Variants of a view differ only in preprocessor definitions, which the
     # textual include scan ignores, so classify each distinct input set once.
-    groups: dict[tuple, list[str]] = {}
+    groups: dict[tuple, list[ApiViewSnapshotConfig]] = {}
     for config in configs:
         codegen_dir = codegen_dirs.get(config.codegen_platform)
         key = (
             tuple(config.inputs + ([codegen_dir] if codegen_dir else [])),
             tuple(config.exclude_patterns),
         )
-        groups.setdefault(key, []).append(config.snapshot_name)
+        groups.setdefault(key, []).append(config)
 
     return [
         (
-            view_names,
+            view_configs,
             classify_headers(
                 list(inputs), _TEMPLATE_EXCLUDE_PATTERNS + list(exclude_patterns)
             ),
         )
-        for (inputs, exclude_patterns), view_names in groups.items()
+        for (inputs, exclude_patterns), view_configs in groups.items()
     ]
 
 
 def get_skipped_files_by_view(
-    view_graphs: list[tuple[list[str], HeaderGraph]],
+    view_graphs: list[tuple[list[ApiViewSnapshotConfig], HeaderGraph]],
     react_native_dir: str,
     verbose: bool,
 ) -> dict[str, set[str]]:
     skipped_by_view: dict[str, set[str]] = {}
-    for view_names, graph in view_graphs:
-        skipped = skipped_headers(graph)
-        if verbose:
-            kept = sorted(
-                path
-                for path, tier in graph.tiers.items()
-                if tier in (Tier.PRIVATE, Tier.FRAMEWORKS) and path not in skipped
-            )
-            print(
-                f"[{', '.join(view_names)}] {len(kept)} private or frameworks "
-                "header(s) kept because a public header reaches them"
+    for view_configs, graph in view_graphs:
+        names_by_visibility: dict[frozenset[Tier], list[str]] = {}
+        for config in view_configs:
+            names_by_visibility.setdefault(config.visibility, []).append(
+                config.snapshot_name
             )
-            for path in kept:
-                print(
-                    f"  {graph.tiers[path].name.lower()} "
-                    f"{_display_path(path, react_native_dir)}"
+
+        for visibility, view_names in names_by_visibility.items():
+            skipped = skipped_headers(graph, visibility)
+            if verbose:
+                _log_kept_headers(
+                    view_names, graph, visibility, skipped, react_native_dir
                 )
-        for view_name in view_names:
-            skipped_by_view[view_name] = skipped
+            for view_name in view_names:
+                skipped_by_view[view_name] = skipped
     return skipped_by_view
 
 
+def _log_kept_headers(
+    view_names: list[str],
+    graph: HeaderGraph,
+    included_tiers: frozenset[Tier],
+    skipped: set[str],
+    react_native_dir: str,
+) -> None:
+    kept = sorted(
+        path
+        for path, tier in graph.tiers.items()
+        if tier is not None and tier not in included_tiers and path not in skipped
+    )
+    included = ", ".join(tier.name.lower() for tier in sorted(included_tiers))
+    print(
+        f"[{', '.join(view_names)}] {len(kept)} header(s) outside the included "
+        f"tiers ({included}) kept because an included header reaches them"
+    )
+    for path in kept:
+        print(
+            f"  {graph.tiers[path].name.lower()} "
+            f"{_display_path(path, react_native_dir)}"
+        )
+
+
 def log_boundary_breaks(
-    view_graphs: list[tuple[list[str], HeaderGraph]],
+    view_graphs: list[tuple[list[ApiViewSnapshotConfig], HeaderGraph]],
     react_native_dir: str,
     enabled: bool,
 ) -> None:
     if not enabled:
         return
 
-    for view_names, graph in view_graphs:
-        label = ", ".join(view_names)
+    for view_configs, graph in view_graphs:
+        label = ", ".join(config.snapshot_name for config in view_configs)
         breaks = find_boundary_breaks(graph)
         print(f"[{label}] {len(breaks)} tier boundary break(s)")
         for boundary_break in breaks:

scripts/cxx-api/parser/config.py

@@ -15,6 +15,8 @@
 
 import yaml
 
+from .tiers import DEFAULT_TIERS, parse_tier, Tier
+
 
 @dataclass
 class ApiViewVariant:
@@ -39,6 +41,15 @@ class ApiViewSnapshotConfig:
     codegen_platform: str | None = None
     input_filter: bool = False
     exclude_symbols: list[str] = field(default_factory=list)
+    visibility: frozenset[Tier] = DEFAULT_TIERS
+
+
+def _parse_visibility(
+    names: list[str] | None, default: frozenset[Tier]
+) -> frozenset[Tier]:
+    if names is None:
+        return default
+    return frozenset(parse_tier(name) for name in names)
 
 
 def parse_config(
@@ -51,6 +62,8 @@ def parse_config(
     The config must contain:
       - An optional top-level ``exclude_patterns`` list that is prepended to
         every platform's own ``exclude_patterns``.
+      - An optional top-level ``visibility`` list of C++ stable API tiers,
+        used by platforms that do not set their own. Defaults to ``[public]``.
       - A ``platforms`` mapping whose values are per-platform view configs.
 
     Args:
@@ -62,6 +75,7 @@ def parse_config(
     """
     global_exclude_patterns: list[str] = raw_config.get("exclude_patterns") or []
     global_exclude_symbols: list[str] = raw_config.get("exclude_symbols") or []
+    global_visibility = _parse_visibility(raw_config.get("visibility"), DEFAULT_TIERS)
     platforms: dict = raw_config.get("platforms") or {}
 
     snapshot_configs = []
@@ -95,6 +109,7 @@ def parse_config(
                 merged_symbols.append(symbol)
                 seen_symbols.add(symbol)
         exclude_symbols = merged_symbols
+        visibility = _parse_visibility(view_config.get("visibility"), global_visibility)
 
         raw_variants = view_config.get("variants") or {}
         variants = [
@@ -115,6 +130,7 @@ def parse_config(
                     codegen_platform=codegen_platform,
                     input_filter=input_filter,
                     exclude_symbols=exclude_symbols,
+                    visibility=visibility,
                 )
             )
         else:
@@ -130,6 +146,7 @@ def parse_config(
                         codegen_platform=codegen_platform,
                         input_filter=input_filter,
                         exclude_symbols=exclude_symbols,
+                        visibility=visibility,
                     )
                 )
 

scripts/cxx-api/parser/tiers.py

@@ -26,6 +26,8 @@ class Tier(enum.IntEnum):
     PUBLIC = 3
 
 
+DEFAULT_TIERS: frozenset[Tier] = frozenset({Tier.PUBLIC})
+
 _GUARD_TIERS = {
     "Private": Tier.PRIVATE,
     "Frameworks": Tier.FRAMEWORKS,
@@ -178,12 +180,23 @@ def find_boundary_breaks(graph: HeaderGraph) -> list[BoundaryBreak]:
     return breaks
 
 
-def skipped_headers(graph: HeaderGraph) -> set[str]:
+def parse_tier(name: str) -> Tier:
+    try:
+        return Tier[name.upper()]
+    except KeyError:
+        valid = ", ".join(tier.name.lower() for tier in Tier)
+        raise ValueError(f"Unknown tier '{name}', expected one of: {valid}") from None
+
+
+def skipped_headers(
+    graph: HeaderGraph, included_tiers: frozenset[Tier] = DEFAULT_TIERS
+) -> set[str]:
     """
-    Private and frameworks headers that no public header reaches. A header
-    reachable from a public one is public in practice, whatever its guard says.
+    Classified headers outside `included_tiers` that no header in an included
+    tier reaches. A header reachable from an included one is effectively part
+    of that tier, whatever its guard says.
     """
-    reachable = {path for path, tier in graph.tiers.items() if tier == Tier.PUBLIC}
+    reachable = {path for path, tier in graph.tiers.items() if tier in included_tiers}
     queue = deque(reachable)
     while queue:
         node = queue.popleft()
@@ -195,7 +208,7 @@ def skipped_headers(graph: HeaderGraph) -> set[str]:
     return {
         path
         for path, tier in graph.tiers.items()
-        if tier in (Tier.PRIVATE, Tier.FRAMEWORKS) and path not in reachable
+        if tier is not None and tier not in included_tiers and path not in reachable
     }
 
 

scripts/cxx-api/tests/test_config.py

@@ -8,6 +8,7 @@
 import unittest
 
 from ..parser.config import parse_config
+from ..parser.tiers import Tier
 
 
 class TestParseConfig(unittest.TestCase):
@@ -625,6 +626,54 @@ def test_per_platform_exclude_symbols_propagated_to_variants(self):
         for r in result:
             self.assertEqual(r.exclude_symbols, ["Fantom", "Android"])
 
+    # =========================================================================
+    # Visibility
+    # =========================================================================
+
+    def test_visibility_defaults_to_public(self):
+        """Missing visibility defaults to public only"""
+        result = parse_config({"platforms": {"TestView": {}}}, "/base/dir")
+
+        self.assertEqual(result[0].visibility, frozenset({Tier.PUBLIC}))
+
+    def test_per_platform_visibility_overrides_global(self):
+        """Per-platform visibility replaces the global one"""
+        config = {
+            "visibility": ["public", "frameworks"],
+            "platforms": {
+                "ViewA": {"visibility": ["private"]},
+                "ViewB": {},
+            },
+        }
+        result = parse_config(config, "/base/dir")
+
+        view_a = next(r for r in result if r.snapshot_name == "ViewA")
+        self.assertEqual(view_a.visibility, frozenset({Tier.PRIVATE}))
+
+        view_b = next(r for r in result if r.snapshot_name == "ViewB")
+        self.assertEqual(view_b.visibility, frozenset({Tier.PUBLIC, Tier.FRAMEWORKS}))
+
+    def test_visibility_propagated_to_variants(self):
+        """Visibility applies to every variant of a view"""
+        config = {
+            "platforms": {
+                "TestView": {
+                    "visibility": ["public", "private"],
+                    "variants": {"debug": {}, "release": {}},
+                }
+            }
+        }
+        result = parse_config(config, "/base/dir")
+
+        for r in result:
+            self.assertEqual(r.visibility, frozenset({Tier.PUBLIC, Tier.PRIVATE}))
+
+    def test_unknown_visibility_rejected(self):
+        """An unknown tier name in visibility raises"""
+        config = {"platforms": {"TestView": {"visibility": ["internal"]}}}
+        with self.assertRaises(ValueError):
+            parse_config(config, "/base/dir")
+
     # =========================================================================
     # Variant naming
     # =========================================================================

scripts/cxx-api/tests/test_tiers.py

@@ -220,8 +220,11 @@ def test_build_header_graph_ignores_self_include(self):
     # Skipped headers
     # =========================================================================
 
-    def skipped(self):
-        return {os.path.relpath(p, self.root) for p in skipped_headers(self.graph())}
+    def skipped(self, *included_tiers):
+        args = (frozenset(included_tiers),) if included_tiers else ()
+        return {
+            os.path.relpath(p, self.root) for p in skipped_headers(self.graph(), *args)
+        }
 
     def test_skips_unreached_private_and_frameworks_headers(self):
         self.write("Public.h", PUBLIC)
@@ -243,3 +246,21 @@ def test_keeps_headers_reached_from_public(self):
     def test_never_skips_unclassified_headers(self):
         self.write("Unguarded.h")
         self.assertEqual(self.skipped(), set())
+
+    def test_keeps_included_tiers(self):
+        self.write("Public.h", PUBLIC)
+        self.write("Frameworks.h", FRAMEWORKS)
+        self.write("Private.h", PRIVATE)
+
+        self.assertEqual(self.skipped(Tier.PUBLIC, Tier.FRAMEWORKS), {"Private.h"})
+        self.assertEqual(
+            self.skipped(Tier.PUBLIC, Tier.FRAMEWORKS, Tier.PRIVATE), set()
+        )
+
+    def test_keeps_headers_reached_from_included_tiers(self):
+        self.write("Public.h", PUBLIC)
+        self.write("Frameworks.h", FRAMEWORKS + '#include "Private.h"\n')
+        self.write("Private.h", PRIVATE)
+        self.write("Other.h", PRIVATE)
+
+        self.assertEqual(self.skipped(Tier.PUBLIC, Tier.FRAMEWORKS), {"Other.h"})