Update sorting and grouping behavior (#55647)

Summary:
Pull Request resolved: #55647

Changelog: [Internal]

Updates sorting and grouping behavior of C++ API snapshot.

Reviewed By: cipolleschi

Differential Revision: D93407634

Author: j-piasecki

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/*"

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 @@
     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 @@ def __init__(self, name: str, value: str | None) -> None:
         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 @@ def __init__(
         )
         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 @@ def __init__(
         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 @@ def __init__(
         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 @@ def __init__(
         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:
         """

scripts/cxx-api/parser/scope.py

@@ -9,13 +9,17 @@
 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 @@ def __init__(self) -> None:
     def to_string(self, scope: Scope) -> str:
         qualification = scope.get_qualified_name()
 
-        result = []
+        # Group members by kind
+        groups: dict[MemberKind, list[str]] = {kind: [] for kind in MemberKind}
+
         for member in scope.get_members():
-            result.append(member.to_string(0, qualification, hide_visibility=True))
+            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 kind in MemberKind:
+            sorted_group = natsorted(groups[kind])
+            result.extend(sorted_group)
 
-        result = natsorted(result)
         return "\n".join(result)
 
 
@@ -264,16 +277,56 @@ def to_string(self) -> str:
         """
         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):
         """

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 {
-}

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 {
+}

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 {
 }