Normalize Objective-C nullability annotations (facebook#55898)

Summary:
Pull Request resolved: facebook#55898

Normalize Objective-C nullability annotations in the cxx-api parser to ensure consistent output in API snapshots.

Objective-C has three different forms of nullability annotations that are semantically equivalent:
- `nonnull`/`nullable` (context-sensitive keywords)
- `_Nonnull`/`_Nullable` (type qualifiers)
- `__nonnull`/`__nullable` (legacy Apple macros)

This diff normalizes all forms to `_Nonnull`/`_Nullable` for consistency.

**Examples:**
- `nonnull NSString*` → `_Nonnull NSString*`
- `NSString* __nonnull` → `NSString* _Nonnull`
- `nullable id` → `_Nullable id`
- `id __nullable` → `id _Nullable`
- `NSString* _Nonnull` → `NSString* _Nonnull` (unchanged)

Added a test case to verify the normalization works correctly.

Changelog:
[Internal]

Reviewed By: cortinico

Differential Revision: D95195669

Author: coado

scripts/cxx-api/parser/utils/text_resolution.py

@@ -90,6 +90,30 @@ def normalize_angle_brackets(text: str) -> str:
     return text
 
 
+def normalize_nullability(text: str) -> str:
+    """Normalize Objective-C nullability annotations to a consistent form.
+
+    There are three forms of nullability annotations in Objective-C:
+    - nonnull/nullable (context-sensitive keywords, typically used as prefix)
+    - _Nonnull/_Nullable (type qualifiers, can appear after the type)
+    - __nonnull/__nullable (legacy Apple macros, deprecated but still used)
+
+    This function normalizes all forms to _Nonnull/_Nullable, which is the
+    most flexible form that can be used in any position.
+    """
+    # Normalize __nonnull -> _Nonnull (must come before nonnull)
+    text = re.sub(r"\b__nonnull\b", "_Nonnull", text)
+    # Normalize nonnull -> _Nonnull (negative lookbehind to avoid _Nonnull)
+    text = re.sub(r"(?<!_)\bnonnull\b", "_Nonnull", text)
+
+    # Normalize __nullable -> _Nullable (must come before nullable)
+    text = re.sub(r"\b__nullable\b", "_Nullable", text)
+    # Normalize nullable -> _Nullable (negative lookbehind to avoid _Nullable)
+    text = re.sub(r"(?<!_)\bnullable\b", "_Nullable", text)
+
+    return text
+
+
 def normalize_pointer_spacing(text: str) -> str:
     """Normalize spacing around pointer (*) and reference (&, &&) symbols.
 
@@ -137,14 +161,20 @@ def resolve_ref_text_name(type_def: compound.refTextType) -> str:
                     name += part.value.valueOf_
                 else:
                     name += str(part.value)
-        return normalize_pointer_spacing(normalize_angle_brackets(name))
+        return normalize_nullability(
+            normalize_pointer_spacing(normalize_angle_brackets(name))
+        )
 
     if type_def.ref:
-        return normalize_pointer_spacing(
-            normalize_angle_brackets(type_def.ref[0].get_valueOf_())
+        return normalize_nullability(
+            normalize_pointer_spacing(
+                normalize_angle_brackets(type_def.ref[0].get_valueOf_())
+            )
         )
 
-    return normalize_pointer_spacing(normalize_angle_brackets(type_def.get_valueOf_()))
+    return normalize_nullability(
+        normalize_pointer_spacing(normalize_angle_brackets(type_def.get_valueOf_()))
+    )
 
 
 class InitializerType(Enum):
@@ -203,7 +233,9 @@ def resolve_linked_text_name(
             name = name[1:-1].strip()
 
     return (
-        normalize_pointer_spacing(normalize_angle_brackets(name.strip())),
+        normalize_nullability(
+            normalize_pointer_spacing(normalize_angle_brackets(name.strip()))
+        ),
         initialier_type,
     )
 

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

@@ -0,0 +1,10 @@
+interface NullabilityTest : public NSObject {
+  public @property (assign) NSString* nonnullProperty;
+  public @property (assign) NSString* nullableProperty;
+  public virtual NSString* _Nonnull legacyNonnullMethod();
+  public virtual NSString* _Nonnull modernNonnullMethod();
+  public virtual NSString* _Nullable legacyNullableMethod();
+  public virtual NSString* _Nullable modernNullableMethod();
+  public virtual _Nonnull NSString* nonnullMethod();
+  public virtual _Nullable NSString* nullableMethod();
+}

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

@@ -0,0 +1,21 @@
+/*
+ * 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 NullabilityTest : NSObject
+
+// Different nullability annotation styles that should be normalized
+- (nonnull NSString *)nonnullMethod;
+- (nullable NSString *)nullableMethod;
+- (NSString *__nonnull)legacyNonnullMethod;
+- (NSString *__nullable)legacyNullableMethod;
+- (NSString *_Nonnull)modernNonnullMethod;
+- (NSString *_Nullable)modernNullableMethod;
+
+@property (nonatomic, nonnull) NSString *nonnullProperty;
+@property (nonatomic, nullable) NSString *nullableProperty;
+
+@end