diff --git a/scripts/cxx-api/config.yml b/scripts/cxx-api/config.yml index 623a392234c..65ceefb0022 100644 --- a/scripts/cxx-api/config.yml +++ b/scripts/cxx-api/config.yml @@ -5,7 +5,7 @@ ReactCommon: exclude_patterns: - "*/test_utils/*" - "*/jni/*" - - "*/platform/cxx/*" + - "*/platform/cxx/*" # Should this be included in ReactCommon? - "*/platform/windows/*" - "*/platform/macos/*" - "*/platform/ios/*" diff --git a/scripts/cxx-api/parser/member.py b/scripts/cxx-api/parser/member.py index d6930ba55e0..d5fe3cb2639 100644 --- a/scripts/cxx-api/parser/member.py +++ b/scripts/cxx-api/parser/member.py @@ -6,6 +6,7 @@ from __future__ import annotations from abc import ABC, abstractmethod +from enum import IntEnum from typing import TYPE_CHECKING from .template import Template, TemplateList @@ -25,12 +26,31 @@ if TYPE_CHECKING: from .scope import Scope +class MemberKind(IntEnum): + """ + Classification of member kinds for grouping in output. + The order here determines the output order within namespace scopes. + """ + + CONSTANT = 0 + TYPE_ALIAS = 1 + CONCEPT = 2 + FUNCTION = 3 + OPERATOR = 4 + VARIABLE = 5 + + class Member(ABC): def __init__(self, name: str, visibility: str) -> None: self.name: str = name self.visibility: str = visibility self.template_list: TemplateList | None = None + @property + @abstractmethod + def member_kind(self) -> MemberKind: + pass + @abstractmethod def to_string( self, @@ -62,6 +82,10 @@ class EnumMember(Member): super().__init__(name, "public") self.value: str | None = value + @property + def member_kind(self) -> MemberKind: + return MemberKind.CONSTANT + def to_string( self, indent: int = 0, @@ -104,6 +128,12 @@ class VariableMember(Member): ) self._parsed_type: list[str | list[Argument]] = parse_type_with_argstrings(type) + @property + def member_kind(self) -> MemberKind: + if self.is_const or self.is_constexpr: + return MemberKind.CONSTANT + return MemberKind.VARIABLE + def close(self, scope: Scope): self._fp_arguments = qualify_arguments(self._fp_arguments, scope) self._parsed_type = qualify_parsed_type(self._parsed_type, scope) @@ -188,6 +218,12 @@ class FunctionMember(Member): self.is_const = self.modifiers.is_const self.is_override = self.modifiers.is_override + @property + def member_kind(self) -> MemberKind: + if self.name.startswith("operator"): + return MemberKind.OPERATOR + return MemberKind.FUNCTION + def close(self, scope: Scope): self.type = qualify_type_str(self.type, scope) self.arguments = qualify_arguments(self.arguments, scope) @@ -264,6 +300,10 @@ class TypedefMember(Member): self._parsed_type: list[str | list[Argument]] = parse_type_with_argstrings(type) self.type: str = type + @property + def member_kind(self) -> MemberKind: + return MemberKind.TYPE_ALIAS + def close(self, scope: Scope): self._fp_arguments = qualify_arguments(self._fp_arguments, scope) self._parsed_type = qualify_parsed_type(self._parsed_type, scope) @@ -315,6 +355,10 @@ class ConceptMember(Member): super().__init__(name, "public") self.constraint: str = self._normalize_constraint(constraint) + @property + def member_kind(self) -> MemberKind: + return MemberKind.CONCEPT + @staticmethod def _normalize_constraint(constraint: str) -> str: """ diff --git a/scripts/cxx-api/parser/scope.py b/scripts/cxx-api/parser/scope.py index a6086094f3e..ced8491758d 100644 --- a/scripts/cxx-api/parser/scope.py +++ b/scripts/cxx-api/parser/scope.py @@ -9,13 +9,17 @@ from abc import ABC, abstractmethod from enum import Enum from typing import Generic, TypeVar -from natsort import natsorted +from natsort import natsort_keygen, natsorted -from .member import Member +from .member import Member, MemberKind from .template import Template, TemplateList from .utils import parse_qualified_path +# Pre-create natsort key function for efficiency +_natsort_key = natsort_keygen() + + class ScopeKind(ABC): def __init__(self, name) -> None: self.name: str = name @@ -105,11 +109,20 @@ class NamespaceScopeKind(ScopeKind): def to_string(self, scope: Scope) -> str: qualification = scope.get_qualified_name() + # Group members by kind + groups: dict[MemberKind, list[str]] = {kind: [] for kind in MemberKind} + + for member in scope.get_members(): + kind = member.member_kind + stringified = member.to_string(0, qualification, hide_visibility=True) + groups[kind].append(stringified) + + # Sort within each group and combine in kind order result = [] - for member in scope.get_members(): - result.append(member.to_string(0, qualification, hide_visibility=True)) + for kind in MemberKind: + sorted_group = natsorted(groups[kind]) + result.extend(sorted_group) - result = natsorted(result) return "\n".join(result) @@ -264,16 +277,56 @@ class Scope(Generic[ScopeKindT]): """ Get the string representation of the scope. """ - result = [self.kind.to_string(self)] + # Get this scope's content (e.g., class members, free functions, ...) + this_content = self.kind.to_string(self) - for _, inner_scope in sorted( - filter(lambda x: x[0] is not None, self.inner_scopes.items()), - key=lambda x: x[0], - ): - result.append(inner_scope.to_string()) + # Separate inner scopes into namespaces and non-namespaces + # Keep (scope, string) tuples to sort by scope properties + namespace_scope_items: list[tuple[Scope, str]] = [] + non_namespace_scope_items: list[tuple[Scope, str]] = [] - result = natsorted(result) - return "\n\n".join(result).strip() + for _, inner_scope in self.inner_scopes.items(): + if inner_scope.name is None: + continue + inner_str = inner_scope.to_string() + if not inner_str.strip(): + continue + + if isinstance(inner_scope.kind, NamespaceScopeKind): + namespace_scope_items.append((inner_scope, inner_str)) + else: + non_namespace_scope_items.append((inner_scope, inner_str)) + + # Sort non-namespace scopes by depth (fewer :: first) then by string + def scope_sort_key(item: tuple[Scope, str]) -> tuple: + scope, string = item + depth = scope.get_qualified_name().count("::") + return (depth, _natsort_key(string)) + + non_namespace_scope_items.sort(key=scope_sort_key) + non_namespace_scope_strings = [s for _, s in non_namespace_scope_items] + namespace_scope_strings = [s for _, s in namespace_scope_items] + + # Build result: + # 1. Free members / this scope's content first + # 2. Non-namespace inner scopes (classes, structs, enums), sorted by depth + # 3. Namespace inner scopes, each separated by "\n\n\n" (two blank lines) + + local_parts = [] + if this_content.strip(): + local_parts.append(this_content) + local_parts.extend(non_namespace_scope_strings) + + # NOTE: Don't sort local_parts together - free members should come first + local_block = "\n\n".join(local_parts) + + # Combine with namespace scopes using one more blank line for clearer separation + all_blocks = [] + if local_block.strip(): + all_blocks.append(local_block) + all_blocks.extend(natsorted(namespace_scope_strings)) + + return "\n\n\n".join(all_blocks).strip() def print(self): """ diff --git a/scripts/cxx-api/tests/snapshots/should_handle_struct_with_enum/snapshot.api b/scripts/cxx-api/tests/snapshots/should_handle_struct_with_enum/snapshot.api index 8407635093b..96b0e1e9b06 100644 --- a/scripts/cxx-api/tests/snapshots/should_handle_struct_with_enum/snapshot.api +++ b/scripts/cxx-api/tests/snapshots/should_handle_struct_with_enum/snapshot.api @@ -1,7 +1,7 @@ +struct test::TestStruct { +} + enum test::TestStruct::Enum { Value1, Value2, } - -struct test::TestStruct { -} diff --git a/scripts/cxx-api/tests/snapshots/should_qualify_free_declarations/snapshot.api b/scripts/cxx-api/tests/snapshots/should_qualify_free_declarations/snapshot.api index f65f0cac022..75eab9550ed 100644 --- a/scripts/cxx-api/tests/snapshots/should_qualify_free_declarations/snapshot.api +++ b/scripts/cxx-api/tests/snapshots/should_qualify_free_declarations/snapshot.api @@ -1,6 +1,6 @@ -struct test::Param { -} - typedef void(*test::FreeFnPtr)(test::Param); using test::FreeCallback = void(test::Param); void test::freeFunction(test::Param p); + +struct test::Param { +} diff --git a/scripts/cxx-api/tests/snapshots/should_qualify_partially_qualified_args/snapshot.api b/scripts/cxx-api/tests/snapshots/should_qualify_partially_qualified_args/snapshot.api index 1ebe9e74ffb..b96bccd048f 100644 --- a/scripts/cxx-api/tests/snapshots/should_qualify_partially_qualified_args/snapshot.api +++ b/scripts/cxx-api/tests/snapshots/should_qualify_partially_qualified_args/snapshot.api @@ -1,6 +1,7 @@ facebook::yoga::Result facebook::react::getResult(facebook::yoga::Node node, int flags); void facebook::react::processNode(facebook::yoga::Node node); + struct facebook::yoga::Node { }