Add exclude_symbols to the cxx-api parser config (#56240)

Summary:
Pull Request resolved: #56240

There are cases in which we want to strip particular symbols from the snapshot. This diff adds `exclude_symbols` to the parser config to enable definitions of symbol patterns that should be excluded from the snapshot.

Changelog:
[Internal]

Reviewed By: cipolleschi

Differential Revision: D98295409

Author: coado

scripts/cxx-api/config.yml

@@ -4,6 +4,8 @@ exclude_patterns:
   - "*/test/*"
   - "*/stubs/*"
 
+exclude_symbols:
+
 platforms:
   ReactCommon:
     codegen:

scripts/cxx-api/parser/__main__.py

@@ -89,6 +89,7 @@ def build_snapshot_for_view(
     verbose: bool = True,
     input_filter: str = None,
     work_dir: str | None = None,
+    exclude_symbols: list[str] | None = None,
 ) -> str:
     if verbose:
         print(f"[{api_view}] Generating API view")
@@ -127,7 +128,9 @@ def build_snapshot_for_view(
     if verbose:
         print(f"[{api_view}] Building snapshot")
 
-    snapshot = build_snapshot(os.path.join(work_dir, "xml"))
+    snapshot = build_snapshot(
+        os.path.join(work_dir, "xml"), exclude_symbols=exclude_symbols
+    )
     snapshot_string = snapshot.to_string()
 
     output_file = os.path.join(output_dir, f"{api_view}Cxx.api")
@@ -175,6 +178,7 @@ def build_snapshots(
                         verbose=verbose,
                         input_filter=input_filter if config.input_filter else None,
                         work_dir=work_dir,
+                        exclude_symbols=config.exclude_symbols,
                     )
                     futures[future] = config.snapshot_name
 

scripts/cxx-api/parser/config.py

@@ -38,6 +38,7 @@ class ApiViewSnapshotConfig:
     definitions: dict[str, str | int]
     codegen_platform: str | None = None
     input_filter: bool = False
+    exclude_symbols: list[str] = field(default_factory=list)
 
 
 def parse_config(
@@ -60,6 +61,7 @@ def parse_config(
         Flattened list of ApiViewSnapshotConfig objects for all views and variants
     """
     global_exclude_patterns: list[str] = raw_config.get("exclude_patterns") or []
+    global_exclude_symbols: list[str] = raw_config.get("exclude_symbols") or []
     platforms: dict = raw_config.get("platforms") or {}
 
     snapshot_configs = []
@@ -103,6 +105,7 @@ def parse_config(
                     definitions=base_definitions,
                     codegen_platform=codegen_platform,
                     input_filter=input_filter,
+                    exclude_symbols=global_exclude_symbols,
                 )
             )
         else:
@@ -117,6 +120,7 @@ def parse_config(
                         definitions=merged_definitions,
                         codegen_platform=codegen_platform,
                         input_filter=input_filter,
+                        exclude_symbols=global_exclude_symbols,
                     )
                 )
 

scripts/cxx-api/parser/main.py

@@ -28,16 +28,32 @@
 from .utils import has_scope_resolution_outside_angles, parse_qualified_path
 
 
-def _process_namespace_sections(snapshot, namespace_scope, compound_object):
+def _should_exclude_symbol(name: str, exclude_symbols: list[str]) -> bool:
+    """
+    Check if a compound name should be excluded based on symbol patterns.
+
+    Each pattern in exclude_symbols is treated as a substring match against
+    the compound's qualified name.
+    """
+    return any(pattern in name for pattern in exclude_symbols)
+
+
+def _process_namespace_sections(
+    snapshot, namespace_scope, compound_object, exclude_symbols: list[str]
+):
     """
     Process all section definitions inside a namespace compound.
     """
+    compound_name = compound_object.compoundname
     for section_def in compound_object.sectiondef:
         if section_def.kind == "var":
             for variable_def in section_def.memberdef:
                 # Skip out-of-class definitions (e.g. "Strct<T>::VALUE")
                 if has_scope_resolution_outside_angles(variable_def.get_name()):
                     continue
+                qualified_name = f"{compound_name}::{variable_def.get_name()}"
+                if _should_exclude_symbol(qualified_name, exclude_symbols):
+                    continue
                 is_static = variable_def.static == "yes"
                 namespace_scope.add_member(
                     get_variable_member(variable_def, "public", is_static)
@@ -47,6 +63,9 @@ def _process_namespace_sections(snapshot, namespace_scope, compound_object):
                 # Skip out-of-class definitions (e.g. "Strct<T>::convert")
                 if has_scope_resolution_outside_angles(function_def.get_name()):
                     continue
+                qualified_name = f"{compound_name}::{function_def.get_name()}"
+                if _should_exclude_symbol(qualified_name, exclude_symbols):
+                    continue
                 function_static = function_def.static == "yes"
 
                 if not function_static:
@@ -55,20 +74,29 @@ def _process_namespace_sections(snapshot, namespace_scope, compound_object):
                     )
         elif section_def.kind == "typedef":
             for typedef_def in section_def.memberdef:
+                qualified_name = f"{compound_name}::{typedef_def.get_name()}"
+                if _should_exclude_symbol(qualified_name, exclude_symbols):
+                    continue
                 namespace_scope.add_member(get_typedef_member(typedef_def, "public"))
         elif section_def.kind == "enum":
             for enum_def in section_def.memberdef:
+                qualified_name = f"{compound_name}::{enum_def.get_name()}"
+                if _should_exclude_symbol(qualified_name, exclude_symbols):
+                    continue
                 create_enum_scope(snapshot, enum_def)
         else:
             print(
                 f"Unknown section kind: {section_def.kind} in {compound_object.location.file}"
             )
 
 
-def _handle_namespace_compound(snapshot, compound_object):
+def _handle_namespace_compound(snapshot, compound_object, exclude_symbols=None):
     """
     Handle a namespace compound definition.
     """
+    if exclude_symbols is None:
+        exclude_symbols = []
+
     # Skip anonymous namespaces (internal linkage, not public API).
     # Doxygen encodes them with a '@' prefix in the compound name.
     if "@" in compound_object.compoundname:
@@ -78,7 +106,9 @@ def _handle_namespace_compound(snapshot, compound_object):
 
     namespace_scope.location = compound_object.location.file
 
-    _process_namespace_sections(snapshot, namespace_scope, compound_object)
+    _process_namespace_sections(
+        snapshot, namespace_scope, compound_object, exclude_symbols
+    )
 
 
 def _handle_concept_compound(snapshot, compound_object):
@@ -140,10 +170,18 @@ def _handle_class_compound(snapshot, compound_object):
 )
 
 
-def build_snapshot(xml_dir: str) -> Snapshot:
+def build_snapshot(xml_dir: str, exclude_symbols: list[str] | None = None) -> Snapshot:
     """
     Reads the Doxygen XML output and builds a snapshot of the C++ API.
+
+    Args:
+        xml_dir: Path to the Doxygen XML output directory.
+        exclude_symbols: Optional list of substring patterns. Compounds whose
+            qualified name contains any of these patterns will be excluded.
     """
+    if exclude_symbols is None:
+        exclude_symbols = []
+
     index_path = os.path.join(xml_dir, "index.xml")
     if not os.path.exists(index_path):
         raise RuntimeError(f"Doxygen entry point not found at {index_path}")
@@ -163,12 +201,19 @@ def build_snapshot(xml_dir: str) -> Snapshot:
             if compound_object.prot == "private":
                 continue
 
+            if _should_exclude_symbol(compound_object.compoundname, exclude_symbols):
+                continue
+
             kind = compound_object.kind
 
             if kind in _IGNORED_COMPOUNDS:
                 pass
             elif kind in _COMPOUND_HANDLERS:
-                _COMPOUND_HANDLERS[kind](snapshot, compound_object)
+                handler = _COMPOUND_HANDLERS[kind]
+                if handler == _handle_namespace_compound:
+                    handler(snapshot, compound_object, exclude_symbols)
+                else:
+                    handler(snapshot, compound_object)
             else:
                 print(f"Unknown compound kind: {kind}")
 

scripts/cxx-api/tests/test_config.py

@@ -480,6 +480,93 @@ def test_global_exclude_patterns_applied_to_all_platforms(self):
         view_b = next(r for r in result if r.snapshot_name == "ViewB")
         self.assertEqual(view_b.exclude_patterns, ["*/test/*", "*/b_only/*"])
 
+    # =========================================================================
+    # Exclude symbols
+    # =========================================================================
+
+    def test_exclude_symbols_parsed(self):
+        """Global exclude_symbols are parsed and propagated"""
+        config = {
+            "exclude_symbols": ["Fantom", "::detail::"],
+            "platforms": {
+                "TestView": {
+                    "inputs": [],
+                    "definitions": {},
+                }
+            },
+        }
+        result = parse_config(config, "/base/dir")
+
+        self.assertEqual(result[0].exclude_symbols, ["Fantom", "::detail::"])
+
+    def test_exclude_symbols_propagated_to_variants(self):
+        """Global exclude_symbols are propagated to all variant configs"""
+        config = {
+            "exclude_symbols": ["Fantom"],
+            "platforms": {
+                "TestView": {
+                    "inputs": [],
+                    "definitions": {},
+                    "variants": {
+                        "debug": {"definitions": {"DEBUG": 1}},
+                        "release": {"definitions": {"NDEBUG": 1}},
+                    },
+                }
+            },
+        }
+        result = parse_config(config, "/base/dir")
+
+        self.assertEqual(len(result), 2)
+        for r in result:
+            self.assertEqual(r.exclude_symbols, ["Fantom"])
+
+    def test_exclude_symbols_default_empty(self):
+        """Missing exclude_symbols defaults to empty list"""
+        config = {
+            "platforms": {
+                "TestView": {
+                    "inputs": [],
+                    "definitions": {},
+                }
+            }
+        }
+        result = parse_config(config, "/base/dir")
+
+        self.assertEqual(result[0].exclude_symbols, [])
+
+    def test_exclude_symbols_none_treated_as_empty(self):
+        """None exclude_symbols treated as empty list"""
+        config = {
+            "exclude_symbols": None,
+            "platforms": {
+                "TestView": {
+                    "inputs": [],
+                    "definitions": {},
+                }
+            },
+        }
+        result = parse_config(config, "/base/dir")
+
+        self.assertEqual(result[0].exclude_symbols, [])
+
+    def test_exclude_symbols_applied_to_all_platforms(self):
+        """Global exclude_symbols apply to every platform"""
+        config = {
+            "exclude_symbols": ["Fantom"],
+            "platforms": {
+                "ViewA": {
+                    "inputs": [],
+                },
+                "ViewB": {
+                    "inputs": [],
+                },
+            },
+        }
+        result = parse_config(config, "/base/dir")
+
+        for r in result:
+            self.assertEqual(r.exclude_symbols, ["Fantom"])
+
     # =========================================================================
     # Variant naming
     # =========================================================================