Add support for parsing interfaces (#55770)

Summary:
Pull Request resolved: #55770

This diff adds support for parsing Objective-C interfaces in the C++ API snapshot parser.

Changelog:
[Internal]

Reviewed By: cipolleschi

Differential Revision: D94071995

fbshipit-source-id: b1b89d520a489be7c4a0e790874dd9f7b518df35

Author: coado

scripts/cxx-api/manual_test/.doxygen.config.template

@@ -2442,7 +2442,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             =
+PREDEFINED             = FOLLY_PACK_PUSH="" FOLLY_PACK_POP="" FOLLY_PACK_ATTR="" __attribute__(x)="" ${PREDEFINED}
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

scripts/cxx-api/parser/main.py

@@ -8,7 +8,6 @@
 import os
 import re
 from enum import Enum
-from pprint import pprint
 
 from doxmlparser import compound, index
 
@@ -21,7 +20,7 @@
     TypedefMember,
     VariableMember,
 )
-from .scope import ProtocolScopeKind, StructLikeScopeKind
+from .scope import InterfaceScopeKind, ProtocolScopeKind, StructLikeScopeKind
 from .snapshot import Snapshot
 from .template import Template
 from .utils import Argument, extract_qualifiers, parse_qualified_path
@@ -608,6 +607,66 @@ def create_protocol_scope(snapshot: Snapshot, scope_def: compound.CompounddefTyp
             )
 
 
+def create_interface_scope(snapshot: Snapshot, scope_def: compound.CompounddefType):
+    """
+    Create an interface scope in the snapshot (Objective-C @interface).
+    """
+    interface_name = scope_def.compoundname
+
+    interface_scope = snapshot.create_interface(interface_name)
+    base_classes = get_base_classes(scope_def, base_class=InterfaceScopeKind.Base)
+    interface_scope.kind.add_base(base_classes)
+    interface_scope.location = scope_def.location.file
+
+    for section_def in scope_def.sectiondef:
+        kind = section_def.kind
+        parts = kind.split("-")
+        visibility = parts[0]
+        is_static = "static" in parts
+        member_type = parts[-1]
+
+        if visibility == "private":
+            pass
+        elif visibility in ("public", "protected"):
+            if member_type == "attrib":
+                for member_def in section_def.memberdef:
+                    if member_def.kind == "variable":
+                        interface_scope.add_member(
+                            get_variable_member(member_def, visibility, is_static)
+                        )
+            elif member_type == "func":
+                for function_def in section_def.memberdef:
+                    interface_scope.add_member(
+                        get_function_member(function_def, visibility, is_static)
+                    )
+            elif member_type == "type":
+                for member_def in section_def.memberdef:
+                    if member_def.kind == "enum":
+                        create_enum_scope(snapshot, member_def)
+                    elif member_def.kind == "typedef":
+                        interface_scope.add_member(
+                            get_typedef_member(member_def, visibility)
+                        )
+                    else:
+                        print(
+                            f"Unknown section member kind: {member_def.kind} in {scope_def.location.file}"
+                        )
+            else:
+                print(
+                    f"Unknown interface section kind: {kind} in {scope_def.location.file}"
+                )
+        elif visibility == "property":
+            for member_def in section_def.memberdef:
+                if member_def.kind == "property":
+                    interface_scope.add_member(
+                        get_property_member(member_def, "public", is_static)
+                    )
+        else:
+            print(
+                f"Unknown interface visibility: {visibility} in {scope_def.location.file}"
+            )
+
+
 def build_snapshot(xml_dir: str) -> Snapshot:
     """
     Reads the Doxygen XML output and builds a snapshot of the C++ API.
@@ -628,12 +687,23 @@ def build_snapshot(xml_dir: str) -> Snapshot:
         doxygen_object = compound.parse(detail_file, silence=True)
 
         for compound_object in doxygen_object.compounddef:
+            # Check if this is an Objective-C interface by looking at the compound id
+            # Doxygen reports ObjC interfaces as kind="class" but with id starting with "interface"
+            is_objc_interface = (
+                compound_object.kind == "class"
+                and compound_object.id.startswith("interface")
+            )
+
             # classes and structs are represented by the same scope with a different kind
             if (
                 compound_object.kind == "class"
                 or compound_object.kind == "struct"
                 or compound_object.kind == "union"
             ):
+                # Handle Objective-C interfaces separately
+                if is_objc_interface:
+                    create_interface_scope(snapshot, compound_object)
+                    continue
                 class_scope = (
                     snapshot.create_struct_like(
                         compound_object.compoundname, StructLikeScopeKind.Type.CLASS
@@ -781,6 +851,8 @@ def build_snapshot(xml_dir: str) -> Snapshot:
                 pass
             elif compound_object.kind == "protocol":
                 create_protocol_scope(snapshot, compound_object)
+            elif compound_object.kind == "interface":
+                create_interface_scope(snapshot, compound_object)
             else:
                 print(f"Unknown compound kind: {compound_object.kind}")
 

scripts/cxx-api/parser/scope.py

@@ -202,6 +202,57 @@ def to_string(self, scope: Scope) -> str:
         return result
 
 
+class InterfaceScopeKind(ScopeKind):
+    class Base:
+        def __init__(
+            self, name: str, protection: str, virtual: bool, refid: str
+        ) -> None:
+            self.name: str = name
+            self.protection: str = protection
+            self.virtual: bool = virtual
+            self.refid: str = refid
+
+    def __init__(self) -> None:
+        super().__init__("interface")
+        self.base_classes: [InterfaceScopeKind.Base] = []
+
+    def add_base(
+        self, base: InterfaceScopeKind.Base | [InterfaceScopeKind.Base]
+    ) -> None:
+        if isinstance(base, list):
+            for b in base:
+                self.base_classes.append(b)
+        else:
+            self.base_classes.append(base)
+
+    def to_string(self, scope: Scope) -> str:
+        result = ""
+
+        bases = []
+        for base in self.base_classes:
+            base_text = [base.protection]
+            if base.virtual:
+                base_text.append("virtual")
+            base_text.append(base.name)
+            bases.append(" ".join(base_text))
+
+        inheritance_string = " : " + ", ".join(bases) if bases else ""
+
+        result += f"{self.name} {scope.get_qualified_name()}{inheritance_string} {{"
+
+        stringified_members = []
+        for member in scope.get_members():
+            stringified_members.append(member.to_string(2))
+        stringified_members = natsorted(stringified_members)
+        result += ("\n" if len(stringified_members) > 0 else "") + "\n".join(
+            stringified_members
+        )
+
+        result += "\n}"
+
+        return result
+
+
 class TemporaryScopeKind(ScopeKind):
     def __init__(self) -> None:
         super().__init__("temporary")

scripts/cxx-api/parser/snapshot.py

@@ -7,6 +7,7 @@
 
 from .scope import (
     EnumScopeKind,
+    InterfaceScopeKind,
     NamespaceScopeKind,
     ProtocolScopeKind,
     Scope,
@@ -109,6 +110,30 @@ def create_protocol(self, qualified_name: str) -> Scope[ProtocolScopeKind]:
             current_scope.inner_scopes[scope_name] = new_scope
             return new_scope
 
+    def create_interface(self, qualified_name: str) -> Scope[InterfaceScopeKind]:
+        """
+        Create an interface in the snapshot.
+        """
+        path = parse_qualified_path(qualified_name)
+        scope_path = path[0:-1]
+        scope_name = path[-1]
+        current_scope = self.ensure_scope(scope_path)
+
+        if scope_name in current_scope.inner_scopes:
+            scope = current_scope.inner_scopes[scope_name]
+            if scope.kind.name == "temporary":
+                scope.kind = InterfaceScopeKind()
+            else:
+                raise RuntimeError(
+                    f"Identifier {scope_name} already exists in scope {current_scope.name}"
+                )
+            return scope
+        else:
+            new_scope = Scope(InterfaceScopeKind(), scope_name)
+            new_scope.parent_scope = current_scope
+            current_scope.inner_scopes[scope_name] = new_scope
+            return new_scope
+
     def create_enum(self, qualified_name: str) -> Scope[EnumScopeKind]:
         """
         Create an enum in the snapshot.

scripts/cxx-api/tests/snapshots/should_handle_interface_empty/snapshot.api

@@ -0,0 +1,2 @@
+interface RCTEmptyInterface {
+}

scripts/cxx-api/tests/snapshots/should_handle_interface_empty/test.h

@@ -0,0 +1,10 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+@interface RCTEmptyInterface
+
+@end

scripts/cxx-api/tests/snapshots/should_handle_interface_inheritance/snapshot.api

@@ -0,0 +1,7 @@
+interface RCTBaseInterface {
+  public virtual void baseMethod();
+}
+
+interface RCTChildInterface : public RCTBaseInterface {
+  public virtual void childMethod();
+}

scripts/cxx-api/tests/snapshots/should_handle_interface_inheritance/test.h

@@ -0,0 +1,18 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+@interface RCTBaseInterface
+
+- (void)baseMethod;
+
+@end
+
+@interface RCTChildInterface : RCTBaseInterface
+
+- (void)childMethod;
+
+@end

scripts/cxx-api/tests/snapshots/should_handle_interface_with_method/snapshot.api

@@ -0,0 +1,5 @@
+interface RCTInterfaceWithMethod {
+  public virtual NSString * getTitle();
+  public virtual void doSomething();
+  public virtual void processValue:withName:(int value, NSString * name);
+}

scripts/cxx-api/tests/snapshots/should_handle_interface_with_method/test.h

@@ -0,0 +1,14 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+@interface RCTInterfaceWithMethod
+
+- (void)doSomething;
+- (NSString *)getTitle;
+- (void)processValue:(int)value withName:(NSString *)name;
+
+@end