main.py

# 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.

from __future__ import annotations

import os
import re
from enum import Enum
from pprint import pprint

from doxmlparser import compound, index

from .member import (
    ConceptMember,
    EnumMember,
    FriendMember,
    FunctionMember,
    PropertyMember,
    TypedefMember,
    VariableMember,
)
from .scope import ProtocolScopeKind, StructLikeScopeKind
from .snapshot import Snapshot
from .template import Template
from .utils import Argument, extract_qualifiers, parse_qualified_path


def decode_doxygen_template_encoding(encoded: str) -> str:
    """Decode Doxygen's encoding for template specializations in refids.

    Doxygen encodes special characters in refids using underscore-prefixed codes:
    - '_3' = '<' (template open)
    - '_4' = '>' (template close)
    - '_01' = ' ' (space)
    - '_07' = '(' (open paren)
    - '_08' = ')' (close paren)
    - '_8_8_8' = '...' (variadic ellipsis)
    - '_00' = ',' (comma)
    - '_02' = '*' (pointer)
    - '_05' = '=' (equals)
    - '_06' = '&' (reference)

    e.g. 'SyncCallback_3_01R_07Args_8_8_8_08_4' -> 'SyncCallback< R(Args...)>'
    """
    result = encoded

    # Process longer patterns first to avoid partial matches
    result = result.replace("_8_8_8", "...")  # Variadic ellipsis

    # Process two-char patterns (_0X codes)
    result = result.replace("_00", ", ")  # Comma (with space for readability)
    result = result.replace("_01", " ")  # Space
    result = result.replace("_02", "*")  # Pointer
    result = result.replace("_05", "=")  # Equals
    result = result.replace("_06", "&")  # Reference
    result = result.replace("_07", "(")  # Open paren
    result = result.replace("_08", ")")  # Close paren

    # Process single-char patterns last
    result = result.replace("_3", "<")  # Template open
    result = result.replace("_4", ">")  # Template close

    return result


def _strip_template_args(name: str) -> str:
    """Strip template arguments from a type name.

    e.g. 'SyncCallback< R(Args...)>' -> 'SyncCallback'
    """
    angle_idx = name.find("<")
    return name[:angle_idx].rstrip() if angle_idx != -1 else name


def _qualify_text_with_refid(text: str, refid: str) -> str:
    """Qualify a text symbol using the namespace extracted from its doxygen refid.

    For ref elements, doxygen provides a refid that encodes the fully qualified
    path to the referenced symbol. This function extracts the namespace from
    that refid and prepends it to the text, avoiding redundant qualification.

    Args:
        text: The symbol text (e.g., "SyncCallback")
        refid: The doxygen refid (e.g., "classfacebook_1_1react_1_1SyncCallback...")

    Returns:
        The qualified text (e.g., "facebook::react::SyncCallback")
    """
    ns = extract_namespace_from_refid(refid)

    # Skip re-qualification if text is already globally qualified
    # (starts with "::") - it's already an absolute path
    if not ns or text.startswith(ns) or text.startswith("::"):
        return text

    # The text may already start with a trailing portion of the namespace.
    # For example ns="facebook::react::HighResDuration" and
    # text="HighResDuration::zero". We need to find the longest suffix of ns
    # that is a prefix of text (on a "::" boundary) and only prepend the
    # missing part.
    ns_parts = ns.split("::")
    prepend = ns

    for i in range(1, len(ns_parts)):
        suffix = "::".join(ns_parts[i:])
        # Also compare without template args - for template specializations
        # like "SyncCallback< R(Args...)>", text "SyncCallback" should match
        base_suffix = _strip_template_args(ns_parts[i])
        if (
            text.startswith(suffix + "::")
            or text == suffix
            or text.startswith(base_suffix + "::")
            or text == base_suffix
        ):
            prepend = "::".join(ns_parts[:i])
            break

    return prepend + "::" + text


def normalize_angle_brackets(text: str) -> str:
    """Doxygen adds spaces around < and > to avoid XML ambiguity.
    e.g. "NSArray< id< RCTBridgeMethod > > *" -> "NSArray<id<RCTBridgeMethod>> *"
    """
    text = re.sub(r"<\s+", "<", text)
    text = re.sub(r"\s+>", ">", text)
    return text


def extract_namespace_from_refid(refid: str) -> str:
    """Extract the namespace prefix from a doxygen refid.
    e.g. 'namespacefacebook_1_1yoga_1a...' -> 'facebook::yoga'
         'structfacebook_1_1react_1_1detail_1_1is__dynamic' -> 'facebook::react::detail::is_dynamic'
         'classfacebook_1_1react_1_1SyncCallback_3_01R_07Args_8_8_8_08_4' -> 'facebook::react::SyncCallback< R(Args...)>'

    Doxygen encoding:
    - '::' is encoded as '_1_1'
    - '_' in identifiers is encoded as '__' (double underscore)
    - Template specializations are encoded with hex-like codes (see decode_doxygen_template_encoding)
    """
    for prefix in ("namespace", "struct", "class", "union"):
        if refid.startswith(prefix):
            compound_part = refid[len(prefix) :]
            idx = compound_part.find("_1a")
            if idx != -1:
                compound_part = compound_part[:idx]
            # First replace '::' encoding (_1_1 -> ::)
            result = compound_part.replace("_1_1", "::")
            # Then replace double underscore with single underscore
            # (Doxygen encodes '_' in identifiers as '__')
            result = result.replace("__", "_")
            # Decode template specialization encodings
            result = decode_doxygen_template_encoding(result)
            return result
    return ""


class InitializerType(Enum):
    NONE = (0,)
    ASSIGNMENT = (1,)
    BRACE = 2


def resolve_linked_text_name(
    type_def: compound.linkedTextType,
    strip_initializers: bool = False,
) -> (str, InitializerType):
    """
    Resolve the full text content of a linkedTextType, including all text
    fragments and ref elements.
    """
    name = ""
    in_string = False

    if hasattr(type_def, "content_") and type_def.content_:
        for part in type_def.content_:
            if part.category == 1:  # MixedContainer.CategoryText
                in_string = part.value.count('"') % 2 != in_string
                name += part.value
            elif part.category == 3:  # MixedContainer.CategoryComplex (ref element)
                # For ref elements, get the text content and fully qualify using refid
                text = ""
                if hasattr(part.value, "get_valueOf_"):
                    text = part.value.get_valueOf_()
                elif hasattr(part.value, "valueOf_"):
                    text = part.value.valueOf_
                else:
                    text = str(part.value)

                # Don't resolve refs inside string literals - doxygen may
                # incorrectly treat symbols in strings as references
                refid = getattr(part.value, "refid", None)
                if refid and not in_string:
                    text = _qualify_text_with_refid(text, refid)

                name += text
    elif type_def.ref:
        name = type_def.ref[0].get_valueOf_()
    else:
        name = type_def.get_valueOf_()

    initialier_type = InitializerType.NONE
    if strip_initializers:
        if name.startswith("="):
            # Detect assignment initializers: = value
            initialier_type = InitializerType.ASSIGNMENT
            name = name[1:]
        elif name.startswith("{") and name.endswith("}"):
            # Detect brace initializers: {value}
            initialier_type = InitializerType.BRACE
            name = name[1:-1].strip()

    return (normalize_angle_brackets(name.strip()), initialier_type)


def get_base_classes(
    compound_object: compound.CompounddefType,
    base_class=StructLikeScopeKind.Base,
) -> list:
    """
    Get the base classes of a compound object.
    """
    base_classes = []
    if compound_object.basecompoundref:
        for base in compound_object.basecompoundref:
            # base is a compoundRefType with:
            # - refid: reference ID to the base class definition
            # - prot: protection level (public, protected, private)
            # - virt: virtual inheritance (non-virtual, virtual, pure-virtual)
            # - valueOf_: the name of the base class
            base_name = base.valueOf_
            base_prot = base.prot
            base_virt = base.virt
            base_refid = base.refid

            if base_prot == "private":
                # Ignore private base classes
                continue

            base_classes.append(
                base_class(
                    base_name,
                    base_prot,
                    base_virt == "virtual",
                    base_refid,
                )
            )
    return base_classes


def get_template_params(
    compound_object: compound.CompounddefType,
) -> [Template]:
    """
    Get the template parameters of a compound object.
    """
    template_params = []
    if compound_object.templateparamlist is not None:
        for param in compound_object.templateparamlist.param:
            template_value = (
                resolve_linked_text_name(param.defval)[0] if param.defval else None
            )
            template_name = param.defname
            template_type = resolve_linked_text_name(param.get_type())[0]

            if template_name is None:
                # Split type string and extract name from the end
                # Handles: "typename T", "class T", "int N", etc.
                parts = template_type.strip().split()
                if len(parts) >= 2:
                    template_type = " ".join(parts[:-1])
                    template_name = parts[-1]
                elif len(parts) == 1:
                    # Check if this is an unnamed template parameter
                    # (just "typename" or "class" with or without a default value)
                    # In this case, we leave name as None/empty
                    if parts[0] in ("typename", "class"):
                        # Unnamed template parameter
                        # e.g., "typename" or "typename = std::enable_if_t<...>"
                        template_name = None
                    else:
                        # Just a name like "T" with no type keyword
                        template_name = parts[0]

            template_params.append(
                Template(template_type, template_name, template_value)
            )
    return template_params


def get_variable_member(
    member_def: compound.MemberdefType,
    visibility: str,
    is_static: bool = False,
) -> VariableMember:
    """
    Get the variable member from a member definition.
    """
    variable_name = member_def.get_name()

    if len(variable_name) == 0:
        # Ignore anonymous variables
        return None

    (variable_type, _) = resolve_linked_text_name(member_def.get_type())
    variable_value = None
    variable_definition = member_def.definition
    variable_argstring = member_def.get_argsstring()

    is_constexpr = member_def.constexpr == "yes"
    is_mutable = member_def.mutable == "yes"

    if is_constexpr and variable_type.find("constexpr") != -1:
        variable_type = variable_type.replace("constexpr", "").strip()

    is_const = variable_type.startswith("const")
    if is_const:
        variable_type = variable_type[5:].strip()

    is_brace_initializer = False
    if member_def.initializer is not None:
        (variable_value, initializer_type) = resolve_linked_text_name(
            member_def.initializer,
            strip_initializers=True,
        )
        if initializer_type == InitializerType.BRACE:
            is_brace_initializer = True

    return VariableMember(
        variable_name,
        variable_type,
        visibility,
        is_const,
        is_static,
        is_constexpr,
        is_mutable,
        variable_value,
        variable_definition,
        variable_argstring,
        is_brace_initializer,
    )


def get_doxygen_params(
    function_def: compound.MemberdefType,
) -> list[tuple[str | None, str, str | None, str | None]] | None:
    """
    Extract structured parameter information from doxygen <param> elements.

    Returns a list of Argument tuples (qualifiers, type, name, default_value),
    or None if no <param> elements are available.
    """
    params = function_def.param
    if not params:
        return None

    arguments: list[Argument] = []
    for param in params:
        param_type = (
            resolve_linked_text_name(param.get_type())[0].strip()
            if param.get_type()
            else ""
        )
        param_name = param.declname or param.defname or None
        param_default = (
            resolve_linked_text_name(param.defval)[0].strip() if param.defval else None
        )

        # Doxygen splits array dimensions into a separate <array> element.
        # For complex declarators like "PropNameID (&&propertyNames)[N]",
        # doxygen gives type="PropNameID(&&)", name="propertyNames",
        # array="[N]".  We must reconstruct the full declarator with the
        # name embedded inside the grouping parentheses:
        #   PropNameID(&&propertyNames)[N]
        param_array = param.array
        if param_array:
            # Match type ending with a pointer/reference declarator group:
            # e.g. "PropNameID(&&)", "int(&)", "void(*)"
            m = re.search(r"\([*&]+\)\s*$", param_type)
            if m and param_name:
                # Insert name before the closing ')' and append array
                insert_pos = m.end() - 1  # position of trailing ')'
                param_type = (
                    param_type[:insert_pos]
                    + param_name
                    + param_type[insert_pos:]
                    + param_array
                )
                param_name = None
            else:
                param_type += param_array

        qualifiers, core_type = extract_qualifiers(param_type)
        arguments.append((qualifiers, core_type, param_name, param_default))

    return arguments


def get_function_member(
    function_def: compound.MemberdefType,
    visibility: str,
    is_static: bool = False,
) -> FunctionMember:
    """
    Get the function member from a member definition.
    """
    function_name = function_def.get_name()
    function_type = resolve_linked_text_name(function_def.get_type())[0]
    function_arg_string = function_def.get_argsstring()
    is_pure_virtual = function_def.get_virt() == "pure-virtual"
    function_virtual = function_def.get_virt() == "virtual" or is_pure_virtual
    is_constexpr = function_def.constexpr == "yes"

    # Doxygen incorrectly merges "=0" into the return type for pure-virtual
    # functions using trailing return types (e.g. "auto f() -> T = 0").
    # Strip the trailing "=0" from the type string.
    function_type = re.sub(r"\s*=\s*0\s*$", "", function_type)

    # For constexpr constructors, Doxygen outputs "constexpr" both as an
    # attribute (constexpr="yes") and as the return type (<type>constexpr</type>).
    # Remove the redundant type to avoid "constexpr constexpr" in output.
    if is_constexpr and function_type == "constexpr":
        function_type = ""

    doxygen_params = get_doxygen_params(function_def)

    function = FunctionMember(
        function_name,
        function_type,
        visibility,
        function_arg_string,
        function_virtual,
        is_pure_virtual,
        is_static,
        doxygen_params,
        is_constexpr,
    )

    function.add_template(get_template_params(function_def))

    return function


def get_typedef_member(
    typedef_def: compound.memberdefType, visibility: str
) -> TypedefMember:
    typedef_name = typedef_def.get_name()
    typedef_type = resolve_linked_text_name(typedef_def.get_type())[0]
    typedef_argstring = typedef_def.get_argsstring()
    typedef_definition = typedef_def.definition

    typedef_keyword = "using"
    if typedef_definition.startswith("typedef"):
        typedef_keyword = "typedef"

    typedef = TypedefMember(
        typedef_name,
        typedef_type,
        typedef_argstring,
        visibility,
        typedef_keyword,
    )

    typedef.add_template(get_template_params(typedef_def))

    return typedef


def get_concept_member(
    concept_def: compound.CompounddefType,
) -> ConceptMember:
    """
    Get the concept member from a compound definition.
    """
    concept_name = concept_def.compoundname
    concept_path = parse_qualified_path(concept_name)
    unqualified_name = concept_path[-1]

    initializer = concept_def.initializer
    constraint = ""

    if initializer:
        # The initializer contains the entire constraind definition.
        # We want to extract the constraint part after "="
        initializer_text = resolve_linked_text_name(initializer)[0]
        eq_pos = initializer_text.find("=")
        if eq_pos != -1:
            constraint = initializer_text[eq_pos + 1 :].strip()

    concept = ConceptMember(unqualified_name, constraint)
    concept.add_template(get_template_params(concept_def))

    return concept


def get_property_member(
    member_def: compound.MemberdefType,
    visibility: str,
    is_static: bool = False,
) -> PropertyMember:
    """
    Get the property member from a member definition.
    """
    property_name = member_def.get_name()
    property_type = resolve_linked_text_name(member_def.get_type())[0].strip()
    accessor = member_def.accessor if hasattr(member_def, "accessor") else None
    is_readable = getattr(member_def, "readable", "no") == "yes"
    is_writable = getattr(member_def, "writable", "no") == "yes"

    return PropertyMember(
        property_name,
        property_type,
        visibility,
        is_static,
        accessor,
        is_readable,
        is_writable,
    )


def create_enum_scope(snapshot: Snapshot, enum_def: compound.EnumdefType):
    """
    Create an enum scope in the snapshot.
    """
    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

    for enum_value_def in enum_def.enumvalue:
        value_name = enum_value_def.get_name()
        value_value = None

        if enum_value_def.initializer is not None:
            (value_value, _) = resolve_linked_text_name(enum_value_def.initializer)

        scope.add_member(
            EnumMember(
                value_name,
                value_value,
            ),
        )


def create_protocol_scope(snapshot: Snapshot, scope_def: compound.CompounddefType):
    """
    Create a protocol scope in the snapshot.
    """
    # Doxygen appends "-p" to ObjC protocol compound names
    protocol_name = scope_def.compoundname
    if protocol_name.endswith("-p"):
        protocol_name = protocol_name[:-2]

    protocol_scope = snapshot.create_protocol(protocol_name)
    base_classes = get_base_classes(scope_def, base_class=ProtocolScopeKind.Base)
    for base in base_classes:
        base.name = base.name.strip("<>")
    protocol_scope.kind.add_base(base_classes)
    protocol_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":
                        protocol_scope.add_member(
                            get_variable_member(member_def, visibility, is_static)
                        )
            elif member_type == "func":
                for function_def in section_def.memberdef:
                    protocol_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":
                        protocol_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 protocol section kind: {kind} in {scope_def.location.file}"
                )
        elif visibility == "property":
            for member_def in section_def.memberdef:
                if member_def.kind == "property":
                    protocol_scope.add_member(
                        get_property_member(member_def, "public", is_static)
                    )
        else:
            print(
                f"Unknown protocol 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.
    """
    index_path = os.path.join(xml_dir, "index.xml")
    if not os.path.exists(index_path):
        raise RuntimeError(f"Doxygen entry point not found at {index_path}")

    root = index.parse(index_path, silence=True)
    snapshot = Snapshot()

    for entry in root.compound:
        detail_file = os.path.join(xml_dir, f"{entry.refid}.xml")
        if not os.path.exists(detail_file):
            print(f"Detail file not found at {detail_file}")
            continue

        doxygen_object = compound.parse(detail_file, silence=True)

        for compound_object in doxygen_object.compounddef:
            # 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"
            ):
                class_scope = (
                    snapshot.create_struct_like(
                        compound_object.compoundname, StructLikeScopeKind.Type.CLASS
                    )
                    if compound_object.kind == "class"
                    else snapshot.create_struct_like(
                        compound_object.compoundname, StructLikeScopeKind.Type.STRUCT
                    )
                    if compound_object.kind == "struct"
                    else snapshot.create_struct_like(
                        compound_object.compoundname, StructLikeScopeKind.Type.UNION
                    )
                )

                class_scope.kind.add_base(get_base_classes(compound_object))
                class_scope.kind.add_template(get_template_params(compound_object))
                class_scope.location = compound_object.location.file

                for section_def in compound_object.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":
                                    (var_type, _) = resolve_linked_text_name(
                                        member_def.get_type()
                                    )

                                    # Skip anonymous variables
                                    if "@" in var_type:
                                        continue

                                    if var_type == "friend":
                                        class_scope.add_member(
                                            FriendMember(
                                                member_def.get_name(), visibility
                                            )
                                        )
                                    else:
                                        class_scope.add_member(
                                            get_variable_member(
                                                member_def, visibility, is_static
                                            )
                                        )
                        elif member_type == "func":
                            for function_def in section_def.memberdef:
                                class_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":
                                    class_scope.add_member(
                                        get_typedef_member(member_def, visibility)
                                    )
                                else:
                                    print(
                                        f"Unknown section member kind: {member_def.kind} in {compound_object.location.file}"
                                    )
                        else:
                            print(
                                f"Unknown class section kind: {kind} in {compound_object.location.file}"
                            )
                    elif visibility == "friend":
                        # Ignore friend declarations, they are not meaningful for the public API surface
                        pass
                    elif visibility == "property":
                        print(
                            f"Property not supported: {compound_object.compoundname} in {compound_object.location.file}"
                        )
                    else:
                        print(
                            f"Unknown class visibility: {visibility} in {compound_object.location.file}"
                        )
            elif compound_object.kind == "namespace":
                # Skip anonymous namespaces (internal linkage, not public API).
                # Doxygen encodes them with a '@' prefix in the compound name.
                if "@" in compound_object.compoundname:
                    continue

                namespace_scope = snapshot.create_or_get_namespace(
                    compound_object.compoundname
                )

                namespace_scope.location = compound_object.location.file

                for section_def in compound_object.sectiondef:
                    if section_def.kind == "var":
                        for variable_def in section_def.memberdef:
                            is_static = variable_def.static == "yes"
                            namespace_scope.add_member(
                                get_variable_member(variable_def, "public", is_static)
                            )
                    elif section_def.kind == "func":
                        for function_def in section_def.memberdef:
                            function_static = function_def.static == "yes"

                            if not function_static:
                                namespace_scope.add_member(
                                    get_function_member(function_def, "public")
                                )
                    elif section_def.kind == "typedef":
                        for typedef_def in section_def.memberdef:
                            namespace_scope.add_member(
                                get_typedef_member(typedef_def, "public")
                            )
                    elif section_def.kind == "enum":
                        for enum_def in section_def.memberdef:
                            create_enum_scope(snapshot, enum_def)
                    else:
                        print(
                            f"Unknown section kind: {section_def.kind} in {compound_object.location.file}"
                        )
            elif compound_object.kind == "concept":
                # Concepts belong to a namespace, so we need to find or create the parent namespace
                concept_name = compound_object.compoundname
                concept_path = parse_qualified_path(concept_name)
                namespace_path = "::".join(concept_path[:-1]) if concept_path else ""

                if namespace_path:
                    namespace_scope = snapshot.create_or_get_namespace(namespace_path)
                else:
                    namespace_scope = snapshot.root_scope

                namespace_scope.add_member(get_concept_member(compound_object))
            elif compound_object.kind == "file":
                pass
            elif compound_object.kind == "dir":
                pass
            elif compound_object.kind == "category":
                print(f"Category not supported: {compound_object.compoundname}")
            elif compound_object.kind == "page":
                # Contains deprecation info
                pass
            elif compound_object.kind == "protocol":
                create_protocol_scope(snapshot, compound_object)
            else:
                print(f"Unknown compound kind: {compound_object.kind}")

    snapshot.finish()
    return snapshot