fix: stabilize CXX API generator on MacOS, make parser indempotent for nested enums (#57536)

Summary:
Fixes C++ API snapshot generation failures for nested enums and macOS/Linux output drift due to platform-dependent behavior, in the CXX API generator.

### Problems

1. Duplicate enums: Doxygen parses codegen `EventEmitters.h` twice (direct codegen input + again via `.mm` includes). The parser raised `RuntimeError: Identifier OnOrientationChangeOrientation already exists in scope ModalHostViewEventEmitter` on `ReactApple*` views.

2. Inconsistent behaviour on MacOS vs Linux:
  - for codegen component aliases (`ConcreteComponentDescriptor`, `ConcreteViewShadowNode`), macOS Doxygen emits hybrid XML definitions (`typedef Type Name = Type`) while Linux CI emits `using Name = Type`. The parser keyed off `definition.startswith("typedef")`, so identical source produced different `.api` output per platform.
  - `CASE_SENSE_NAMES = SYSTEM` follows the host OS default (case-insensitive on macOS, case-sensitive on Linux), causing inconsistent symbol resolution.

### Resolution

- `.doxygen.config.template` files: set `CASE_SENSE_NAMES = YES` for deterministic name matching across macOS and Linux.
- `snapshot.py`: `create_enum()` returns an existing enum scope instead of raising when the enum is already registered.
- `builders.py`: `create_enum_scope()` to skip enums that already exist; `get_typedef_member()` to normalize Doxygen’s `typedef ... = ...` form to `using` so the output format is unified.

## Changelog:

[INTERNAL] [FIXED] - Fix C++ API snapshot generation crash on duplicate codegen enums
[INTERNAL] [FIXED] - Fix platform-dependent inconsistent CXX API generator output

Pull Request resolved: https://github.com/react/react-native/pull/57536

Test Plan:
- [x] `yarn cxx-api-build` completes on macOS (tested locally)
- [x] `yarn cxx-api-validate` passes (tested locally on MacOS & on the Linux CI)
- [x] `validate-cxx-api-snapshots` passes on Linux (tested on CI)

Reviewed By: j-piasecki

Differential Revision: D112793182

Pulled By: coado

fbshipit-source-id: ada818451fb1207d965c1bed4fb5ce23ee2fe00f
This commit is contained in:
artus9033 authored and meta-codesync[bot] committed 2026-07-20 05:01:24 -07:00
1 parent f2a6db9fce
commit 566c7ac2d1
5 files changed
+29 -4

No files matched your search

@@ -653,7 +653,7 @@ INTERNAL_DOCS = NO
# Possible values are: SYSTEM, NO and YES.
# The default value is: SYSTEM.
CASE_SENSE_NAMES = SYSTEM
CASE_SENSE_NAMES = YES
# If the HIDE_SCOPE_NAMES tag is set to NO then Doxygen will show members with
# their full class and namespace scopes in the documentation. If set to YES, the
@@ -653,7 +653,7 @@ INTERNAL_DOCS = NO
# Possible values are: SYSTEM, NO and YES.
# The default value is: SYSTEM.
CASE_SENSE_NAMES = SYSTEM
CASE_SENSE_NAMES = YES
# If the HIDE_SCOPE_NAMES tag is set to NO then Doxygen will show members with
# their full class and namespace scopes in the documentation. If set to YES, the
+24 -1
View File
@@ -28,6 +28,7 @@ from .member import (
TypedefMember,
VariableMember,
)
from .member.base import is_function_pointer_argstring
from .scope import InterfaceScopeKind, ProtocolScopeKind, StructLikeScopeKind
from .snapshot import Snapshot
from .template import Template
@@ -460,7 +461,21 @@ def get_typedef_member(
typedef_keyword = "using"
if typedef_definition.startswith("typedef"):
typedef_keyword = "typedef"
# Doxygen's "combining using relations" pass can emit hybrid definitions
# like "typedef Type Name = Type" for using-declarations on macOS, while
# Linux builds report "using Name = Type". Normalise the hybrid form for
# codegen component aliases so snapshots are stable across platforms.
if (
"=" in typedef_definition
and not is_function_pointer_argstring(typedef_argstring)
and (
"ConcreteComponentDescriptor" in typedef_definition
or "ConcreteViewShadowNode" in typedef_definition
)
):
typedef_keyword = "using"
else:
typedef_keyword = "typedef"
typedef = TypedefMember(
typedef_name,
@@ -605,6 +620,14 @@ def create_enum_scope(snapshot: Snapshot, enum_def: compound.EnumdefType) -> Non
"""
Create an enum scope in the snapshot.
"""
path = parse_qualified_path(enum_def.qualifiedname)
parent_scope = snapshot.ensure_scope(path[0:-1])
enum_name = path[-1]
if enum_name in parent_scope.inner_scopes:
existing = parent_scope.inner_scopes[enum_name]
if existing.kind.name == "enum":
return
scope = snapshot.create_enum(enum_def.qualifiedname)
scope.kind.type = resolve_linked_text_name(enum_def.get_type())[0]
scope.location = enum_def.location.file
+2
View File
@@ -184,6 +184,8 @@ class Snapshot:
scope = current_scope.inner_scopes[enum_name]
if scope.kind.name == "temporary":
scope.kind = EnumScopeKind()
elif scope.kind.name == "enum":
return scope
else:
raise RuntimeError(
f"Identifier {enum_name} already exists in scope {current_scope.name}"
@@ -653,7 +653,7 @@ INTERNAL_DOCS = NO
# Possible values are: SYSTEM, NO and YES.
# The default value is: SYSTEM.
CASE_SENSE_NAMES = SYSTEM
CASE_SENSE_NAMES = YES
# If the HIDE_SCOPE_NAMES tag is set to NO then Doxygen will show members with
# their full class and namespace scopes in the documentation. If set to YES, the