"""Resource node for hierarchical API structure.

This module defines the ResourceNode dataclass used to represent the tree structure
of API namespaces in the CATAPA API.

Each node represents a resource in the API path hierarchy and stores its full resource chain
from root as a list of identifiers for easy manipulation.

References:
    NONE
"""

from dataclasses import dataclass
from typing import List


@dataclass(frozen=True)
class ResourceNode:
    """Node representing a resource in the API namespace hierarchy.

    Stores the complete resource chain from root as a list of identifiers, with all other
    attributes derived from this canonical representation.

    A ResourceNode can be:
    - Namespace node: has children (intermediate level)
    - API node: is_api=True (maps to an API class)
    - Hybrid node: both of the above

    Attributes:
        resource_chain: Full chain from root as list (e.g., ["core", "employees"])
        description: Full description from OpenAPI spec for docstrings
        children: List of child ResourceNode instances
        is_api: Whether this node corresponds to an actual API endpoint.

    Example:
        Root:  ResourceNode(resource_chain=["core"], ...)
        Child: ResourceNode(resource_chain=["core", "employees"], ...)
    """

    resource_chain: List[str]
    description: str
    children: List["ResourceNode"]
    is_api: bool = False

    @property
    def resource_name(self) -> str:
        """Get just this resource name (last element of chain).

        Returns:
            Last segment of the chain (e.g., "employees" from ["core", "employees"])
        """
        return self.resource_chain[-1]

    @property
    def attribute_name(self) -> str:
        """Convert resource name to Python attribute name.

        Returns:
            Snake_case attribute name for Python access (e.g., "employees")
        """
        # Resource names are already sanitized in parsing, ensure lowercase
        return self.resource_name.lower()

    @property
    def namespace(self) -> str:
        """Get namespace path in dot notation.

        Returns:
            Dot-separated namespace path (e.g., "core.employees")
        """
        return ".".join(self.resource_chain)

    def get_api_class_name(self) -> str:
        """Generate the API class name.

        Returns:
            PascalCase API class name with 'Api' suffix (e.g., "CoreEmployeesApi")
        """
        pascal_case = "".join(part.capitalize() for segment in self.resource_chain for part in segment.split("_"))
        return f"{pascal_case}Api"
